项目属性和自动初始值设定项

本主题介绍可在Visual Studio project文件(如 .csproj 或 .vcxproj)中设置的project属性,以便自定义应用的部署方式,包括配置自动初始值设定项。

Windows 应用 SDK中的自动初始值设定项

在Windows 应用 SDK中,有几个例程的作业是为了确保正确初始化Windows 应用运行时。 这些例程称为自动初始化程序,因为它们在应用程序入口之前自动运行,并完成初始化任务。

小窍门

如果你对技术详细信息感到好奇。 在C++中,自动初始化器是通过静态类构造函数实现的。 在 C# 中,自动初始化器是通过 .NET 模块初始化器实现的。 所以你可能有时会听到有人用模块初始化程序,而正确的术语应该是自动初始化程序。

默认情况下,根据应用的打包和部署配置,所有自动初始化器都会有条件地启用。 下面是有关它们的详细信息:

  • 引导程序(也称为动态依赖项)自动初始化程序。 此自动初始值设定项在应用启动时自动调用 Bootstrapper API,以将框架包添加到依赖框架的未打包应用的包图。 如果需要控制初始化,则可以改用显式 Bootstrapper 调用。 有关依赖于框架的应用(和自包含应用)的信息,请参阅 Windows 应用 SDK 部署概述。 有关解压缩(和打包)应用的信息,请参阅 Windows 应用:打包、部署和过程。
    • 对于打包的应用(包括打包了外部位置的应用(稀疏包)),请在 AppxManifest.xml 中使用 <PackageDependency> 静态声明框架依赖项;不需要为该依赖项进行启动程序初始化。 自包含应用不需要 Bootstrapper 初始化,因为它在本地承载框架二进制文件,而不是引用 Framework MSIX 包。
    • 可以在 .csproj 或 .vcxproj 文件中通过 <WindowsAppSdkBootstrapInitialize>false</WindowsAppSdkBootstrapInitialize> 来选择禁用引导程序/动态依赖项自动初始化程序。
  • 部署管理器自动初始化器。 这对于使用主程序/单例功能(例如推送通知)的框架依赖型打包应用是必需的,因为 appxmanifest.xml 文件无法表达这些依赖关系。
    • 对于独立应用,不需要使用 Deployment Manager 自动初始化器,因为这些应用不支持主功能/单例模式。
    • 有关更多详细信息,请参阅本主题后面的 部署管理器自动初始值设定项 部分。
  • 免注册激活的自动初始化组件。 如果应用在早于 Windows 10 2019 年 5 月更新(版本 1903;代号为“19H1”)的操作系统版本上运行,则独立应用必须使用基于清单的未对接免注册 Windows 运行时 (WinRT) 激活 (UndockedRegFreeWinRT)。
    • 对于依赖框架型应用以及面向 Windows 10 版本 1903 或更高版本的独立应用,你不需要免注册激活自动初始化程序。 这些应用可以通过 <WindowsAppSdkUndockedRegFreeWinRTInitialize>false</WindowsAppSdkUndockedRegFreeWinRTInitialize> 选择退出。
  • 兼容性自动初始化工具。 应用必须使用 A/B 分组控制机制来控制服务发布行为。 有关详细信息,请参阅 RuntimeCompatibilityOptions。
    • 对于不使用 A/B 容器(即默认设置)的应用程序,不需要使用兼容性自动初始化器。

部署管理器自动初始化工具

当使用 Windows 应用 SDK 1.8 或更高版本的应用启动时,部署管理器自动初始化程序会默认运行。 但你可以选择退出该流程。 本部分介绍允许部署管理器自动初始值设定项运行的好处和注意事项,这有助于你决定是否选择退出。

为了使应用能够使用 Main/Singleton 包(例如推送通知):1。必须使用部署 API 来确保部署这些包(因为 Main/Singleton 包不是框架,而是“主”包,如应用);因此它们不能注册为应用的 appx 清单中的依赖项。相反,部署 API 提供了部署这些包的功能。 2. 由于 1,应用需要通过调用 DeploymentManager.Initialize 来初始化部署管理器。 应用可以自动或显式执行这项操作,正如我们将看到的。 3. 你的应用需要是一个框架依赖型打包应用,这样才能依赖于主程序/单例包。

初始化部署管理器的一种方法是允许部署管理器自动初始化程序运行(请参阅本主题前面介绍的 Windows 应用 SDK 的“自动初始化程序”部分)。 部署管理器自动初始化程序为你调用 DeploymentManager.Initialize。 初始化部署管理器的另一种方法是显式调用 DeploymentManager.Initialize 。

如果你的应用(使用 Windows 应用 SDK 1.8 或更高版本)不需要 Main/Singleton 包, 然后,应通过在应用的project文件中将 WindowsAppSdkDeploymentManagerInitialize 属性设置为 false 来选择退出部署管理器自动初始值设定项。

如果你的应用(使用 Windows 应用 SDK 1.8 或更高版本)确实需要 Main/Singleton 包,则可以:

  • 允许部署管理器的自动初始化器运行(默认情况下会自动运行),
  • 或者通过在应用程序的项目文件中将WindowsAppSdkDeploymentManagerInitialize 属性设置为false,退出部署管理器自动初始值设定项。 然后,您应该自行显式调用 DeploymentManager.Initialize。

重要

对于在 AppContainer 中运行的任何进程,如果导致调用 DeploymentManager.Initialize,则应用需要在packageManagement中声明受限功能。

项目属性

下表是可在应用的project文件中设置的属性。 有关Windows 应用 SDK中的自动初始值设定项的详细信息,请参阅上一部分(上一节)。

属性名称和说明 价值观 有关详细信息
AppxPackage。 指定是否打包 WinUI 应用。 false (对于未打包的应用),或省略(对于打包的应用) 取消打包 WinUI 应用
EnableMsixTooling。 为项目启用单项目MSIX功能。 true(若要启用),或省略(若要禁用) 使用单项目 MSIX 打包应用
UseCrtSDKReferenceStaticWarning。 抑制当 C++ 打包应用以静态方式链接 CRT 时触发的生成警告(这是使用混合 CRT 进行独立部署所必需的)。 对于选择使用 混合 CRT 的打包应用项目,将其设置为 false。 false (禁止在打包的自包含应用中显示警告),或不存在(默认启用警告) 适用于独立应用的Windows 应用 SDK部署指南
UseWinUI。 指定是否在应用中使用 WinUI 用户界面框架。 true,或省略(对于 false) Windows 应用 SDK中的 WinUI (WinUI)
WindowsAppSDKSingleFileVerifyConfiguration。 控制在设置 PublishSingleFile 时,SDK 是否运行生成时验证目标。 启用后(默认情况下),如果缺少必需的属性(WindowsPackageType=None、IncludeAllContentForSelfExtract、),目标将发出EnableMsixTooling;如果缺少自包含设置(SelfContained、),则会发出WindowsAppSDKSelfContained。 仅在需要禁用所有检查时才将其设置为 false——例如,在已手动验证合规性的 CI 管道中。 true (默认 — 会运行验证), false (禁止所有检查) 在 Microsoft.WindowsAppSDK.SingleFile.targets 中定义(设置 PublishSingleFile 时由 NuGet 包自动包含)
WindowsAppSdkBootstrapInitialize。 确定 Windows 应用 SDK 是否使用引导程序/动态依赖项的自动初始化器。 对于依赖框架且带有 的可执行文件,默认情况下为 WindowsPackageType=None;默认情况下,不为自包含、打包或非可执行项目启用 选择退出(或选择加入)自动初始化项
WindowsAppSdkDeploymentManagerInitialize。 确定Windows 应用 SDK是否利用该部署管理器自动初始化器。 true (默认值), false
WindowsAppSDKRuntimePatchLevel1、 WindowsAppSDKRuntimePatchLevel2 和 WindowsAppSDKDisabledChanges。 确定 Windows 应用 SDK 是否使用兼容性自动初始化程序,并为通过服务更新添加的更改的 Windows 应用 运行时行为配置任何所需的兼容性选项。 各种,或缺失(禁用自动初始化程序) RuntimeCompatibilityOptions
WindowsAppSDKSelfContained。 确定应用是否以独立部署的方式部署。 true,或省略(对于 false) 适用于独立应用的Windows 应用 SDK部署指南
WindowsAppSdkUndockedRegFreeWinRTInitialize。 确定 Windows 应用 SDK 是否利用免注册激活自动初始化程序。 true (可执行文件的默认值), false (非可执行文件的默认值) 选择退出(或加入)自动 UndockedRegFreeWinRT 支持
WindowsPackageType。 默认情况下,为未打包的依赖于框架的可执行文件设置 <WindowsPackageType>None</WindowsPackageType> 可启用 Bootstrapper 自动初始值设定项。 它不会为自包含部署启用 Bootstrapper 初始化。 None 用于未打包的应用,或对于打包的应用则省略 取消打包 WinUI 应用

幕后机制,以及选择退出自动初始值设定项

Example

下面是一个 C# WinUI 3 项目的典型 .csproj 文件的摘录,展示了上表中的一些项目属性的应用。

...
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
    ...
    <UseWinUI>true</UseWinUI>
    <EnableMsixTooling>true</EnableMsixTooling>
  </PropertyGroup>
...