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

项目
07/05/2024

本文介绍如何配置未使用 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时使用的框架包依赖项，以及使用外部位置或未打包的应用进行打包所需的其他组件。

先决条件

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

说明

可以使用 C# 或 C++ 项目遵循本教程。

注意

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

按照这些说明配置 C# WinUI 3 项目，该项目打包到外部位置或解压缩。

在 Visual Studio 中，创建新的 C# 控制台应用 项目。将项目命名为“DynamicDependenciesTest”。创建项目后，应具有“Hello， World！”C# 控制台应用。
接下来，配置项目。
1. 在“解决方案资源管理器”中，右击项目，然后选择“编辑项目文件”。
2. 将 TargetFramework 元素的值替换为目标框架名字对象。例如，如果应用目标是 Windows 10 版本 2004，请使用以下项。
```
<TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
```
1. 保存并关闭项目文件。
将解决方案的平台更改为 x64。 .NET 项目中的默认值为 AnyCPU，但 WinUI 3 不支持该平台。
1. 选择生成>配置管理器。
2. 选择“活动解决方案平台”下的下拉列表，单击“新建”选项以打开“新建解决方案平台”对话框。
3. 在“键入或选择新平台”下的下拉菜单中，选择“x64”。
4. 选择“确定”以关闭“新建解决方案平台”对话框。
5. 在“配置管理器”中，单击“关闭”。
在项目中安装 Windows 应用 SDK NuGet 包。
1. 在“解决方案资源管理器”中，右键单击“依赖项”节点，然后选择“管理 NuGet 包”。
2. 在 NuGet 程序包管理器窗口中，选择“浏览”选项卡，并安装 Microsoft.WindowsAppSDK 包。
现在，可以使用引导程序 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 方法。
为了演示已正确加载 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++ WinUI 3 项目。

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

创建项目后，应具有“Hello， World！”C++控制台应用。
接下来，在项目中安装 Windows 应用 SDK NuGet 包。
1. 在“解决方案资源管理器”中，右键单击“引用”节点，然后选择“管理 NuGet 包”。
2. 在 NuGet 程序包管理器 窗口中，选择“浏览”选项卡，然后搜索 Microsoft.WindowsAppSDK。

现在，可以使用引导程序 API（请参阅使用打包到外部位置或未打包的应用的Windows 应用 SDK运行时）来初始化应用中的Windows 应用 SDK运行时。这使你能够在应用中使用 Windows 应用 SDK API。

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

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

接下来，在主方法的开头添加此代码，以调用 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; 
}

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

std::cout << "Hello, World!\n"; 

// Release the DDLM and clean up.
MddBootstrapShutdown();

最终代码应如下所示。

#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(); 
}

单击“不调试启动”（或“开始调试”）生成并运行应用。

如果项目为 WPF

对于 Windows Presentation Foundation（WPF）应用，请参阅在 WPF 应用中使用Windows 应用 SDK。

通过

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

先决条件

说明

如果项目为 WPF

相关主题

其他资源