为使用外部位置打包的应用或未打包的应用使用 Windows App SDK 运行时

项目
06/24/2024

注意

如果使用 MSIX 技术安装应用，请参阅依赖框架的打包应用的Windows 应用 SDK部署指南。

如果未使用 MSIX 安装应用（也就是说，它打包为外部位置或未打包），则必须初始化要使用的Windows 应用 SDK，然后才能调用 winUI 3、应用生命周期、MRT Core 和 DWriteCore 等Windows 应用 SDK功能。应用在使用Windows 应用 SDK的任何其他功能之前，必须先初始化Windows 应用 SDK运行时。

从 Windows 应用 SDK 1.0 开始，当应用通过自动初始化（设置项目属性<WindowsPackageType>None</WindowsPackageType>）开始时，可以自动完成此操作。有关演示，请参阅创建第一个 WinUI 3 项目。
但是，如果你有高级需求（例如通过显示自己的自定义 UI 或日志记录来处理错误），或者需要加载与你生成的版本不同的Windows 应用 SDK版本，请继续阅读本主题。在这些方案中，可以显式调用引导程序 API，而不是自动初始化。

上述两种技术中的任何一种都允许使用 MSIX 的应用在运行时对Windows 应用 SDK采用动态依赖项。

有关动态依赖项的背景信息，请参阅 MSIX 框架包和动态依赖项。

在幕后，并选择退出自动模块初始化

上述属性生成的 WindowsPackageType 代码利用模块初始值设定项调用引导程序 API。引导程序执行繁重的工作来查找Windows 应用 SDK，并使当前进程能够使用它。生成的代码处理初始化和关闭。可以使用以下项目属性控制初始化的行为：

<WindowsAppSDKBootstrapAutoInitializeOptions_Default>true</WindowsAppSDKBootstrapAutoInitializeOptions_Default>
- 使用默认选项。
<WindowsAppSDKBootstrapAutoInitializeOptions_None>true</WindowsAppSDKBootstrapAutoInitializeOptions_None>
- 不使用任何选项。
<WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak>
- 如果发生错误，请调用 DebugBreak（）。
<WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached>
- 如果仅在调试器附加到进程时发生错误，则调用 DebugBreak（）。
<WindowsAppSDKBootstrapAutoInitializeOptions_OnError_FailFast>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_FailFast>
- 如果发生错误，则执行快速故障。
<WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>
- 如果找不到匹配的运行时，提示用户获取Windows 应用 SDK运行时。
<WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>
- 如果在具有包标识的进程中调用（否则失败并返回错误），则为 Succceed。

如果希望应用具有显式控制，则可以在应用程序的启动初期直接调用 boostrapper API。在这种情况下，项目文件中不需要 WindowsPackageType 。

注意

除了自动初始化和引导程序 API， Windows 应用 SDK 还提供了动态依赖 API 的实现。此 API 使你的未打包应用程序能够依赖于任何框架包（不仅仅是 Windows 应用 SDK 框架包），并且它由引导程序 API 在内部使用。有关动态依赖项 API 的详细信息，请参阅使用动态依赖项 API 在运行时引用 MSIX 包。

选择退出（或加入）自动模块初始化

项目属性 <WindowsAppSdkBootstrapInitialize>false</WindowsAppSdkBootstrapInitialize> 禁用上述自动模块初始化（未调用引导程序 API）。这样，应用就可以承担责任，并直接调用引导程序 API。

从Windows 应用 SDK版本 1.2 开始，自动模块初始化仅适用于生成可执行文件的项目（即 OutputType 项目属性设置为 Exe 或 WinExe）。这是为了防止默认将自动初始值设定项添加到类库 DLL 和其他非可执行文件中。如果需要非可执行文件中的自动初始值设定项（例如，由不初始化引导程序的主机进程可执行文件加载的测试 DLL），则可以使用 <WindowsAppSdkBootstrapInitialize>true</WindowsAppSdkBootstrapInitialize> 在项目中显式启用自动初始值设定项。

使用引导程序 API

重要

从版本 1.1 开始，下面提到的 MddBootstrapInitialize2 函数可用。

引导程序 API 由三个 C/C++ 函数组成，这些函数在 Windows 应用 SDK 中的 mddbootstrap.h 头文件中声明：MddBootstrapInitialize、MddBootstrapInitialize2 和 MddBootstrapShutdown。这些函数由Windows 应用 SDK中的引导程序库提供。该库是一个小 DLL，必须随应用一起分发;它不是框架包本身的一部分。

MddBootstrapInitialize2

此函数初始化调用过程以使用最符合你传递给函数参数的条件的 Windows 应用 SDK 框架包版本。通常，这会导致引用与安装的 Windows 应用 SDK NuGet 包匹配的框架包的版本。如果多个包满足条件，则选择最佳候选项。此函数必须是应用启动中的第一个调用之一，以确保引导程序组件可以正确初始化 Windows 应用 SDK 并将运行时引用添加到框架包。

引导程序 API 使用动态依赖项 API 将Windows 应用 SDK运行时的框架包添加到当前进程的包图中，否则启用对包的访问。

此函数还初始化动态依赖生命周期管理器 (DDLM)。该组件提供基础结构，以防止操作系统在未打包的应用使用Windows 应用 SDK框架包时提供服务。

MddBootstrapShutdown

此函数将删除对通过调用 MddBootstrapInitialize 进行的当前进程的更改。调用此函数后，你的应用将无法再调用 Windows 应用 SDK API，包括动态依赖 API。

此功能还会关闭动态依赖生命周期管理器 (DDLM)，以便 Windows 可以根据需要为框架包提供服务。

引导程序 API 的 .NET 包装器

尽管可以直接从 .NET 应用调用 C/C++ 引导程序 API，但需要使用平台调用来调用函数。在 Windows 应用 SDK 1.0 及更高版本中，可以在程序集中使用Microsoft.WindowsAppRuntime.Bootstrap.Net.dll引导程序 API 的 .NET 包装器。该程序集为 .NET 开发人员提供更简单、更自然的 API 来访问引导程序的功能。 Bootstrap 类提供静态 Initialize、TryInitialize 和 Shutdown 函数，用于包装对 MddBootstrapInitialize 和 MddBootstrapShutdown 函数的调用，用于大多数常见方案。有关演示如何对引导程序 API 使用 .NET 包装的示例，请参阅教程中的 C# 说明：在打包到外部位置的应用中使用引导程序 API，或使用Windows 应用 SDK解压缩。

有关引导程序 API 的 .NET 包装器的更多信息，请参阅以下资源：

引导程序 C# API。
动态依赖规范的第 6.1.4 节。
Bootstrap.cs：用于引导程序 API 的 .NET 包装器的开源实现。

引导程序 API 的C++包装器

从 Windows 应用 SDK 1.1 开始，启动程序 API 的C++包装器可用。

请参阅 Bootstrapper C++ API。

在应用程序清单中声明 OS 兼容性

若要声明操作系统（OS）兼容性，并避免默认为 Windows 8 行为（以及潜在的崩溃）的Windows 应用 SDK，可以包含与外部位置或未打包的应用打包的并行应用程序清单。请参阅应用程序清单（该文件声明了 DPI 感知等内容，并且在生成过程中被嵌入到应用的 .exe）。如果要向现有应用添加Windows 应用 SDK支持，而不是通过 Visual Studio 项目模板创建新应用，则可能是个问题。

如果项目中还没有并行应用程序清单，请向项目添加新的 XML 文件，并在应用程序清单中将其命名为建议。将兼容性元素和以下示例中显示的子元素添加到文件中。这些值控制应用进程中运行的组件的怪癖级别。

将 maxversiontested 元素的 Id 属性替换为你面向的 Windows 版本号（必须为 10.0.17763.0 或更高版本）。请注意，设置更高的值意味着旧版本的 Windows 不会正确运行你的应用，因为每个 Windows 版本只知道之前的版本。因此，如果你希望你的应用在 Windows 10 版本 1809（10.0）上运行，生成 17763），然后应保留 10.0.17763.0 值，或者为应用支持的不同值添加多个 经过 maxversiontested 的元素。

<?xml version="1.0" encoding="UTF-8"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
    <compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
        <application>
            <!-- Windows 10, version 1809 (10.0; Build 17763) -->
            <maxversiontested Id="10.0.17763.0"/>
            <supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}" />
        </application>
    </compatibility>
</assembly>

通过