使用 Desktop App Converter 打包桌面应用程序Package a desktop application using the Desktop App Converter

备注

现已弃用 Desktop App Converter 工具。The Desktop App Converter tool is deprecated. 建议改用 MSIX 打包工具We recommend that you use the MSIX Packaging Tool instead.

DAC 图标

Desktop App Converter (DAC) 创建桌面应用程序的包以便与最新 Windows 功能集成,包括通过 Microsoft Store 实现分发和提供服务。The Desktop App Converter (DAC) creates packages for desktop applications to integrate with the latest Windows features, including distribution and servicing via the Microsoft Store. 这包括 Win32 应用和使用 .NET 4.6.1 创建的应用。This includes Win32 apps and apps that you've created by using .NET 4.6.1.

获取桌面应用转换器Get the Desktop App Converter

尽管此工具名称中出现了“Converter”一词,但它实际上并不转换你的应用。While the term "Converter" appears in the name of this tool, it doesn't actually convert your app. 你的应用程序会保持不变。Your application remains unchanged. 但是,此工具会生成一个带有应用包标识并能够调用各种 WinRT API 的 Windows 应用包。However, this tool generates a Windows app package with a package identity and the ability to call a vast range of WinRT APIs.

可以通过使用 Add-AppxPackage PowerShell cmdlet 在开发计算机上安装该程序包。You can install that package by using the Add-AppxPackage PowerShell cmdlet on your development machine.

转换器使用转换器下载项中提供的干净基本映像在隔离的 Windows 环境中运行桌面安装程序。The converter runs the desktop installer in an isolated Windows environment by using a clean base image provided as part of the converter download. 它捕获桌面安装程序进行的任何注册表和文件系统 I/O,并将其作为输出的一部分打包。It captures any registry and file system I/O made by the desktop installer and packages it as part of the output.

重要

Windows 10 版本 1607 及更高版本支持桌 Desktop App Converter。Desktop App Converter is supported on Windows 10, version 1607, and later. 在 Visual Studio 中,它只能用于面向 Windows 10 周年更新(10.0;内部版本 14393)或更高版本的项目中。It can only be used in projects that target Windows 10 Anniversary Update (10.0; Build 14393) or a later release in Visual Studio.

DAC 不仅能为你生成一个包The DAC does more than just generate a package for you

它还可以为你执行以下操作。Here's a few extra things it can do for you.

Windows 10 创意者更新Windows 10 Creators Update

✔️自动注册预览控件、缩略图处理程序、属性处理程序、防火墙规则、URL 标志。Automatically register your preview handlers, thumbnail handlers, property handlers, firewall rules, URL flags.

✔️自动注册使用户能够使用“文件资源管理器”中的“种类”列对文件进行分组的文件类型映射。 Automatically register file type mappings that enable users to group files by using the Kind column in File Explorer.

✔️注册你的公共 COM 服务器。Register your public COM servers.

Windows 10 周年更新或更高版本Windows 10 Anniversary Update or later

✔️自动对程序包进行签名,使你能够测试你的应用。Automatically sign your package so that you can test your app.

✔️针对打包应用和 Microsoft Store 要求验证应用程序。Validate your application against packaged app and Microsoft Store requirements.

若要查找完整的选项列表,请参阅本指南的参数部分。To find a complete list of options, see the Parameters section of this guide.

如果你已准备好创建应用包,那我们开始吧。If you're ready to create your package, let's start.

首先,准备应用程序First, prepare your application

在开始为应用程序创建程序包之前请查看此指南:准备打包桌面应用程序Review this guide before you begin creating a package for your application: Prepare to package a desktop application.

请确保你的系统可以运行转换器Make sure that your system can run the converter

请确保你的系统满足以下要求:Make sure that your system meets the following requirements:

启动 Desktop App ConverterStart the Desktop App Converter

  1. 下载并安装 Desktop App ConverterDownload and install the Desktop App Converter.

  2. 以管理员身份运行 Desktop App Converter。Run the Desktop App Converter as an administrator.

    以管理员身份运行 DAC

    会出现一个控制台窗口。A console window appears. 你需要使用该控制台窗口运行命令。You'll use that console window to run commands.

进行一些设置(仅限具有安装程序的应用)Set a few things up (apps with installers only)

如果你的应用程序没有安装程序,可以跳到下一部分。You can skip ahead to the next section if your application doesn't have an installer.

  1. 识别操作系统的版本号。Identify the version number of your operating system.

    若要执行该操作,请在“运行”对话框中键入“winver”,然后选择“确定”按钮。 To do that, type winver in the Run dialog box, and then choose the OK button.

    winver

    可以在“关于 Windows”对话框中找到你的 Windows 版本。 You'll find the version of your Windows build in the About Windows dialog box.

    Windows 10 版本

  2. 下载相应的 Desktop App Converter 基础映像Download the appropriate Desktop app Converter base image.

    确保文件名中显示的版本号与 Windows 内部版本的版本号相匹配。Make sure that the version number that appears in the name of the file matches the version number of your Windows build.

    重要

    如果使用的是版本 15063,则该版本的次要版本等于或大于 .483(例如: 15063.540),请确保下载 BaseImage-15063-UPDATE.wim 文件。 If you're using build number 15063, and the minor version of that build is equal to or greater than .483 (For example: 15063.540), make sure to download the BaseImage-15063-UPDATE.wim file. 如果该版本的次要版本小于 .483,请下载 BaseImage-15063.wim 文件。 If the minor version of that build is less than .483, download the BaseImage-15063.wim file. 如果已设置此基文件的不兼容版本,则可以解决此问题。If you've already setup an incompatible version of this base file, you can fix it. 这篇博客文章介绍了如何解决此问题。This blog post explains how to do that.

  3. 将下载的文件放置在你稍后可在计算机上找到它的任意位置。Place the downloaded file anywhere on your computer where you'll be able to find it later.

  4. 在启动 Desktop App Converter 时出现的控制台窗口中,运行此命令:Set-ExecutionPolicy bypassIn the console window that appeared when you started the Desktop App Converter, run this command: Set-ExecutionPolicy bypass.

  5. 通过运行此命令设置转换器:DesktopAppConverter.exe -Setup -BaseImage .\BaseImage-1XXXX.wim -VerboseSet up the converter by running this command: DesktopAppConverter.exe -Setup -BaseImage .\BaseImage-1XXXX.wim -Verbose.

  6. 如果系统提示你重启计算机,请执行此操作。Restart your computer if you're prompted to do so.

    当转换器展开基础映像时,控制台窗口中会显示状态消息。Status messages appear in the console window as the converter expands the base image. 如果未看到任何状态消息,请按任意键。If you don't see any status messages, press any key. 此操作可以刷新控制台窗口的内容。This can cause the contents of the console window to refresh.

    控制台窗口中的状态消息

    当基础映像完全展开后,请转至下一部分。When the base image is fully expanded, move to the next section.

将应用打包Package an app

若要将应用打包,请在启动 Desktop App Converter 时打开的控制台窗口中运行 DesktopAppConverter.exe 命令。To Package your app, run the DesktopAppConverter.exe command in the console window that opened when you started the Desktop App Converter.

你将通过使用参数指定应用程序的包名称、发布者和版本号。You'll specify the package name, publisher and version number of the application by using parameters.

备注

如果已在 Microsoft Store 中保留了应用名称,可以使用合作伙伴中心获取包名称和发布者名称。If you've reserved your app name in the Microsoft Store, you can obtain the package and publisher names by using Partner Center. 如果你打算将应用旁加载到其他系统上,只要选择的发布者名称与用于对应用进行签名的证书上的名称相匹配,就可以提供自己的名称。If you plan to sideload your app onto other systems, you can provide your own names for these as long as the publisher name that you choose matches the name on the certificate you use to sign your app.

命令参数概览A quick look at command parameters

以下是所需参数。Here are the required parameters.

DesktopAppConverter.exe
-Installer <String>
-Destination <String>
-PackageName <String>
-Publisher <String>
-Version <Version>

可以在此处阅读有关每个参数的信息。You can read about each one here.

示例Examples

以下是将应用打包的一些常见方法。Here's a few common ways to package your app.

打包具有安装程序 (.msi) 文件的应用程序Package an application that has an installer (.msi) file

使用 Installer 参数指向安装程序文件。Point to the installer file by using the Installer parameter.

DesktopAppConverter.exe -Installer C:\Installer\MyAppSetup.msi -Destination C:\Output\MyApp -PackageName "MyApp" -Publisher "CN=MyPublisher" -Version 0.0.0.1

重要

以下是在执行此操作时要记住的两个重要事项。There are two important things to keep in mind here. 首先,请确保安装程序位于独立文件夹中,并确保只有与该安装程序相关的文件位于同一文件夹中。First, make sure that your installer is located in an independent folder and that only files related to that installer are in the same folder. 转换器将该文件夹的所有内容复制到隔离的 Windows 环境中。The converter copies all of the contents of that folder to the isolated Windows environment.
其次,如果合作伙伴中心为你的程序包分配了以数字开头的标识,请确保还要传入 -AppId 参数,并且仅使用字符串后缀(在句点分隔符之后)作为该参数的值。Secondly, if Partner Center assigns an identity to your package that begins with a number, make sure that you also pass in the -AppId parameter, and use only the string suffix (after the period separator) as the value of that parameter.

如果你的安装程序包括相关库或框架的安装程序,则组织内容的方式可能略有不同。If your installer includes installers for dependent libraries or frameworks, you might have to organize things a bit a differently. 请参阅用桌面桥链连多个安装程序See Chaining multiple installers with the Desktop Bridge.

打包具有安装程序可执行文件的应用程序Package an application that has a setup executable file

使用 Installer 参数指向安装程序可执行文件。Point to the setup executable by using the Installer parameter.

DesktopAppConverter.exe -Installer C:\Installer\MyAppSetup.exe -InstallerArguments "/S" -Destination C:\Output\MyApp -PackageName "MyApp" -Publisher "CN=MyPublisher" -Version 0.0.0.1

重要

如果合作伙伴中心为你的程序包分配了以数字开头的标识,请确保还要传入 -AppId 参数,并且仅使用字符串后缀(在句点分隔符之后)作为该参数的值。If Partner Center assigns an identity to your package that begins with a number, make sure that you also pass in the -AppId parameter, and use only the string suffix (after the period separator) as the value of that parameter.

InstallerArguments 参数是可选参数。The InstallerArguments parameter is an optional parameter. 但是,因为 Desktop App Converter 需要安装程序在无人参与模式下运行,因此如果你的应用程序需要无提示标志以静默方式运行,则可能需要使用该参数。However, because the Desktop App Converter needs your installer to run in unattended mode, you might have to use it if your application needs silent flags to run silently. /S 标志是十分常见的无提示标志,但你使用的标志可能有所不同,具体取决于用于创建安装程序文件的安装程序技术。The /S flag is a very common silent flag, but the flag that you use might be different depending on which installer technology you used to create the setup file.

打包没有安装程序的应用程序Package an application that doesn't have an installer

在此示例中,使用 Installer 参数指向应用程序文件的根文件夹。In this example, use the Installer parameter to point to the root folder of your application files.

使用 AppExecutable 参数指向应用可执行文件。Use the AppExecutable parameter to point to your apps executable file.

DesktopAppConverter.exe -Installer C:\Installer\MyApp\ -AppExecutable MyApp.exe -Destination C:\Output\MyApp -PackageName "MyApp" -Publisher "CN=MyPublisher" -Version 0.0.0.1

重要

如果合作伙伴中心为你的程序包分配了以数字开头的标识,请确保还要传入 -AppId 参数,并且仅使用字符串后缀(在句点分隔符之后)作为该参数的值。If Partner Center assigns an identity to your package that begins with a number, make sure that you also pass in the -AppId parameter, and use only the string suffix (after the period separator) as the value of that parameter.

将应用打包、对应用进行签名并对应用包运行验证检查Package an app, sign the app, and run validation checks on the package

此示例类似于第一个示例,不同之处在于它显示了如何对应用程序进行签名以进行本地测试,然后根据打包应用和 Microsoft Store 的要求验证你的应用程序。This example is similar to first one except it shows how you can sign your application for local testing, and then validate your application against packaged app and Microsoft Store requirements.

DesktopAppConverter.exe -Installer C:\Installer\MyAppSetup.exe -InstallerArguments "/S" -Destination C:\Output\MyApp -PackageName "MyApp" -Publisher "CN=MyPublisher" -Version 0.0.0.1 -MakeAppx -Sign -Verbose -Verify

重要

如果合作伙伴中心为你的程序包分配了以数字开头的标识,请确保还要传入 -AppId 参数,并且仅使用字符串后缀(在句点分隔符之后)作为该参数的值。If Partner Center assigns an identity to your package that begins with a number, make sure that you also pass in the -AppId parameter, and use only the string suffix (after the period separator) as the value of that parameter.

Sign 参数生成一个证书,然后使用该证书对应用程序进行签名。The Sign parameter generates a certificate and then signs your application with it. 若要运行应用,你需要安装生成的证书。To run your app, you'll have to install that generated certificate. 若要了解如何操作,请参阅本指南的运行已打包的应用部分。To learn how, see the Run the packaged app section of this guide.

可以使用 Verify 参数验证你的应用程序。You can validate you application by using the Verify parameter.

可选参数概览A quick look at optional parameters

SignVerify 参数是可选参数。The Sign and Verify parameters are optional. 还有更多的可选参数。There are many more optional parameters. 以下是一些更常用的可选参数。Here are some of the more commonly used optional parameters.

[-ExpandedBaseImage <String>]
[-AppExecutable <String>]
[-AppFileTypes <String>]
[-AppId <String>]
[-AppDisplayName <String>]
[-AppDescription <String>]
[-PackageDisplayName <String>]
[-PackagePublisherDisplayName <String>]
[-MakeAppx]
[-LogFile <String>]
[<CommonParameters>]

可以在下一部分中阅读有关所有参数的信息。You can read about all of them in the next section.

参数引用Parameter Reference

以下是运行 Desktop App Converter 时可使用的参数的完整列表(按类别列出)。Here's the complete list of parameters (organized by category) that you can use when you run the Desktop App Converter.

还可以通过在应用控制台窗口中运行 Get-Help 命令来查看整个列表。You can also view the entire list by running the Get-Help command in the app console window.

设置参数Setup parameters
-Setup [<SwitchParameter>]-Setup [<SwitchParameter>] 必需Required 在设置模式下运行 DesktopAppConverter。Runs DesktopAppConverter in setup mode. 设置模式支持扩展所提供的基本映像。Setup mode supports expanding a provided base image.
-BaseImage <String>-BaseImage <String> 必需Required 未扩展的基本映像的完整路径。Full path to an unexpanded base image. 如果指定 -Setup,则需要此参数。This parameter is required if -Setup is specified.
-LogFile <String>-LogFile <String> 可选Optional 指定日志文件。Specifies a log file. 如果省略,将创建一个日志文件临时位置。If omitted, a log file temporary location will be created.
-NatSubnetPrefix <String>-NatSubnetPrefix <String> 可选Optional 用于 Nat 实例的前缀值。Prefix value to be used for the Nat instance. 通常,仅在主机连接到与转换器的 NetNat 相同的子网范围时,你会希望更改此值。Typically, you would want to change this only if your host machine is attached to the same subnet range as the converter's NetNat. 你可以通过使用 Get-NetNat cmdlet 查询当前转换器 NetNat 配置。You can query the current converter NetNat config by using the Get-NetNat cmdlet.
-NoRestart [<SwitchParameter>]-NoRestart [<SwitchParameter>] 必需Required 在运行设置时不要提示重启(需要重启才能启用容器功能)。Don't prompt for reboot when running setup (reboot is required to enable the container feature).
转换参数Conversion parameters
-AppInstallPath <String>-AppInstallPath <String> 可选Optional 应用程序针对已安装文件(如果已安装)的根文件夹的完整路径(例如“C:\Program Files (x86)\MyApp”)。The full path to your application's root folder for the installed files if it were installed (e.g., "C:\Program Files (x86)\MyApp").
-Destination <String>-Destination <String> 必需Required 如果转换器的 appx 输出的所需目标尚未存在,DesktopAppConverter 可以创建此位置。The desired destination for the converter's appx output - DesktopAppConverter can create this location if it doesn't already exist.
-Installer <String>-Installer <String> 必需Required 应用程序的安装程序的路径 - 必须能够在无人参与/无提示的情况下运行。The path to the installer for your application - must be able to run unattended/silently. 无安装程序的转换,这是应用程序文件的根目录的路径。No-installer conversion, this is the path to the root directory of your application files.
-InstallerArguments <String>-InstallerArguments <String> 可选Optional 用于强制安装程序在无人参与/无提示的情况下运行的参数的逗号分隔列表或字符串。A comma-separated list or string of arguments to force your installer to run unattended/silently. 如果安装程序是 msi,则此参数为可选参数。This parameter is optional if your installer is an msi. 若要从安装程序中获取日志,请在此处为安装程序提供日志记录参数,并使用路径 <log_folder>,该路径是转换器使用相应路径所替换的标记。To get a log from your installer, supply the logging argument for the installer here and use the path <log_folder>, which is a token that the converter replaces with the appropriate path.

注意:无人参与/无提示标志和日志参数将因安装程序技术而有所不同。NOTE: The unattended/silent flags and log arguments will vary between installer technologies.

此参数的示例用法:-InstallerArguments "/silent /log <log_folder>\install.log" 另一个不生成日志文件的示例如下所示:-InstallerArguments "/quiet", "/norestart" 再次强调,如果希望转换器捕获日志并将其放入最终日志文件夹,就必须将任何日志直接定向到令牌路径 <log_folder>。An example usage for this parameter: -InstallerArguments "/silent /log <log_folder>\install.log" Another example that doesn't produce a log file may look like: -InstallerArguments "/quiet", "/norestart" Again, you must literally direct any logs to the token path <log_folder> if you want the converter to capture it and put it in the final log folder.
-InstallerValidExitCodes <Int32>-InstallerValidExitCodes <Int32> 可选Optional 指示安装程序成功运行的退出代码的逗号分隔列表(例如:0, 1234, 5678)。A comma-separated list of exit codes that indicate your installer ran successfully (for example: 0, 1234, 5678). 默认情况下,对于非 msi,它为 0,对于 msi,它为 0, 1641, 3010。By default this is 0 for non-msi, and 0, 1641, 3010 for msi.
-MakeAppx [<SwitchParameter>]-MakeAppx [<SwitchParameter>] 可选Optional 一个告知此脚本对输出调用 MakeAppx 的开关(当存在时)。A switch that, when present, tells this script to call MakeAppx on the output.
-MakeMSIX [<SwitchParameter>]-MakeMSIX [<SwitchParameter>] 可选Optional 一个开关,它存在时,会指示此脚本将输出打包为 MSIX 包。A switch that, when present, tells this script to package the output as an MSIX Package.
程序包标识符参数Package identity parameters
-PackageName <String>-PackageName <String> 必需Required 通用 Windows 应用程序包的名称。The name of your Universal Windows App package. 如果合作伙伴中心为你的程序包分配了以数字开头的标识,请确保还要传入 -AppId 参数,并且仅使用字符串后缀(在句点分隔符之后)作为该参数的值。If Partner Center assigns an identity to your package that begins with a number, make sure that you also pass in the -AppId parameter, and use only the string suffix (after the period separator) as the value of that parameter.
-Publisher <String>-Publisher <String> 必需Required 通用 Windows 应用程序包的发布者The publisher of your Universal Windows App package
-Version <Version>-Version <Version> 必需Required 通用 Windows 应用程序包的版本号The version number for your Universal Windows App package
包清单参数Package manifest parameters
-AppExecutable <String>-AppExecutable <String> 可选Optional 你的应用程序的主可执行文件的名称(“MyApp.exe”)。The name of your application's main executable (eg "MyApp.exe"). 无安装程序的转换需要使用此参数。This parameter is required for a no-installer conversion.
-AppFileTypes <String>-AppFileTypes <String> 可选Optional 应用程序将与其关联的文件类型的逗号分隔列表。A comma-separated list of file types which the application will be associated with. 用法示例:-AppFileTypes "'.md', '.markdown'"。Example usage: -AppFileTypes "'.md', '.markdown'".
-AppId <String>-AppId <String> 可选Optional 在 Windows 应用程序包清单中指定要将应用程序 ID 设置为的值。Specifies a value to set Application Id to in the Windows app package manifest. 如果未指定,则将其设置为 PackageName 传入的值。If it is not specified, it will be set to the value passed in for PackageName. 在许多情况下,使用 PackageName 很合适。 In many cases, using the PackageName is fine. 然而,如果合作伙伴中心为你的程序包分配了以数字开头的标识,请确保还要传入 -AppId 参数,并且仅使用字符串后缀(在句点分隔符之后)作为该参数的值。However, if Partner Center assigns an identity to your package that begins with a number, make sure that you also pass in the -AppId parameter, and use only the string suffix (after the period separator) as the value of that parameter.
-AppDisplayName <String>-AppDisplayName <String> 可选Optional 在 Windows 应用程序包清单中指定要将应用程序显示名称设置为的值。Specifies a value to set Application Display Name to in the Windows app package manifest. 如果未指定,则将其设置为 PackageName 传入的值。If it is not specified, it will be set to the value passed in for PackageName.
-AppDescription <String>-AppDescription <String> 可选Optional 在 Windows 应用程序包清单中指定要将应用程序描述设置为的值。Specifies a value to set Application Description to in the Windows app package manifest. 如果未指定,则将其设置为 PackageName 传入的值。If it is not specified, it will be set to the value passed in for PackageName.
-PackageDisplayName <String>-PackageDisplayName <String> 可选Optional 在 Windows 应用程序包清单中指定要将程序包显示名称设置为的值。Specifies a value to set Package Display Name to in the Windows app package manifest. 如果未指定,则将其设置为 PackageName 传入的值。If it is not specified, it will be set to the value passed in for PackageName.
-PackagePublisherDisplayName <String>-PackagePublisherDisplayName <String> 可选Optional 在 Windows 应用程序包清单中指定要将程序包发布者显示名称设置为的值。Specifies a value to set Package Publisher Display Name to in the Windows app package manifest. 如果未指定,则将其设置为 Publisher 传入的值。If it is not specified, it will be set to the value passed in for Publisher.
清理参数Cleanup parameters
-Cleanup [<Option>]-Cleanup [<Option>] 必需Required 为 DesktopAppConverter 项目运行清除。Runs cleanup for the DesktopAppConverter artifacts. 清除模式有 3 个有效的选项。There are 3 valid options for the Cleanup mode.
-Cleanup All-Cleanup All 删除所有已扩展的基本映像、删除任何临时转换器文件、删除容器网络并禁用可选的 Windows 功能,即容器。Deletes all expanded base images, removes any temporary converter files, removes the container network, and disables the optional Windows feature, Containers.
-Cleanup WorkDirectory-Cleanup WorkDirectory 必需Required 删除所有临时转换器文件。Removes all the temporary converter files.
-Cleanup ExpandedImage-Cleanup ExpandedImage 必需Required 删除安装在主机上的所有已扩展的基本映像。Deletes all the expanded base images installed on your host machine.
包体系结构参数Package architecture parameters
-PackageArch <String>-PackageArch <String> 必需Required 生成指定了体系结构的程序包。Generates a package with the specified architecture. 有效选项为“x86”或“x64”,例如 -PackageArch x86。Valid options are 'x86' or 'x64'; for example, -PackageArch x86. 该参数为可选参数。This parameter is optional. 如果未指定,DesktopAppConverter 将尝试自动检测程序包体系结构。If unspecified, the DesktopAppConverter will try to auto-detect package architecture. 如果自动检测失败,它将默认为 x64 程序包。If auto-detection fails, it will default to x64 package.
其他参数Miscellaneous parameters
-ExpandedBaseImage <String>-ExpandedBaseImage <String> 可选Optional 已扩展的基本映像的完整路径。Full path to an already expanded base image.
-LogFile <String>-LogFile <String> 可选Optional 指定日志文件。Specifies a log file. 如果省略,将创建一个日志文件临时位置。If omitted, a log file temporary location will be created.
-Sign [<SwitchParameter>]-Sign [<SwitchParameter>] 可选Optional 出于测试目的,告知此脚本使用生成的证书对输出 Windows 应用包进行签名。Tells this script to sign the output Windows app package by using a generated certificate for testing purposes. 此开关应该位于开关 -MakeAppx 旁边。This switch should be present alongside the switch -MakeAppx.
<通用参数><Common parameters> 必需Required 此 cmdlet 支持通用参数:Verbose、Debug、ErrorAction、ErrorVariable、WarningAction、WarningVariable、OutBuffer、PipelineVariable 和 OutVariable。 This cmdlet supports the common parameters: Verbose, Debug, ErrorAction, ErrorVariable, WarningAction, WarningVariable, OutBuffer, PipelineVariable, and OutVariable. 有关详细信息,请参阅 about_CommonParametersFor more info, see about_CommonParameters.
-Verify [<SwitchParameter>]-Verify [<SwitchParameter>] 可选Optional 一个告知 DAC 根据打包应用和 Microsoft Store 的要求验证应用包的开关(如果有)。A switch that, when present, tells the DAC to validate the app package against packaged app and Microsoft Store requirements. 结果是一个“VerifyReport.xml”验证报告,该报告在浏览器中能够以最佳方式显示。The result is a validation report "VerifyReport.xml", which is best visualized in a browser. 此开关应该位于开关 -MakeAppx 旁边。This switch should be present alongside the switch -MakeAppx.
-PublishComRegistrations-PublishComRegistrations 可选Optional 扫描你的安装程序进行的所有公共 COM 注册,并发布你的清单中有效的注册。Scans all public COM registrations made by your installer and publishes the valid ones in your manifest. 仅当想使这些注册可供其他应用程序使用时才使用此标志。Use this flag only if you want to make these registrations available to other applications. 如果这些注册将仅由你的应用程序使用,则无需使用此标志。You don't need to use this flag if these registrations will be used only by your application.

请查看本文以确保在你将应用打包后,COM 注册会按预期工作。Review this article to make sure that your COM registrations behave as you expect after you package your app.

运行打包的应用Run the packaged app

可通过两种方法运行应用。There's two ways to run your app.

一种方法是打开 PowerShell 命令提示符,然后键入此命令:Add-AppxPackage –Register AppxManifest.xmlOne way is to open a PowerShell command prompt, and then type this command: Add-AppxPackage –Register AppxManifest.xml. 这可能是运行应用程序最简单的方法,因为你无需对其进行签名。It's probably the easiest way to run your application because you don't have to sign it.

另一种方法是使用证书对应用程序进行签名。Another way is to sign your application with a certificate. 如果使用 sign 参数,Desktop App Converter 将为你生成一个证书,然后使用该证书对应用程序进行签名。If you use the sign parameter, the Desktop App Converter will generate one for you, and then sign your application with it. 该文件名为 auto-generated.cer,你可以在已打包应用的根文件夹中找到它。 That file is named auto-generated.cer, and you can find it in the root folder of your packaged app.

请按照以下步骤安装生成的证书,然后运行应用。Follow these steps to install the generated certificate, and then run your app.

  1. 双击 auto-generated.cer 文件安装证书。 Double-click the auto-generated.cer file to install the certificate.

    生成的证书文件

    备注

    如果系统提示你输入密码,请使用默认密码“123456”。If you're prompted for a password, use the default password "123456".

  2. 在“证书”对话框中,选择“安装证书”按钮。 In the Certificate dialog box, choose the Install Certificate button.

  3. 在“证书导入向导”中,将证书安装到“本地计算机”,并将证书放在“受信任人”证书存储区中。 In the Certificate Import Wizard, install the certificate onto the Local Machine, and place the certificate into the Trusted People certificate store.

    “受信任人”存储区

  4. 在已打包应用的根文件夹中,双击 Windows 应用包文件。In root folder of your packaged app, double click the Windows app package file.

    Windows 应用包文件

  5. 选择“安装”按钮以安装应用。 Install the app, by choosing the Install button.

    “安装”按钮

修改已打包的应用Modify the packaged app

你可能需要对已打包的应用程序进行更改,以解决 Bug、添加视觉资源或使用动态磁贴等现代体验增强你的应用程序。You'll likely make changes to your packaged application to address bugs, add visual assets, or enhance your application with modern experiences such as live tiles.

进行更改之后,无需再次运行转换器。After you make your changes, you don't need to run the converter again. 在大多数情况下,你只需使用 MakeAppx 工具以及 DAC 为你的应用程序生成的 appxmanifest.xml 文件将应用重新打包。In most cases, you can just repackage your application by using the MakeAppx tool and the appxmanifest.xml file the DAC generates for your app. 请参阅生成 Windows 应用包See Generate a Windows app package.

备注

如果你对安装程序进行的注册表设置做出了更改,则需要再次运行 Desktop App Converter 以应用这些更改。If you make changes to registry settings that your installer makes, you will have to run the Desktop App Converter again to pick up those changes.

以下两部分介绍了针对已打包的应用程序可考虑使用的一些可选修复。The following two sections describe a couple of optional fix-ups to the packaged application that you might consider.

删除不必要的文件和注册表项Delete unnecessary files and registry keys

Desktop App Converter 采用非常保守的方法来筛选掉容器中的文件和系统干扰。The desktop App Converter takes a very conservative approach to filtering out files and system noise in the container.

如有需要,可以查看 VFS 文件夹并删除安装程序不需要的任何文件。If you want, you can review the VFS folder and delete any files that your installer doesn't need. 还可以查看 Reg.dat 的内容并删除应用未安装/不需要的任何项。You can also review the contents of Reg.dat and delete any keys that are not installed/needed by the app.

修复损坏的 PE 头Fix corrupted PE headers

在转换过程中,DesktopAppConverter 将自动运行 PEHeaderCertFixTool 以修复任何损坏的 PE 头。During the conversion process, the DesktopAppConverter automatically runs the PEHeaderCertFixTool to fixup any corrupted PE headers. 但是,还可以在 UWP Windows 应用包、松散文件或特定的二进制文件上运行 PEHeaderCertFixTool。However, you can also run the PEHeaderCertFixTool on a UWP Windows app package, loose files, or a specific binary. 下面是一个示例。Here's an example.

PEHeaderCertFixTool.exe <binary file>|<.appx package>|<folder> [/c] [/v]
 /c   -- check for corrupted certificate but do not fix (optional)
 /v   -- verbose (optional)
example1: PEHeaderCertFixTool app.exe
example2: PEHeaderCertFixTool c:\package.appx /c
example3: PEHeaderCertFixTool c:\myapp /c /v

来自 Desktop App Converter 的遥测Telemetry from Desktop App Converter

Desktop App Converter 可以收集关于你和你使用该软件的情况的信息,并将此信息发送给 Microsoft。Desktop App Converter may collect information about you and your use of the software and send this info to Microsoft. 你可以在产品文档和 Microsoft 隐私声明中了解有关 Microsoft 的数据收集和使用的详细信息。You can learn more about Microsoft's data collection and use in the product documentation and in the Microsoft Privacy Statement. 你同意遵守《Microsoft 隐私声明》的所有适用条款。You agree to comply with all applicable provisions of the Microsoft Privacy Statement.

默认情况下,将为 Desktop App Converter 启用遥测。By default, telemetry will be enabled for the Desktop App Converter. 添加以下注册表项以将遥测配置为所需设置:Add the following registry key to configure telemetry to a desired setting:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\DesktopAppConverter
  • 通过使用设置为 1 的 DWORD 来添加或编辑 DisableTelemetry 值。Add or edit the DisableTelemetry value by using a DWORD set to 1.
  • 若要启用遥测,请删除该项或将值设置为 0。To enable telemetry, remove the key or set the value to 0.

语言支持Language support

Desktop App Converter 不支持 Unicode;因此,没有用于该工具的任何中文字符或非 ASCII 字符。The Desktop App Converter does not support Unicode; thus, no Chinese characters or non-ASCII characters can be used with the tool.

Desktop App Converter 的已知问题Known issues with the Desktop App Converter

E_CREATING_ISOLATED_ENV_FAILED 和 E_STARTING_ISOLATED_ENV_FAILED 错误E_CREATING_ISOLATED_ENV_FAILED and E_STARTING_ISOLATED_ENV_FAILED errors

如果收到任一错误,请确保你正在使用的是从下载中心下载的有效基础映像。If you receive either of these errors, make sure that you're using a valid base image from the download center. 如果使用的是有效的基础映像,请尝试在命令中使用 -Cleanup AllIf you’re using a valid base image, try using -Cleanup All in your command. 如果不起作用,请将日志发送至 converter@microsoft.com,以帮助我们进行调查。If that does not work, please send us your logs at converter@microsoft.com to help us investigate.

New-ContainerNetwork:“对象已存在”错误New-ContainerNetwork: The object already exists error

设置新的基础映像时,可能会收到此错误。You might receive this error when you setup a new base image. 如果你在以前安装了 Desktop App Converter 的开发人员计算机上安装有 Windows 预览体验计划外部测试版,则可能会出现这种情况。This can happen if you have a Windows Insider flight on a developer machine that previously had the Desktop App Converter installed.

若要解决此问题,请尝试从提升的命令提示符中运行命令 Netsh int ipv4 reset,然后重启计算机。To resolve this issue, try running the command Netsh int ipv4 reset from an elevated command prompt, and then reboot your machine.

你的 .NET 应用程序是使用“AnyCPU”生成选项编译的,无法安装Your .NET application is compiled with the "AnyCPU" build option and fails to install

如果将主要可执行文件或任何依赖项放置在 Program Files 或 Windows\System32 文件夹层次结构中的任意位置,则可能会出现这种情况。 This can happen if the main executable or any of the dependencies were placed anywhere in the Program Files or Windows\System32 folder hierarchy.

若要解决此问题,请尝试使用你体系结构特定的桌面安装程序(32 位或 64 位)生成 Windows 应用包。To resolve this issue, try using your architecture-specific desktop installer (32 bit or 64 bit) to generate a Windows app package.

发布公共并行的 Fusion 程序集不起作用Publishing public side-by-side Fusion assemblies won't work

在安装期间,应用程序可以发布公共并行 Fusion 程序集,这些程序集可供任何其他进程访问。During install, an application can publish public side-by-side Fusion assemblies, accessible to any other process. 在进程激活上下文创建期间,这些程序集将由名为 CSRSS.exe 的系统进程检索。During process activation context creation, these assemblies are retrieved by a system process named CSRSS.exe. 当已转换的进程执行此操作时,这些程序集的激活上下文创建和模块加载将失败。When this is done for a converted process, activation context creation and module loading of these assemblies will fail. 并行的 Fusion 程序集注册在以下位置中:The side-by-side Fusion assemblies are registered in the following locations:

  • 注册表:HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\SideBySide\WinnersRegistry: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\SideBySide\Winners
  • 文件系统:%windir%\SideBySideFile System: %windir%\SideBySide

这是一个已知限制,目前尚无解决方法。This is a known limitation and no workaround currently exists. 即,内置程序集(如 ComCtl)随操作系统附带,因此依赖它们是安全的行为。That said, Inbox assemblies, like ComCtl, are shipped with the OS, so taking a dependency on them is safe.

XML 中发现错误。Error found in XML. “Executable”特性无效 - 根据其数据类型,值“MyApp.EXE”无效The 'Executable' attribute is invalid - The value 'MyApp.EXE' is invalid according to its datatype

如果应用程序中的可执行文件具有大写的 .EXE 扩展名,则可能会出现这种情况。 This can happen if the executables in your application have a capitalized .EXE extension. 虽然此扩展名的大小写不应影响应用程序是否能够运行,但这可能导致 DAC 生成此错误。Although, the casing of this extension shouldn't affect whether your application runs, this can cause the DAC to generate this error.

若要解决此问题,请尝试在打包时指定 -AppExecutable 标志,并使用小写的“.exe”作为主要可执行文件的扩展名(例如: MYAPP.exe)。To resolve this issue, try specifying the -AppExecutable flag when you package, and use the lower case ".exe" as the extension of your main executable (For example: MYAPP.exe). 或者,可以将应用程序中的所有可执行文件的大小写从大写更改为小写(例如从 .EXE 更改为 .exe)。Alternately you can change the casing for all executables in your application from uppercase to lowercase (For example: from .EXE to .exe).

已损坏或格式不正确的验证码签名Corrupted or malformed Authenticode signatures

本部分包含有关如何在可能包含已损坏或格式不正确的验证码签名的 Windows 应用包中标识可移植可执行 (PE) 文件的问题。This section contains details on how to identify issues with Portable Executable (PE) files in your Windows app package that may contain corrupted or malformed Authenticode signatures. PE 文件中的无效验证码签名可能采用任何二进制格式(如 .exe、.dll、.chm 等),并且会阻止程序包正确签名,从而使其无法从 Windows 应用包部署。Invalid Authenticode signatures on your PE files, which may be in any binary format (e.g. .exe, .dll, .chm, etc.), will prevent your package from being signed properly, and thus prevent it from being deployable from an Windows app package.

PE 文件的验证码签名的位置由可选头数据目录中的证书表项和关联的属性证书表指定。The location of the Authenticode signature of a PE file is specified by the Certificate Table entry in the Optional Header Data Directories and the associated Attribute Certificate Table. 在签名验证期间,这些结构中指定的信息用于找到 PE 文件上的签名。During signature verification, the information specified in these structures is used to locate the signature on a PE file. 如果这些值损坏,则文件可能看起来无法有效进行签名。If these values get corrupted then it is possible for a file to appear to be invalidly signed.

若要使验证码签名正确,验证码签名必须符合以下情况:For the Authenticode signature to be correct, the following must be true of the Authenticode signature:

  • PE 文件中 WIN_CERTIFICATE 项的开头不得超过可执行文件的末尾The start of the WIN_CERTIFICATE entry in the PE file cannot extend past the end of the executable
  • WIN_CERTIFCATE 项应位于映像的末尾The WIN_CERTIFCATE entry should be located at the end of the image
  • WIN_CERTIFICATE 项的大小必须为正数The size of the WIN_CERTIFICATE entry must be positive
  • 对于 32 位可执行文件,WIN_CERTIFICATE 项必须在 IMAGE_NT_HEADERS32 结构之后开始,对于 64 位可执行文件,必须在 IMAGE_NT_HEADERS64 结构之后开始The WIN_CERTIFICATEentry must start after the IMAGE_NT_HEADERS32 structure for 32-bit executables and IMAGE_NT_HEADERS64 structure for 64-bit executables

有关更多详细信息,请参考验证码门户可执行文件规范PE 文件格式规范For more details, please refer to the Authenticode Portal Executable specification and the PE file format specification.

请注意,当尝试对 Windows 应用包进行签名时,SignTool.exe 可能会输出已损坏或格式不正确的二进制文件列表。Note that SignTool.exe can output a list of the corrupted or malformed binaries when attempting to sign an Windows app package. 若要执行此操作,请通过将环境变量 APPXSIP_LOG 设置为 1(如 set APPXSIP_LOG=1)来启用详细日志记录并重新运行 SignTool.exe。To do this, enable verbose logging by setting the environment variable APPXSIP_LOG to 1 (e.g., set APPXSIP_LOG=1 ) and re-run SignTool.exe.

若要修复这些格式不正确的二进制文件,请确保它们符合上述要求。To fix these malformed binaries, ensure they conform to the requirements above.

后续步骤Next steps

查找问题的答案Find answers to your questions

有问题?Have questions? 请在 Stack Overflow 上向我们提问。Ask us on Stack Overflow. 我们的团队会监视这些标记Our team monitors these tags. 你还可以在此处提问。You can also ask us here.

运行应用程序/查找和修复问题Run your application / find and fix issues

请参阅运行、调试和测试打包的桌面应用程序See Run, debug, and test a packaged desktop application

分发你的应用Distribute your app

请参阅分发打包的桌面应用程序See Distribute a packaged desktop application