教程：在使用 Windows 应用 SDK 的通过外部位置打包的应用或未打包应用中使用引导程序 API

本文介绍如何使用 MSIX (配置未安装的应用，即使用外部位置打包应用或未打包的应用) 使用引导程序 API，以便它显式加载Windows 应用 SDK运行时，并调用Windows 应用 SDK API。 未通过 MSIX 安装的应用包括使用外部位置打包的应用和未打包的应用。

重要

从 Windows 应用 SDK 1.0 开始，从使用外部位置打包或未打包的应用加载 Windows 应用 SDK 的默认方法是通过 <WindowsPackageType> 项目属性使用自动初始化（以及进行其他配置更改）。 有关 WinUI 3 项目上下文中自动初始化所涉及的步骤，请参阅 创建第一个 WinUI 3 项目。 或者，如果现有项目不是 WinUI 3，则请参阅在现有项目中使用 Windows 应用 SDK。

如果有高级需求（例如自定义错误处理或加载特定版本的 Windows 应用 SDK），则可以改为显式调用引导程序 API。 这就是本主题演示的方法。 此外，有关详细信息，请参阅将Windows 应用 SDK运行时用于使用外部位置打包或未打包的应用。

本主题演示如何从基本控制台应用项目显式调用引导程序 API;但这些步骤适用于使用 Windows 应用 SDK的任何未打包桌面应用。

在完成本教程之前，建议查看运行时体系结构，详细了解应用使用Windows 应用 SDK时使用的框架包依赖项，以及使用外部位置打包或未打包的应用所需的其他组件。

先决条件

1. 安装适用于 Windows 应用 SDK 的工具。
2. 确保已安装与外部位置打包的应用和未打包应用的所有依赖项， (请参阅Windows 应用 SDK部署指南，了解使用外部位置打包或未打包) 打包的依赖框架的应用。 执行此操作的一种简单方法是运行 Windows 应用 SDK 运行时安装程序。

说明

可以使用 C# 或 C++ 项目按照本教程进行操作。

注意

动态依赖项和引导程序 API 在由提升的进程调用时失败。 因此，不应以提升权限启动 Visual Studio。 有关更多详细信息 ，请参阅动态依赖项不支持提升 #567 。

C#

按照这些说明配置使用外部位置打包或未打包的 C# WinUI 3 项目。

1. 在 Visual Studio 中，创建新的 C# 控制台应用 项目。 将项目命名为“DynamicDependenciesTest”。 创建项目后，你应该有一个“Hello， World！”C# 控制台应用。

2. 接下来，配置项目。

   1. 在“解决方案资源管理器”中，右击项目，然后选择“编辑项目文件”。
   2. 将 TargetFramework 元素的值替换为目标框架名字对象。 例如，如果应用目标是 Windows 10 版本 2004，请使用以下项。

   <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
   

   1. 保存并关闭项目文件。

3. 将解决方案的平台更改为 x64。 .NET 项目中的默认值为 AnyCPU，但 WinUI 3 不支持该平台。

   1. 选择“生成”>“配置管理器”。
   2. 选择“活动解决方案平台”下的下拉列表，单击“新建”选项以打开“新建解决方案平台”对话框。
   3. 在“键入或选择新平台”下的下拉菜单中，选择“x64”。
   4. 选择“确定”以关闭“新建解决方案平台”对话框。
   5. 在“配置管理器”中，单击“关闭”。

4. 在项目中安装 Windows 应用 SDK NuGet 包。

   1. 在“解决方案资源管理器”中，右键单击“依赖项”节点，然后选择“管理 NuGet 包”。
   2. 在 “NuGet 包管理器 ”窗口中，选择“ 浏览 ”选项卡，然后安装 Microsoft.WindowsAppSDK 包。

5. 现已准备好使用引导程序 API (请参阅对使用外部位置打包的应用使用Windows 应用 SDK运行时或未打包) 动态获取Windows 应用 SDK框架包的依赖项。 这使你能够在应用中使用 Windows 应用 SDK API。

   打开 Program.cs 代码文件，将默认代码替换为以下代码，以调用 Bootstrap.Initialize 方法初始化引导程序。 此代码定义初始化引导程序时应用所依赖的Windows 应用 SDK版本。

   重要

   需要编辑以下代码以适应特定配置。 请参阅 Bootstrap.Initialize 方法的参数说明，以便可以指定已安装的 Windows 应用 SDK版本之一。

   using System;
   using Microsoft.Windows.ApplicationModel.DynamicDependency;
   
   namespace DynamicDependenciesTest
   {
       class Program
       {
           static void Main(string[] args)
           {
               Bootstrap.Initialize(0x00010002);
               Console.WriteLine("Hello, World!");
   
               // Release the DDLM and clean up.
               Bootstrap.Shutdown();
           }
       }
   }
   

   引导程序 API 是一个本机 C/C++ API，可用于在应用中使用Windows 应用 SDK API。 但在使用 Windows 应用 SDK 1.0 或更高版本的 .NET 应用中，可以将 .NET 包装器用于引导程序 API。 与直接调用本机 C/C++ 函数相比，该包装器提供了在 .NET 应用中调用引导程序 API 的更简单方法。 前面的代码示例在引导程序 API 的 .NET 包装器中调用 Bootstrap 类的静态 Initialize 和 Shutdown 方法。

6. 为了演示已正确加载 Windows 应用 SDK 运行时组件，请添加一些使用 Windows 应用 SDK 中的 ResourceManager 类加载字符串资源的代码。

   1. 向项目添加新 的资源文件 (.resw) ， (保留默认名称) 。

   2. 在编辑器中打开资源文件后，使用以下属性创建新的字符串资源。

      • 名称：消息
      • 值： 你好，资源！

   3. 保存资源文件。

   4. 打开 Program.cs 代码文件，并将 行替换为 Console.WriteLine("Hello, World!"); 以下代码。

   // Create a resource manager using the resource index generated during build.
    var manager = new Microsoft.Windows.ApplicationModel.Resources.ResourceManager("DynamicDependenciesTest.pri");
   
   // Look up a string in the .resw file using its name.
   Console.WriteLine(manager.MainResourceMap.GetValue("Resources/Message").ValueAsString);
   

   1. 单击 “启动但不调试 (”或 “开始调试) 以生成并运行应用。 应会看到字符串 Hello, resources! 已成功显示。

C++

按照这些说明配置使用外部位置打包或未打包的 C++ WinUI 3 项目。

1. 在 Visual Studio 中创建新的 C++ 控制台应用项目。 将项目命名为“DynamicDependenciesTest”。

   

   创建项目后，你应该有一个“Hello， World！”C++ 控制台应用。

2. 接下来，在项目中安装 Windows 应用 SDK NuGet 包。

   1. 在“解决方案资源管理器”中，右键单击“引用”节点，然后选择“管理 NuGet 包”。
   2. 在 “NuGet 包管理器 ”窗口中，选择“ 浏览 ”选项卡，然后搜索 “Microsoft.WindowsAppSDK”。

3. 现在，你已准备好使用引导程序 API (请参阅将Windows 应用 SDK运行时用于使用外部位置打包的应用或未打包) 初始化应用中的Windows 应用 SDK运行时。 这使你能够在应用中使用 Windows 应用 SDK API。

   1. 将以下包含文件添加到 DynamicDependenciesTest.cpp 文件顶部。 可以通过 Windows 应用 SDK NuGet 包获取 mddbootstrap.h 标头。

   #include <windows.h>
   #include <MddBootstrap.h>
   

   1. 接下来，在 main 方法的开头添加此代码，以调用 MddBootstrapInitialize 函数来初始化引导程序并处理任何错误。 此代码定义初始化引导程序时应用所依赖的Windows 应用 SDK版本。

   重要

   需要编辑以下代码以适应特定配置。 请参阅 MddBootstrapInitialize 函数的参数说明，以便可以指定已安装的 Windows 应用 SDK版本之一。

   const UINT32 majorMinorVersion{ 0x00010002 }; 
   PCWSTR versionTag{ L"" }; 
   const PACKAGE_VERSION minVersion{};
   
   const HRESULT hr{ MddBootstrapInitialize(majorMinorVersion, versionTag, minVersion) }; 
   
   // Check the return code for errors. If there is an error, display the result.
   if (FAILED(hr)) 
   { 
       wprintf(L"Error 0x%X in MddBootstrapInitialize(0x%08X, %s, %hu.%hu.%hu.%hu)\n", 
           hr, majorMinorVersion, versionTag, minVersion.Major, minVersion.Minor, minVersion.Build, minVersion.Revision); 
       return hr; 
   } 
   

   1. 最后，添加此代码以显示字符串 Hello, World! ，并调用 MddBootstrapShutdown 函数以取消初始化引导程序。

   std::cout << "Hello, World!\n"; 
   
   // Release the DDLM and clean up.
   MddBootstrapShutdown(); 
   

   1. 最终代码应如下所示。

   #include <iostream> 
   #include <windows.h> 
   #include <MddBootstrap.h>
   
   int main() 
   { 
       // Take a dependency on Windows App SDK Stable.
       const UINT32 majorMinorVersion{ 0x00010002 }; 
       PCWSTR versionTag{ L"" }; 
       const PACKAGE_VERSION minVersion{};
   
       const HRESULT hr{ MddBootstrapInitialize(majorMinorVersion, versionTag, minVersion) }; 
   
       // Check the return code. If there is a failure, display the result.
       if (FAILED(hr)) 
       { 
           wprintf(L"Error 0x%X in MddBootstrapInitialize(0x%08X, %s, %hu.%hu.%hu.%hu)\n", 
               hr, majorMinorVersion, versionTag, minVersion.Major, minVersion.Minor, minVersion.Build, minVersion.Revision); 
           return hr; 
       } 
   
       std::cout << "Hello, World!\n"; 
   
       // Release the DDLM and clean up.
       MddBootstrapShutdown(); 
   } 
   

4. 单击 “启动但不调试 (”或 “开始调试) 以生成并运行应用。

如果项目是 WPF

有关Windows Presentation Foundation (WPF) 应用，请参阅在 WPF 应用中使用Windows 应用 SDK。

相关主题

• 依赖于框架的使用外部位置打包的应用或未打包应用的 Windows 应用 SDK 部署指南
• 运行时体系结构