依赖于框架的打包应用的 Windows 应用 SDK 部署指南

本文提供有关部署依赖于框架的打包应用（请参阅 什么是 MSIX？）的指南，这些应用使用 Windows 应用 SDK。 其他依赖框架的打包选项的等效主题是 Windows 应用 SDK 部署指南，该指南适用于通过外部位置打包或未打包的依赖框架的应用。

Overview

默认情况下，在 Visual Studio 中使用 WinUI 3 模板之一创建项目时，项目配置为使用单项目 MSIX（请参阅使用单项目 MSIX 打包应用）或 Windows 应用程序打包项目（请参阅 在 Visual Studio 中为 MSIX 打包设置桌面应用程序）将应用构建到 MSIX 包中。 然后，可以使用 Visual Studio中的 打包桌面或 UWP 应用中的说明为应用生成 MSIX 包。 为应用生成 MSIX 包后，可以使用多个选项 来管理 MSIX 部署。

若要详细了解打包应用在使用 Windows 应用 SDK 时可能需要的包，请参阅 Windows 应用 SDK 的部署体系结构。 Those include the Framework, Main, and Singleton packages; which are all signed and published by Microsoft. 部署打包的应用有两个主要要求：

1. 部署 Windows 应用 SDK 框架包。
2. 调用部署 API。

Prerequisites

• 对于打包的应用，VCLibs 框架包依赖项是必需的。 有关详细信息，请参阅 适用于桌面桥的C++运行时框架包。
• C#. 需要 .NET 6 或更高版本。 For more info, see .NET Downloads.

部署 Windows 应用 SDK 框架包

Windows App SDK 框架包包含运行时使用的 Windows 应用 SDK 二进制文件，并随应用程序一起安装。 框架对 Windows 应用 SDK 的不同通道有不同的部署要求。

Stable version

在开发计算机上安装 Windows 应用 SDK NuGet 包的稳定发布版本（请参阅 稳定频道发行说明），并使用提供的 WinUI 3 项目模板之一创建项目时，生成的包清单包含一个 PackageDependency 元素，该元素指定了框架包的依赖项。

However, if you build your app package manually using a separate Windows Application Packaging Project, then you must declare a PackageReference in your Application (package).wapproj file, like the following:

<ItemGroup>
   <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.0.1">
       <IncludeAssets>build</IncludeAssets>
   </PackageReference>
</ItemGroup>

该包依赖项可确保将应用部署到另一台计算机时安装框架包。

Preview version

在你开发计算机上安装 Windows 应用 SDK NuGet 包的预览版本时（请参阅 预览频道发行说明），在生成时将 Windows 应用 SDK 框架包的预览版本作为 NuGet 包的依赖项进行部署。

调用部署 API

另请参阅 初始化 Windows 应用 SDK。

The Deployment API is provided by the Windows App SDK framework package, and is available in the Microsoft.Windows.ApplicationModel.WindowsAppRuntime namespace. Windows 应用程序模型不支持声明对 Main 和 Singleton 包的依赖项。 因此，出于以下原因，需要部署 API：

1. 为框架包中没有的功能（例如推送通知）部署 Singleton 包。
2. 若要部署 Main 包，该包允许从 Microsoft 应用商店自动更新框架包。

For packaged apps that are not distributed through the Store, you as the developer are responsible for distributing the Framework package. 建议调用部署 API，以便传递任何关键服务更新。 请注意，若要使用框架包外部的功能（例如推送通知），必须部署 Singleton 包（这可以通过部署 API 完成，或者通过使用你自己的安装方法重新分发 MSIX 包）。

应在应用进程初始化后调用部署 API，但在应用使用使用 Singleton 包的 Windows 应用 SDK 运行时功能（例如推送通知）之前。 The main methods of the Deployment API are the static GetStatus and Initialize methods of the DeploymentManager class.

• The GetStatus method returns the current deployment status of the Windows App SDK runtime that's currently loaded. 使用此方法确定在当前应用可以使用 Windows 应用 SDK 功能之前是否需要安装 Windows 应用 SDK 运行时包。
• The Initialize method verifies whether all required packages are present to a minimum version needed by the Windows App SDK runtime that's currently loaded. 如果缺少任何包依赖项，该方法将尝试注册缺少的包。 Beginning in Windows App SDK 1.1, the Initialize method also supports the option to force-deploy the Windows App SDK runtime packages. That shuts down any processes for the Main and Singleton runtime packages, and thus interrupts their services (for example, push notifications won't deliver notifications during this time). You should call Initialize only once. You don't need to call Initialize for apps deployed via the Start Without Debugging and Start Debugging commands in Visual Studio.

部署 API 示例应用

For additional guidance on how to use the GetStatus and Initialize methods of the DeploymentManager class, explore the available sample app.

解决安装错误

如果在安装 Windows 应用 SDK 运行时包期间部署 API 遇到错误，它将返回描述问题的错误代码。

For example, if your app is not full trust, or doesn't have the packageManagement restricted capability, then you'll get an ACCESS_DENIED error code. 若要查看可能会遇到的其他错误代码及其可能的原因，请参阅 Windows 应用的打包、部署和查询疑难解答。

如果错误代码不提供足够的信息，则可以在详细的事件日志中找到更多诊断信息（请参阅 获取诊断信息）。

如果遇到无法诊断的错误，请使用错误代码和事件日志在 WindowsAppSDK GitHub 存储库 中提出问题，以便我们可以调查问题。

Related topics

• Windows 应用 SDK 的部署体系结构
• 针对依赖框架的应用程序的 Windows 应用 SDK 部署指南（适用于拥有外部位置的打包应用或未打包应用）
• Release channels
• 使用单项目 MSIX 将应用打包