.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
        
    • 设备存在于工作组中或备用域中, () 的远程计算机: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
    • 允许通过客户端防火墙执行 ICMPv4Allow 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
    • 允许通过客户端防火墙执行 ICMPv4Allow 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.

将按照在 entry.ps1 脚本中输入的顺序来转换打包为 .msix 应用程序格式的应用。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 文件后,在目标设备上执行 MsixPackagingTool.exe 来转换应用并将其放在位于脚本执行文件夹中的 .\Out文件夹中的新 PowerShell 进程中执行run_job.ps1脚本。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.

parametersParameters

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.

LoggingLogging

此脚本将生成一个日志文件,其中概述了在脚本执行过程中早于当前的内容。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.