通过

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

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

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

在 Windows 应用 SDK 中，有几个例程的作业是确保正确初始化 Windows 应用运行时。 这些例程称为自动初始值设定项，因为它们在应用程序的入口点之前自动运行，并执行初始化工作。

小窍门

如果你对技术详细信息感到好奇。 在C++中，使用静态类构造函数实现自动初始值设定项。 在 C# 中，使用 .NET 模块初始值设定项实现自动初始值设定项。 因此，有时你可能会听到在正确术语是自动初始值设定项时使用的模块初始值设定项。

默认情况下，所有自动初始值设定项都会根据应用的打包和部署配置有条件地启用。 下面是有关它们的详细信息：

  • 引导程序（也称为动态依赖项）自动初始值设定项。 此自动初始值设定项在应用启动时自动调用引导程序 API。 依赖框架的未打包应用需要它，以确保将 Windows 应用运行时添加到应用的包图中。 有关依赖于框架的应用（和独立应用）的信息，请参阅 Windows 应用 SDK 部署概述。 有关解压缩（和打包）应用的信息，请参阅 Windows 应用：打包、部署和过程。
    • 对于打包的应用，不需要引导程序/动态依赖项自动初始值设定项，因为 appxmanifest.xml 该文件表示框架依赖项。 对于自包含应用，不需要引导程序/动态依赖项自动初始值设定项，因为这些应用不使用框架。
    • 可以选择退出引导程序/动态依赖项自动初始值设定项或.csproj.vcxproj文件中通过 <WindowsAppSdkBootstrapInitialize>false</WindowsAppSdkBootstrapInitialize>。
  • 部署管理器自动初始值设定项。 使用主/单一实例功能（例如推送通知）的依赖于框架的打包应用是必需的，因为 appxmanifest.xml 文件无法表达这些依赖项。
    • 对于独立应用，不需要部署管理器自动初始值设定项，因为这些应用不支持主/单一实例功能。
  • 无注册激活自动初始值设定项。 如果应用在低于 Windows 10 2019 年 5 月 10 日更新（版本 1903）的作系统版本上运行，则自包含应用需要使用基于清单的无注册 Windows 运行时（WinRT）激活（UndockedRegFreeWinRT），前提是该应用在低于 Windows 10 2019 年 5 月更新的作系统版本（版本 1903）上运行。
    • 对于依赖框架的应用以及面向 Windows 10 版本 1903 或更高版本的自包含应用，无需注册自动初始值设定项。 这些应用可以通过以下方式选择退出 <WindowsAppSdkUndockedRegFreeWinRTInitialize>false</WindowsAppSdkUndockedRegFreeWinRTInitialize>。
  • 兼容性自动初始值设定项。 应用需要使用 A/B 包含设施来控制服务发布行为。 有关详细信息，请参阅 RuntimeCompatibilityOptions。
    • 对于不使用 A/B 包含（默认值）的应用，不需要兼容性自动初始值设定项。

项目属性

这些是可以设置的属性，你可以使用应用的项目文件来指定修补程序级别和禁用的更改。 下面是有关如何在项目文件中指定修补程序级别和禁用更改的示例：

有关 Windows 应用 SDK 中的自动初始值设定项的详细信息，请参阅上一部分（上一部分）。

属性名称和说明 价值观 有关详细信息
AppxPackage。 指定是否打包 WinUI 3 应用。 false （对于未打包的应用），或不存在（对于打包的应用） 为未打包的 WinUI 3 桌面应用创建新项目
EnableMsixTooling。 为项目启用单项目 MSIX 功能。 true （若要启用），或缺席 （禁用） 使用单项目 MSIX 打包应用
UseWinUI。 指定是否在应用中使用 WinUI 3 用户界面框架。 true 或缺席 （对于 false） Windows 应用 SDK 中的 WinUI （WinUI 3）
WindowsAppSdkBootstrapInitialize。 确定 Windows 应用 SDK 是否利用引导程序/动态依赖项自动初始值设定项。 true （可执行文件的默认值）， false （非可执行文件的默认值） 选择退出（或加入）自动初始值设定项
WindowsAppSdkSelfContained。 确定应用是否部署 自包含。 true 或缺席 （对于 false） 适用于独立应用的 Windows 应用 SDK 部署指南
WindowsAppSdkUndockedRegFreeWinRTInitialize。 确定 Windows 应用 SDK 是否利用无注册激活自动初始值设定项。 true （可执行文件的默认值）， false （非可执行文件的默认值） 选择退出（或加入）自动 UndockedRegFreeWinRT 支持
WindowsPackageType。 为未打包的应用设置 <WindowsPackageType>None</WindowsPackageType> 会导致引导程序/动态依赖项自动初始值设定项查找并加载最适合应用的 Windows 应用 SDK 版本。 无或缺席（禁用自动初始值设定项） 为未打包的 WinUI 3 桌面应用创建新项目

幕后选择退出自动初始值设定项
WindowsAppSDKRuntimePatchLevel1、 WindowsAppSDKRuntimePatchLevel2 和 WindowsAppSDKDisabledChanges。 确定 Windows 应用 SDK 是否利用兼容性自动初始值设定项，并为在服务更新中添加的更改的 Windows 应用运行时行为配置任何所需的兼容性选项。 各种或不存在（禁用自动初始值设定项） RuntimeCompatibilityOptions

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>
...
  • Last updated on