MSIX 大量轉換腳本MSIX Bulk conversion scripts

您可以使用 MSIX 工具組中的 大量轉換腳本 ,將 Windows 應用程式轉換成 MSIX 封裝格式。The Bulk conversion scripts in the MSIX Toolkit can be used to automate the conversion of Windows apps to the MSIX package format. entry.ps1的腳本中會提供應用程式清單及其詳細資料。The list of apps and their details are provided in the entry.ps1 script.

準備機器以進行轉換Prepare machines for conversion

執行 MSIX 工具組的大量轉換腳本之前,若要自動將您的應用程式轉換成 MSIX 封裝格式,您將使用 (虛擬或遠端) 的裝置,必須設定為允許遠端通訊,並已安裝 MSIX 封裝工具。Prior to running the MSIX Toolkit's Bulk Conversion script, to automate the conversion of your application to the MSIX packaging format the devices that you will be using (virtual, or remote) must be configured to allow remote communication, and have the MSIX Packaging Tool installed.

字詞Term 描述Description
主機電腦Host Machine 這是執行大量轉換腳本的裝置。This is the device executing the Bulk Conversion scripts.
虛擬機器Virtual Machine 這是 Hyper-v 中的現有裝置,裝載于主機電腦上。This is a device existing in Hyper-V, hosted on the Host Machine.
遠端電腦Remote Machine 這是可透過網路存取的實體或虛擬機器。This is a physical or virtual machine accessible over the network.

主機電腦Host Machine

主機電腦必須符合下列需求:The Host Machine must meet the following requirements:

  • 必須安裝MSIX 封裝工具MSIX Packaging Tool must be installed.
  • 如果正在使用虛擬機器,則必須安裝 Hyper-v。If Virtual Machines are being used, Hyper-V must be installed.
  • 如果正在使用遠端電腦:If Remote Machines are being used:
    • 裝置存在於與遠端電腦 (的相同網域中) :Device exists in the same Domain as the Remote Machine(s):
      • 啟用 PowerShell 遠端Enable PowerShell Remoting
        # Enables PowerShell Remoting
        Enable-PSRemoting -force
        
    • 裝置存在於工作組或替代網域中,作為遠端電腦的 (s) :Device exists in a Workgroup or to an alternate Domain as the Remote Machine(s):
      • 啟用 PowerShell 遠端Enable PowerShell remoting
      • WinRM 受信任的主機必須包含遠端電腦的裝置名稱或 IP 位址WinRM Trusted Host must contain the device name or IP address of the Remote Machine
        # Enables PowerShell Remoting
        Enable-PSRemoting -force
        Set-Item WSMan:\localhost\Client\TrustedHosts -Value <RemoteMachineName>,[<RemoteMachineName>,...]
        

遠端電腦Remote Machine

遠端電腦必須符合下列需求:The Remote Machine must meet the following requirements:

  • 必須安裝MSIX 封裝工具MSIX Packaging Tool must be installed.

  • 如果裝置存在於與主機電腦相同的網域中:If the device exists within the same domain as the Host Machine:

    • 啟用 PowerShell 遠端Enable PowerShell Remoting
    • 必須啟用 WinRMWinRM must be enabled
    • 允許 ICMPv4 通過用戶端防火牆Allow ICMPv4 through client firewall
      # Enables PowerShell Remoting
      Enable-PSRemoting -force
      New-NetFirewallRule -DisplayName “ICMPv4” -Direction Inbound -Action Allow -Protocol icmpv4 -Enabled True
      
  • 如果裝置存在於工作組或替代網域中作為主機電腦:If the device exists within a workgroup or an alternate domain as the Host Machine:

    • 啟用 PowerShell 遠端Enable PowerShell Remoting
    • WinRM 受信任的主機必須包含裝置名稱或主機電腦的 IP 位址WinRM Trusted Host must contain the device name or the IP address of the Host Machine
    • 允許 ICMPv4 通過用戶端防火牆Allow ICMPv4 through client firewall
      # Enables PowerShell Remoting
      Enable-PSRemoting -force
      New-NetFirewallRule -DisplayName “ICMPv4” -Direction Inbound -Action Allow -Protocol icmpv4 -Enabled True
      Set-Item WSMan:\localhost\Client\TrustedHosts -Value <HostMachineName>
      
      

虛擬機器Virtual Machine

建議您使用 Hyper-v 快速建立「MSIX 封裝工具環境」映射,因為它已預先設定為符合所有需求。It is recommended that the Hyper-V Quick Create "MSIX Packaging Tools Environment" image be used, as it is pre-configured to meet all requirements. 虛擬機器必須裝載于主機電腦上,並在 Microsoft Hyper-V 內執行。The virtual machine must be hosted on the Host Machine and running within Microsoft Hyper-V.

虛擬機器必須符合下列需求:The Virtual Machine must meet the following requirements:

語法Syntax

entry.ps1

描述Description

這是一組 PowerShell 腳本,可讓您將應用程式大量封裝成 MSIX 封裝格式。This is a set of PowerShell scripts that provides the ability to bulk package applications into the MSIX package format. 這些腳本會連接到將用來封裝每個應用程式的本機虛擬機器或遠端電腦。These scripts will connect to a local virtual machine or remote machine which will be used to package each application.

封裝至 MSIX 應用程式格式的應用程式將會依照 entry.ps1 腳本中輸入的順序進行轉換。Apps being packaged into the MSIX application format will be converted in the order they were entered in the entry.ps1 script. entry.ps1腳本中列出的遠端電腦將用來將應用程式封裝成 MSIX 格式,將會權責使用。Remote machines listed in the entry.ps1 script will be used to package the applications into the MSIX format will be singularly used. 虛擬機器可以多次使用,將不同的應用程式封裝成 MSIX 應用程式格式。Virtual machines can be used multiple times to package different applications into the MSIX application format.

執行腳本之前,您必須先將想要轉換的應用程式新增至 conversionsParameters 腳本中的變數。Before running the script, you must first add the apps you want to convert to the conversionsParameters variable in the script. 您可以將多個應用程式加入至變數。Multiple apps can be added to the variable. 腳本會利用應用程式和遠端/虛擬機器來建立格式化的 XML 檔案,以符合 MSIX 封裝工具 ( # A0) 的需求。The script leverages the app and remote/virtual machines to create a XML file formatted to meet the requirements of the MSIX Packaging Tool (MsixPackagingTool.exe). 建立 XML 檔案之後, run_job.ps1 腳本會在新的 PowerShell 進程中執行,此程式會在目標裝置上執行 MsixPackagingTool.exe 來轉換應用程式,並將它放在位於腳本執行資料夾中的 .\Out 資料夾。After creating the XML file, the run_job.ps1 script is executed in a new PowerShell process which executes MsixPackagingTool.exe on the target device to convert the app and place it in the .\Out folder located in the script execution folder.

範例Example

PS C:\> entry.ps1

此範例會執行 entry.ps1 腳本。Ths example executes the entry.ps1 script. 此腳本會將變數中指定的應用程式轉換 conversionsParameters 成 MSIX 封裝。This script converts the apps specified in the conversionsParameters variable into MSIX packages. 應用程式會使用 virtualMachinesremoteMachines 變數中指出的虛擬機器或遠端電腦進行轉換。The apps are converted using the virtual machines or remote machines indicated in the virtualMachines and remoteMachines variables.

參數Parameters

virtualMachinesvirtualMachines

virtualMachines參數是一個陣列,其中包含要連線的虛擬機器名稱和認證,以及將應用程式封裝成 MSIX 格式時的存取權。The virtualMachines parameter is an array that contains the name and credentials of the virtual machines to connect to and access when packaging an app into the MSIX format.

  • 輸入: 陣 列Type: Array
  • 必要:Required: No
$virtualMachines = @(
    @{
        Name = "MSIX Packaging Tool Environment";   # Name of the virtual machine as listed in the Hyper-V Management console
        Credential = $credential                    # Credentials used to connect/login to the virtual machine.
    }
)

指定的虛擬機器將用來將應用程式封裝為 MSIX 格式。The specified virtual machine will be used to package apps into the MSIX format. 此虛擬機器將會使用提示時所輸入的認證來連接, (提示字元會在腳本 entry.ps1 執行) 之後直接出現。This virtual machine will be connected to using the credentials entered when prompted (prompt appears directly after script entry.ps1 execution). 在將應用程式封裝成 MSIX 封裝格式之前,腳本會建立 Hyper-v VM 的快照集,然後在封裝應用程式之後還原至此快照集。Prior to packaging an application to the MSIX packaging format, the script will create a snapshot of the Hyper-V VM, and then restored to this snapshot after application has been packaged.

remoteMachinesremoteMachines

remoteMachines 參數是一個陣列,其中包含將應用程式封裝成 MSIX 格式時,所要連接和存取的遠端電腦名稱稱和認證。The remoteMachines parameter is an array that contains the name and credentials of the remote machines to connect to and access when packaging an app into the MSIX format. 指定的遠端電腦將會是用來封裝單一應用程式的單一使用裝置。The remote machines specified will be single-use devices used to package a single application.

遠端電腦必須可在網路上存取及探索。Remote machines must be accessible and discoverable on the network.

  • 輸入: 陣 列Type: Array
  • 必要:Required: No
$remoteMachines = @(
    @{
        ComputerName = "Computer.Domain.com";   # The fully qualified name of the remote machine.
        Credential = $credential }              # Credentials used to connect/login to the remote machine.
)

指定的遠端電腦將會用來將單一應用程式封裝為 MSIX 格式。The specified remote machine will be used to package a single app into the MSIX format. 此遠端電腦將會使用提示時所輸入的認證來連接, (提示字元會在腳本 entry.ps1 執行) 之後直接出現。This remote machine will be connected to using the credentials entered when prompted (prompt appears directly after script entry.ps1 execution).

entry.ps1 腳本執行之前,請先確認裝置的完整功能變數名稱或對外別名可解析。Ensure that the fully qualified domain name or externally facing alias of the device is resolvable prior to execution of the entry.ps1 script.

signingCertificatesigningCertificate

signingCertificate參數是一個陣列,其中包含將用來簽署 MSIX 封裝應用程式之程式碼簽署憑證的相關資訊。The signingCertificate parameter is an array that contains information related to the code signing certificate that will be used to sign the MSIX packaged application. 此憑證的加密層級至少必須是 SHA256。This certificate must have an encryption level of at minimum SHA256.

  • 輸入: 陣 列Type: Array
  • 必要:Required: No
$SigningCertificate = @{
    Password = "Password"; 
    Path = "C:\Temp\ContosoLab.pfx"
}

conversionsParametersconversionsParameters

conversionsParameters參數是一個陣列,其中包含您想要轉換成 MSIX 格式的應用程式相關資訊。The conversionsParameters parameter is an array that contains information about the apps you want to convert to MSIX format. 陣列中的每個應用程式都會個別進行剖析,並透過遠端電腦或虛擬機器上的 MSIX 封裝轉換來執行。Each app in the array will be parsed individually and run through the MSIX package conversion on either a remote machine or virtual machine. 應用程式會以它們出現在腳本中的順序進行轉換。The apps will be converted in the order that they appear in the script. 如果轉換成 MSIX 格式失敗,腳本就不會重新嘗試將應用程式轉換成不同的遠端電腦或虛擬機器。If the conversion to MSIX format fails, the script will not re-attempt to convert the application on a different remote machine or virtual machine.

  • 輸入: 陣 列Type: Array
  • 必要︰Required: Yes
$conversionsParameters = @(
    ## Use for MSI applications:
    @{
        InstallerPath = "C:\Path\To\YourInstaller.msi";    # Full path to the installation media (local or remote paths).
        PackageName = "YourApp";                           # Application Display Name - name visible in the start menu.
        PackageDisplayName = "Your App";                   # Application Name - Can not contain special characters.
        PublisherName = "CN=YourCompany";                  # Certificate Publisher information - must match signing certificate
        PublisherDisplayName = "YourCompany";              # Application Publisher name
        PackageVersion = "1.0.0.0"                         # MSIX Application version (must contain 4 octets).
    },
    ## Use for EXE or other applications:
    @{
        InstallerPath = "Path\To\YourInstaller.exe";       # Full path to the installation media (local or remote paths).
        PackageName = "YourApp";                           # Application Display Name - name visible in the start menu.
        PackageDisplayName = "Your App";                   # Application Name - Can not contain special characters.
        PublisherName = "CN=YourCompany";                  # Certificate Publisher information - must match signing certificate
        PublisherDisplayName = "YourCompany";              # Application Publisher name
        PackageVersion = "1.0.0.0";                        # MSIX Application version (must contain 4 octets).
        InstallerArguments = "/SilentInstallerArguement"   # Arguements required by the installer to provide a silent installation of the application.
    },
    ## Creating the Packaged app and Template file in a specific folder path:
    @{
        InstallerPath = "Path\To\YourInstaller.exe";       # Full path to the installation media (local or remote paths).
        PackageName = "YourApp";                           # Application Display Name - name visible in the start menu.
        PackageDisplayName = "Your App";                   # Application Name - Can not contain special characters.
        PublisherName = "CN=YourCompany";                  # Certificate Publisher information - must match signing certificate
        PublisherDisplayName = "YourCompany";              # Application Publisher name
        PackageVersion = "1.0.0.0";                        # MSIX Application version (must contain 4 octets).
        InstallerArguments = "/SilentInstallerArguement";  # Arguements required by the installer to provide a silent installation of the application.
        SavePackagePath = "Custom\folder\Path";            # Specifies a custom folder path where the MSIX app will be created.
        SaveTemplatePath = "Custom\folder\Path"            # Specifies a custom folder path where the MSIX Template XML will be created.
    }
)

變數中提供的應用程式資訊 conversionsParameters 將用來產生 XML 檔案,其中包含所有必要的應用程式詳細資料。The app information provided in the conversionsParameters variable will be used to generate an XML file with all of the required application details. 建立 XML 檔案之後,腳本會將 XML 檔案傳遞至 MSIX 封裝工具 , ( # A0) 以進行封裝。After creating the XML file, the script will then pass the XML file to the MSIX Packaging Tool (MsixPackagingTool.exe) to be packaged.

記錄Logging

腳本會產生記錄檔,其中會概述在腳本執行期間過了的內容。The script will generate a log file which outlines what has transpired throughout the script execution. 記錄檔將提供與應用程式封裝的相關詳細資料,以 MSIX 封裝格式,以及與腳本進展相關的資訊。The log file will provide details related to the packaging of applications to the MSIX packaging format, and information related to script progression. 您可以從任何文字公用程式讀取記錄,但已設定為使用 Trace32 記錄讀取器進行讀取。The logs can be read from any text utility, but have been configured for reading using the Trace32 log reader. 腳本執行中的錯誤會反白顯示為紅色,警告則會顯示為黃色。Errors in the script execution will be highlighted as Red, and Warnings as yellow. 如需追蹤32記錄讀取器的詳細資訊,請流覽 Microsoft Docs 上的 CMTraceFor more information on the Trace 32 log reader, please visit CMTrace on Microsoft Docs.

記錄檔會建立在腳本的目錄內 .\logs\BulkConversion.logThe log file is created within the script's directory .\logs\BulkConversion.log.