教程：在使用 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 App 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. 在编辑器中打开资源文件后，使用以下属性创建新的字符串资源。

      • 名称：消息
      • 值：Hello, resources!

   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. 接下来，在主方法的开头添加此代码，以调用 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 部署指南
• 运行时体系结构