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

本文提供有关部署依赖于框架的 MSIX 打包应用的指导, (请参阅什么是 MSIX?) 使用Windows 应用 SDK。

概述

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

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

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

先决条件

部署 Windows 应用 SDK 框架包

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

稳定版本

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

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

   <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应用程序模型不支持声明对 Main 和 Singleton 包的依赖项。 因此,出于两个主要原因,需要部署 API:

  1. 若要为框架包中非功能部署单一实例包, (例如推送通知) 。
  2. 若要部署 Main 包,可从Microsoft Store中自动更新框架包。

对于通过Microsoft Store分发的 MSIX 打包应用,开发人员负责分发框架包。 建议调用部署 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 类的 GetStatus 和 Initialize 方法的其他指南,请浏览可用示例。

地址安装错误

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

例如,如果应用不是完全信任或具有 packageManagement 受限功能,则你将收到 ACCESS_DENIED 错误代码。 若要查看可能遇到的其他错误代码及其可能的原因,请参阅对 Windows 应用的打包、部署和查询进行故障排除

如果错误代码未提供足够信息,可以在详细事件日志中查找更多诊断信息。

如果遇到无法诊断的错误,请提交问题,其中包含错误代码和事件日志,以便我们可以调查该问题。