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

本文提供有关部署依赖框架的打包应用的指导, (请参阅什么是 MSIX?) 使用 Windows 应用 SDK。 其他依赖于框架的打包选项的等效主题是Windows 应用 SDK部署指南,该指南适用于使用外部位置打包或未打包的依赖于框架的应用

概述

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

若要详细了解打包应用在使用Windows 应用 SDK时可能需要的包,请参阅Windows 应用 SDK的部署体系结构。 其中包括 FrameworkMainSingleton 包;这些都由 Microsoft 签名和发布。 部署打包应用有两个主要要求:

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

先决条件

部署 Windows 应用 SDK 框架包

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

稳定版本

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

但是,如果使用单独的 Windows 应用程序打包项目手动生成应用包,则必须在Application (package).wapproj文件中声明 PackageReference,如下所示:

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

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

预览版

安装预览发布版本 (在开发计算机上查看 Windows 应用 SDK NuGet 包的预览频道发行说明) 时,Windows 应用 SDK框架包的预览版本在生成时部署为 NuGet 包依赖项。

调用部署 API

部署 API 由 Windows 应用 SDK 框架包提供,可在Microsoft中使用。Windows.ApplicationModel.WindowsAppRuntime 命名空间。 Windows 应用程序模型不支持声明对主包和单一实例包的依赖项。 因此,出于以下原因,需要部署 API:

  1. 例如,若要为框架包 (中未包含的功能部署单一实例包,) 推送通知。
  2. 部署主包,以便从 Microsoft 存储中自动更新框架包。

对于 通过应用商店分发的打包应用,你作为开发人员负责分发框架包。 建议调用部署 API,以便传递任何关键服务更新。 请注意,若要使用框架包之外的功能 (例如推送通知) ,必须部署单一实例包, (这可以通过部署 API 完成,或使用自己的安装方法) 重新分发 MSIX 包。

重要

在 Windows 应用 SDK 版本 1.0 中,只有完全信任或具有 packageManagement 受限功能的 MSIX 打包应用才有权使用部署 API 安装主包和单一实例包依赖项。 对部分信任应用包的支持将在后面的版本中推出。

应在初始化应用进程后调用部署 API,但在应用使用使用单一实例包 (Windows 应用 SDK运行时功能之前,) 推送通知。 部署 API 的主要方法是 DeploymentManager 类的静态 GetStatusInitialize 方法。

  • GetStatus 方法返回当前加载的Windows 应用 SDK运行时的当前部署状态。 使用此方法确定在当前应用可以使用Windows 应用 SDK功能之前,是否需要安装Windows 应用 SDK运行时包。
  • Initialize 方法验证所有必需的包是否都以当前加载的Windows 应用 SDK运行时所需的最低版本提供。 如果缺少任何包依赖项,则 方法会尝试注册这些缺失的包。 从 Windows 应用 SDK 1.1 开始,Initialize 方法还支持强制部署Windows 应用 SDK运行时包的选项。 这会关闭 MainSingleton 运行时包的任何进程,从而中断其服务 (例如,推送通知在此期间不会) 传递通知。

部署 API 示例应用

有关如何使用 DeploymentManager 类的 GetStatusInitialize 方法的其他指导,请浏览可用的示例应用。

地址安装错误

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

例如,如果你的应用不完全信任,或者没有 packageManagement 受限功能,则会收到 ACCESS_DENIED 错误代码。 若要查看可能遇到的其他错误代码及其可能的原因,请参阅 Windows 应用的打包、部署和查询疑难解答

如果错误代码未提供足够的信息,则可以在详细的事件日志中找到更多诊断信息, (请参阅) 获取诊断信息

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