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

注意

如果使用 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>
  • <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 的详细信息,请参阅 在运行时引用框架包

选择退出自动模块初始化

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

使用引导程序 API

重要

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

引导 API 包含三个 C/C++ 函数,这些函数在Windows 应用 SDK中的 mddbootstrap.h 头文件中声明:MddBootstrapInitialize、MddBootstrapInitialize2MddBootstrapShutdown 这些函数由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 类提供静态 InitializeTryInitializeShutdown 函数,用于包装对 MddBootstrapInitializeMddBootstrapShutdown 函数的调用,以用于大多数常见方案。 有关演示如何对引导程序 API 使用 .NET 包装器的示例,请参阅教程中的 C# 说明:在打包到外部位置的应用中使用引导程序 API,或使用Windows 应用 SDK解压缩

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

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

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

请参阅 Bootstrapper C++ API

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

若要声明操作系统 (操作系统) 兼容性,并且为了避免默认Windows 应用 SDK默认Windows 8行为 (和潜在崩溃) ,可以将并行应用程序清单与打包到外部位置或未打包的应用一起包含。 请参阅应用程序清单(该文件声明了 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>