使用动态依赖项 API 在运行时引用框架包

动态依赖项 API 使未打包的应用能够引用和使用 WinUI 2 与 DirectX 运行时等框架包。 有关框架包依赖项的详细信息,请参阅 MSIX 框架包和动态依赖项

具体而言,动态依赖项 API 提供了用于为框架包管理安装时引用和运行时引用的方式 。 有关这些引用类型的详细信息,请参阅框架包的服务模型

注意

与其他框架包不同,不能使用动态依赖项 API 在未打包应用中引用 Windows 应用 SDK 框架包。 而是需要使用 Windows App SDK 提供的引导程序 API。 引导程序 API 是动态依赖项 API 的一种专用形式,旨在依赖于 Windows 应用 SDK 框架包的依赖。 有关详细信息,请参阅将 Windows 应用 SDK 运行时用于使用外部位置打包的应用或未打包的应用

使用动态依赖项 API

动态依赖项 API 有两种实现,可以根据目标平台和方案进行选择。

注意

如本主题中所示,Windows 应用 SDK (C/C++) API 与 Windows 11 (C/C++) API 具有相同的名称,但带有额外的 Mdd 前缀。 Mdd 代表 Microsoft 动态依赖项。

若要在未打包的应用中使用动态依赖项 API 依赖于框架包,请在代码中遵循此常规模式。

1. 创建安装时引用

在应用安装程序中或首次运行应用期间,可调用以下函数或方法之一来为要使用的框架包指定一组条件。 这会向操作系统告知应用依赖于满足指定条件的框架包。 如果安装了满足条件的一个或多个框架包,则 Windows 会确保在删除安装时引用之前至少使这些框架包中的一个保持已安装状态。

  • Windows 11 (C/C++):TryCreatePackageDependency
  • Windows App SDK (C/C++):MddTryCreatePackageDependency
  • Windows App SDK (WinRT):PackageDependency.Create

指定的条件包括包系列名称、最低版本和体系结构,但不能指示特定框架包。 添加对框架包的运行时引用时,API 会选择满足指定条件的最高版本。

还必须指定生存期项目,这可以是当前进程、文件或是向系统指示应用仍可用的 Windows 注册表项。 如果指定项目不再存在,则操作系统可能会假设不再需要依赖项,并且如果其他应用都未声明对框架包的依赖,则可以卸载它。 对于应用在卸载时会忽略删除安装时 pin 的情况,此功能十分有用。

此 API 会返回一个依赖项 ID,必须在其他调用中使用该 ID 才能创建运行时引用并删除安装时引用。

2. 添加运行时引用

在应用需要使用框架包时,可调用以下函数或方法之一来请求访问指定框架包并为其添加运行时引用。 调用此 API 会向操作系统告知框架包处于活动使用状态,以按并行方式处理任何版本更新(实际上会延迟卸载或以其他方式维护较旧版本,直到应用使用完它之后)。 如果成功,则应用可能会激活类并使用框架包中的内容。

  • Windows 11 (C/C++):AddPackageDependency
  • Windows App SDK (C/C++):MddAddPackageDependency
  • Windows App SDK (WinRT):PackageDependency.Add

调用此 API 时,必须传入在创建安装时引用时返回的依赖项 ID 以及进程包图中要用于框架包的所需级别。 此 API 会返回所引用的框架包的完整名称,以及用于跟踪活动使用依赖项的句柄。 如果安装了多个满足在创建安装时引用时指定的条件的框架包,则 API 会选择满足条件的最高版本。

3. 删除运行时引用

应用使用完框架包后,调用以下函数或方法之一可删除运行时引用。 通常,应用会在关闭过程中调用此 API。 此 API 会向操作系统告知可以安全地删除任何不必要的框架包版本。

  • Windows 11 (C/C++):RemovePackageDependency
  • Windows App SDK (C/C++):MddRemovePackageDependency
  • Windows App SDK (WinRT):PackageDependencyContext.Remove

调用此 API 时,必须传入添加运行时引用时返回的句柄。

4. 删除安装时引用

卸载应用时,可调用以下函数或方法之一来删除安装时引用。 此 API 会向操作系统告知如果没有其他应用依赖于框架包,则可以安全地删除框架包。

  • Windows 11 (C/C++):DeletePackageDependency
  • Windows App SDK (C/C++):MddDeletePackageDependency
  • Windows App SDK (WinRT):PackageDependency.Delete

调用此 API 时,必须传入创建安装时引用时返回的依赖项 ID。

Windows 应用 SDK 中的动态依赖项 API 限制

在 Windows 应用 SDK 中使用动态依赖项 API 以依赖于框架包时,此 API 需要通过其他已安装的包和正在运行的进程提供帮助,以向 Windows 告知框架包正在使用中,并在使用期间阻止为框架提供服务。 这称为“生存期管理器”组件。

Windows 应用 SDK 为其框架包提供了一个生存期管理器组件,称为动态依赖项生存期管理器 (DDLM)。 但是,当前没有其他框架包提供与 Microsoft 类似的生存期管理器组件。

Windows 11 中的动态依赖项 API 实现(在 appmodel.h 中)没有此限制。