使用单项目 MSIX 将应用打包

项目
12/29/2023

借助单项目 MSIX 功能，可以生成打包的 WinUI 3 桌面应用，而无需使用单独的打包项目。 WinUI 3 应用是一款在用户界面 (UI) 中使用 Windwos UI 库 (WinUI) 3 框架的应用，并且使用 Windows 应用 SDK。若要打包不是 WinUI 3 应用的桌面应用，请参阅在 Visual Studio 中为 MSIX 打包设置桌面应用程序。

单项目 MSIX 功能作为 Visual Studio 扩展提供，可用于以下应用场景：

使用“打包的空白应用 (桌面版 WinUI 3)”Visual Studio 项目模板（即随附 Windows 应用 SDK 的项目模板），创建“新的”WinUI 3 桌面应用程序。该项目已配置为将应用生成到 MSIX 包中，而无需单独的打包项目。
修改使用单独打包项目的现有 WinUI 3 桌面应用。修改涉及删除单独的打包项目，如下图所示。

概述

本部分介绍有关单项目 MSIX 功能的一些重要详细信息。

好处

在引入单项目 MSIX 功能之前，如果想要生成打包的 WinUI 3 桌面应用，则需要解决方案中有两个项目：你的应用项目，以及一个额外的 Windows 应用程序打包项目（请参阅在 Visual Studio 中为 MSIX 打包设置桌面应用程序）。借助单项目 MSIX 功能，只需使用应用的项目就能开发和生成应用。这可以提供更简洁的项目结构和更直接的开发体验。例如，不再需要选择单独的打包项目作为启动项目。

支持的项目类型

单项目 MSIX 功能支持 Visual Studio 中的 WinUI 3 模板（C# 和 C++），用于 Windows 应用 SDK。

限制

单项目 MSIX 仅支持生成的 MSIX 包中的单个可执行文件。如果需要将多个可执行文件组合到单个 MSIX 包中，则需要继续在解决方案中使用 Windows 应用程序打包项目。

安装单项目 MSIX 打包工具

单项目 MSIX 打包工具包括可用于创建新的打包 WinUI 3 桌面应用的 Visual Studio 项目模板。这些工具包含在适用于 Visual Studio 的 Windows 应用 SDK 扩展中。有关 Windows 应用 SDK 的安装说明，请参阅适用于 Windows 应用 SDK 的安装工具。

预览版 3 的 Windows 应用 SDK 0.8 和 C# 1.0 版本：单项目 MSIX 打包工具不包含在 Visual Studio 的 Windows 应用 SDK 扩展的 Windows 应用 SDK 版本 0.8 中，以及直到预览版 3（含）的 Windows 应用 SDK 1.0 版本 C# 项目中。因此，如果使用这些版本，则“可能”需要显式安装单项目 MSIX 打包工具。请参阅下面的信息：

Visual Studio 2022 版本 17.1 及更高版本：Visual Studio 2022 VSIX 扩展的单项目 MSIX 打包工具内置于 Visual Studio 2022 版本 17.1 及更高版本中。
早于版本 17.1 的 Visual Studio 2022：安装适用于 Visual Studio 2022 VSIX 扩展的单项目 MSIX 打包工具。
Visual Studio 2019：安装适用于 Visual Studio 2019 VSIX 的单项目 MSIX 打包工具扩展。该扩展需要 Visual Studio 2019 版本 16.10.x 或更高版本。

然后可以在 Visual Studio Code 中确认安装了扩展。单击“扩展”>“管理扩展”>“已安装”>“所有”，并确认列出了“单项目 MSIX 打包工具”。

创建新项目

如果使用的是 Windows 应用 SDK 1.0 预览版 2 或更高版本，则可以使用“打包的空白应用 (桌面版 WinUI 3)”模板新建一个包含单项目 MSIX 支持的基于 WinUI 3 的项目。有关详细信息，请参阅创建第一个 WinUI 3 项目。

修改现有项目

按照本部分中的步骤修改使用单独打包项目的现有 WinUI 3 应用。这些步骤包括将包清单（以及生成 MSIX 包所需的其他支持）移动到应用程序项目中，然后删除单独的打包项目。

步骤 1：创建打包项目或打开现有的打包项目

如果已有包含Windows 应用程序打包项目（请参阅在 Visual Studio 中为 MSIX 打包设置桌面应用程序）的 WinUI 3 桌面应用的解决方案（请参阅 Visual Studio 中的 WinUI 3 模板），则现在在 Visual Studio 中打开该解决方案。

如果没有，则使用“以 Windows 应用程序打包项目打包的空白应用 (桌面版 WinUI 3)”模板，在 Visual Studio 中新建 WinUI 3 桌面应用程序。解决方案的外观应类似于以下屏幕截图。

A solution using the packaging project

步骤 2：编辑应用程序项目设置

接下来，编辑某些配置设置以使用单项目 MSIX 功能。要参考的说明根据项目类型和 Visual Studio 版本而有所不同。

在“解决方案资源管理器”中，双击应用程序的项目节点以在 XML 编辑器中打开 .csproj 文件。将以下 XML 添加到主 PropertyGroup 元素<>。

<EnableMsixTooling>true</EnableMsixTooling>
<PublishProfile>Properties\PublishProfiles\win10-$(Platform).pubxml</PublishProfile>

完成后，PropertyGroup 元素应类似于以下内容。

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
    ...
    <UseWinUI>true</UseWinUI>
    <EnableMsixTooling>true</EnableMsixTooling>
    <PublishProfile>Properties\PublishProfiles\win10-$(Platform).pubxml</PublishProfile>
  </PropertyGroup>

保存更改并关闭 .csproj 文件。

根据所用的 Visual Studio 版本执行以下过程之一。

适合 Visual Studio 2022 或更高版本：

在“解决方案资源管理器”中，右键单击应用程序项目节点下的“属性”文件夹，然后选择“添加”>“新建项...”。
选择“文本文件”，将新文件命名为 launchSettings.json，然后单击“添加”。确保新文件位于应用程序项目的“属性”文件夹中。

将以下设置复制到新文件中。你可以根据自己的方案随意更改值。 MyApp 值可以是任意字符串；它不需要与应用程序的名称相匹配。

{
    "profiles": {
        "MyApp": {
            "commandName": "MsixPackage",
            "commandLineArgs": "", /* Command line arguments to pass to the app. */
            "alwaysReinstallApp": false, /* Uninstall and then reinstall the app. All information about the app state is deleted. */
            "remoteDebugEnabled": false, /* Indicates that the debugger should attach to a process on a remote machine. */
            "allowLocalNetworkLoopbackProperty": true, /* Allow the app to make network calls to the device it is installed on. */
            "authenticationMode": "Windows", /* The authentication scheme to use when connecting to the remote machine. */
            "doNotLaunchApp": false, /* Do not launch the app, but debug my code when it starts. */
            "remoteDebugMachine": "", /* The name of the remote machine. */
            "nativeDebugging": false /* Enable debugging for managed and native code together, also known as mixed-mode debugging. */
        }
    }
}

保存并关闭 launchSettings.json 文件。

对于 Visual Studio 2019：

在“解决方案资源管理器”中，右键单击应用程序的项目节点并选择“属性”。
选择“调试”选项卡并将“Launch”属性设置为“MsixPackage”。如果在首次尝试时该属性恢复原始值，可能必须选择此设置两次。
保存所做更改。

在“解决方案资源管理器”中，右键单击应用程序的项目节点并选择“卸载项目”。
再次右键单击项目节点并选择“编辑 project-name.vcxproj”以在 XML 编辑器中打开 .vcxproj 文件。

对 .vcxproj 文件中的 XML 进行以下更改：

将 <EnableMsixTooling>true</EnableMsixTooling> 添加到主 <PropertyGroup> 元素。
将 <AppxPackage> 的值更改为 true。

完成后，.vcxproj 文件的内容应如下所示。

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="15.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup Label="Globals">
    ...
    <MinimumVisualStudioVersion>16.0</MinimumVisualStudioVersion>
    <AppContainerApplication>false</AppContainerApplication>
    <AppxPackage>true</AppxPackage>
    <ApplicationType>Windows Store</ApplicationType>
    <ApplicationTypeRevision>10.0</ApplicationTypeRevision>
    <WindowsTargetPlatformVersion>10.0</WindowsTargetPlatformVersion>
    <WindowsTargetPlatformMinVersion>10.0.17763.0</WindowsTargetPlatformMinVersion>
    <UseWinUI>true</UseWinUI>
    <EnableMsixTooling>true</EnableMsixTooling>
  </PropertyGroup>

保存并关闭 .vcxproj 文件。
在“解决方案资源管理器”中，右键单击项目节点并选择“重新加载项目”。

步骤 3：将文件移到应用程序项目

接下来，将几个重要的文件移到应用程序项目。要参考的说明根据项目类型而有所不同。

在“文件资源管理器”中，将“Package.appxmanifest”文件和“Images”文件夹从打包项目移到应用程序项目。请将此文件和文件夹放在应用程序项目文件夹层次结构的顶层。
在 Visual Studio 的“解决方案资源管理器”中，多选 Images 文件夹中的所有图像。在“属性”窗口中，将“生成操作”属性设置为“内容”。
从解决方案中删除打包项目。

步骤 4：在配置管理器中启用部署

选择“生成”>“配置管理器”。
在“配置管理器”中，对配置和平台的每个组合单击“部署”复选框（例如“调试”和“x86”、“调试”和“arm64”、“发布”和“x64”等）。

注意

请务必使用顶部的“活动解决方案配置”和“活动解决方案平台”下拉菜单，而不是与“部署”复选框位于相同行中的“配置”和“平台”下拉菜单。

步骤 5：部署应用

生成并部署应用程序项目。 Visual Studio 会将应用程序生成到 MSIX 包中，安装该包，然后运行应用程序。

步骤 6：打包应用以进行发布

使用 Visual Studio 中的“打包并发布”命令打包应用程序，以发布到 Microsoft Store。

自动生成并打包单项目 MSIX 应用

可以使用 msbuild 生成并打包单项目 MSIX 应用，从而可以将工作流自动化。对单项目解决方案使用的方法和命令行只是与你在双项目解决方案中所用的略有不同（其中包括“Windows 应用程序打包项目”，请参阅在 Visual Studio 中设置用于 MSIX 打包的桌面应用程序）。

单项目解决方案的重要生成命令选项是 /p:GenerateAppxPackageOnBuild=true。如果不使用该选项，则项目将会生成，但你不会获得 MSIX 包。如果包含该选项，则会生成 MSIX 包。

我们以生成 WinUI 3 单项目解决方案的 GitHub 操作形式提供了一个完整示例。

注意

单项目 MSIX 目前不支持生成 MSIX 包（请参阅捆绑 MSIX 包）。它只生成单个 MSIX。但是，你可以使用 MSIX 捆绑程序 GitHub 操作将 .msix 文件捆绑到 MSIX 包中。

打包的桌面应用如何在 Windows 上运行

若要深入了解在为桌面应用程序创建 Windows 应用包时，文件和注册表项发生的情况，请参阅了解打包的桌面应用如何在 Windows 上运行。

提供反馈

若要向我们发送反馈、报告问题或提出有关单项目 MSIX 功能的问题，请在 Windows 应用 SDK GitHub 存储库上发布话题或问题。