Merging changes synced from https://github.com/MicrosoftDocs/windows-dev-docs-pr (branch live)

Author: Learn Build Service GitHub App

hub/apps/package-and-deploy/project-properties.md

@@ -1,28 +1,54 @@
 ---
-title: Project properties
-description: This topic describes the project properties that you can set in your Visual Studio project file to customize how your app is deployed.
+title: Project properties and auto-initializers
+description: Describes the project properties that you can set in your Visual Studio project file to customize how your app is deployed, including configuring auto-initializers.
 ms.topic: article
-ms.date: 11/17/2022
+ms.date: 08/29/2025
 ms.localizationpriority: medium
 ---
 
-# Project properties
+# Project properties and auto-initializers
 
-This topic describes the project properties that you can set in your Visual Studio project file to customize how your app is deployed.
+This topic describes the project properties that you can set in your Visual Studio project file (such as `.csproj` or `.vcxproj`) in order to customize how your app is deployed, including configuring auto-initializers.
+
+## Auto-initializers in the Windows App SDK
+
+In the Windows App SDK, there are several routines whose job it is to ensure that the Windows App Runtime is properly initialized. These routines are known as auto-initializers, because they run automatically before your application's entry point, and do initialization work for you.
+
+> [!TIP]
+> In case you're curious about technical details. In C++, an auto-initializer is implemented with a static class constructor. In C#, an auto-initializer is implemented with a .NET module initializer. So you might sometimes hear *module initializer* used when the proper term is *auto-initializer*.
+
+All of the auto-initializers are conditionally enabled by default, based on your app's packaging and deployment configuration. Here are details about them:
+
+* Bootstrapper (also known as dynamic dependencies) auto-initializer. This auto-initializer calls the bootstrapper API automatically at app startup. It's required for framework-dependent unpackaged apps, in order to ensure that the Windows App Runtime is added to the app's package graph. For info about framework-dependent (and self-contained) apps, see [Windows App SDK deployment overview](/windows/apps/package-and-deploy/deploy-overview). For info about unpackaged (and packaged) apps, see [Windows apps: packaging, deployment, and process](/windows/apps/get-started/intro-pack-dep-proc).
+  * For a packaged app, you don't need the bootstrapper/dynamic dependencies auto-initializer because the `appxmanifest.xml` file expresses the framework dependency. And for a self-contained app, you don't need the bootstrapper/dynamic dependencies auto-initializer because those apps don't use the framework.
+  * You can opt out of the bootstrapper/dynamic dependencies auto-initializer in your `.csproj` or `.vcxproj` file via `<WindowsAppSdkBootstrapInitialize>false</WindowsAppSdkBootstrapInitialize>`.
+* Deployment Manager auto-initializer. This is required for framework-dependent packaged apps that make use of main/singleton functionality (for example, push notifications), because the `appxmanifest.xml` file can't express those dependencies.
+  * For a self-contained app, you don't need the Deployment Manager auto-initializer because those apps don't support main/singleton functionality.
+* Registration-free activation auto-initializer. This is required for a self-contained app to use manifest-based undocked registration-free Windows Runtime (WinRT) activation (*UndockedRegFreeWinRT*), if the app is running downlevel on an operating system version earlier than Windows 10 May 2019 Update (version 1903; codenamed "19H1").
+  * For framework-dependent apps, and for self-contained apps that target Windows 10, version 1903, or later, you don't need the registration-free activation auto-initializer. Those apps can opt out via `<WindowsAppSdkUndockedRegFreeWinRTInitialize>false</WindowsAppSdkUndockedRegFreeWinRTInitialize>`.
+* Compatibility auto-initializer. This is required for an app to use A/B containment facilities to control servicing release behavior. For more info, see [RuntimeCompatibilityOptions](/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.windowsappruntime.runtimecompatibilityoptions).
+  * For apps that don't use A/B containment (which is the default), you don't need the compatibility auto-initializer.
+
+## Project properties
+
+These are the properties you can set You can use your app's project file to specify the patch level and disabled changes. Here's an example of how to specify the patch level and disabled changes in your project file :
+
+See the previous section (above) for details about the auto-initializers in the Windows App SDK.
 
 |Property name and description|Values|For more info|
 |-|-|-|
 |**AppxPackage**. Specifies whether or not a WinUI 3 app is packaged.|*false* (for an unpackaged app), or absent (for a packaged app)|[Create a new project for an unpackaged WinUI 3 desktop app](/windows/apps/winui/winui3/create-your-first-winui3-app#unpackaged-create-a-new-project-for-an-unpackaged-c-or-c-winui-3-desktop-app)|
 |**EnableMsixTooling**. Enables the single-project MSIX feature for a project.|*true* (to enable), or absent (to disable)|[Package your app using single-project MSIX](/windows/apps/windows-app-sdk/single-project-msix)|
 |**UseWinUI**. Specifies whether you're using the WinUI 3 user interface framework in your app.|*true*, or absent (for *false*)|[WinUI in the Windows App SDK (WinUI 3)](/windows/apps/winui/winui3/)|
-|**WindowsAppSdkBootstrapInitialize**. Determines whether or not the Windows App SDK leverages module initializers to call the bootstrapper API automatically at app startup.|*true* (the default for executables), *false* (the default for non-executables)|[Opting out of (or into) automatic module initialization](/windows/apps/windows-app-sdk/use-windows-app-sdk-run-time#opting-out-of-or-into-automatic-module-initialization)|
+|**WindowsAppSdkBootstrapInitialize**. Determines whether or not the Windows App SDK leverages the bootstrapper/dynamic dependencies auto-initializer.|*true* (the default for executables), *false* (the default for non-executables)|[Opting out of (or into) auto-initializers](/windows/apps/windows-app-sdk/use-windows-app-sdk-run-time#opting-out-of-or-into-automatic-module-initialization)|
 |**WindowsAppSdkSelfContained**. Determines whether or not an app is deployed *self-contained*.|*true*, or absent (for *false*)|[Windows App SDK deployment guide for self-contained apps](/windows/apps/package-and-deploy/self-contained-deploy/deploy-self-contained-apps)|
-|**WindowsAppSdkUndockedRegFreeWinRTInitialize**. Determines whether or not the Windows App SDK's implementation of undocked registration-free Windows Runtime (*UndockedRegFreeWinRT*) is enabled automatically at app startup.|*true* (the default for executables), *false* (the default for non-executables)|[Opting out of (or into) automatic UndockedRegFreeWinRT support](/windows/apps/package-and-deploy/self-contained-deploy/deploy-self-contained-apps#opting-out-of-or-into-automatic-undockedregfreewinrt-support)|
-|**WindowsPackageType**. Setting `<WindowsPackageType>None</WindowsPackageType>` for an unpackaged app causes the *auto-initializer* to locate and load a version of the Windows App SDK version that's most appropriate for your app.|*None*, or absent (to disable the auto-initializer)|[Create a new project for an unpackaged WinUI 3 desktop app](/windows/apps/winui/winui3/create-your-first-winui3-app#unpackaged-create-a-new-project-for-an-unpackaged-c-or-c-winui-3-desktop-app)<br/><br/>[Behind the scenes, and opting out of automatic module initialization](/windows/apps/windows-app-sdk/use-windows-app-sdk-run-time#behind-the-scenes-and-opting-out-of-automatic-module-initialization)|
+|**WindowsAppSdkUndockedRegFreeWinRTInitialize**. Determines whether or not the Windows App SDK leverages the Registration-free activation auto-initializer.|*true* (the default for executables), *false* (the default for non-executables)|[Opting out of (or into) automatic UndockedRegFreeWinRT support](/windows/apps/package-and-deploy/self-contained-deploy/deploy-self-contained-apps#opting-out-of-or-into-automatic-undockedregfreewinrt-support)|
+|**WindowsPackageType**. Setting `<WindowsPackageType>None</WindowsPackageType>` for an unpackaged app causes the bootstrapper/dynamic dependencies auto-initializer to locate and load a version of the Windows App SDK version that's most appropriate for your app.|*None*, or absent (to disable the auto-initializer)|[Create a new project for an unpackaged WinUI 3 desktop app](/windows/apps/winui/winui3/create-your-first-winui3-app#unpackaged-create-a-new-project-for-an-unpackaged-c-or-c-winui-3-desktop-app)<br/><br/>[Behind the scenes, and opting out of auto-initializers](/windows/apps/windows-app-sdk/use-windows-app-sdk-run-time#behind-the-scenes-and-opting-out-of-automatic-module-initialization)|
+|**WindowsAppSDKRuntimePatchLevel1**, **WindowsAppSDKRuntimePatchLevel2**, and **WindowsAppSDKDisabledChanges**. Determines whether or not the Windows App SDK leverages the compatibility auto-initializer, and configures any desired compatibility options for Windows App Runtime behavior of changes added in servicing updates.|Various, or absent (to disable the auto-initializer)|[RuntimeCompatibilityOptions](/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.windowsappruntime.runtimecompatibilityoptions)|
 
 ## Example
 
-Here's an excerpt from a typical `.csproj` file for a C# WinUI 3 project showing some of the project properties from the table above in use.
+Here's an excerpt from a typical `.csproj` file for a C# WinUI 3 project, showing some of the project properties from the table above in use.
 
 ```xml
 ...
@@ -40,4 +66,12 @@ Here's an excerpt from a typical `.csproj` file for a C# WinUI 3 project showing
 
 ## Related topics
 
-* [Deployment overview](./index.md)
+* [Deployment overview](/windows/apps/package-and-deploy/)
+* [Create your first WinUI 3 (Windows App SDK) project](/windows/apps/winui/winui3/create-your-first-winui3-app)
+* [Package your app using single-project MSIX](/windows/apps/windows-app-sdk/single-project-msix)
+* [RuntimeCompatibilityOptions](/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.windowsappruntime.runtimecompatibilityoptions)
+* [Use the Windows App SDK runtime for apps packaged with external location or unpackaged](/windows/apps/windows-app-sdk/use-windows-app-sdk-run-time)
+* [Windows App SDK deployment guide for self-contained apps](/windows/apps/package-and-deploy/self-contained-deploy/deploy-self-contained-apps)
+* [Windows App SDK deployment overview](/windows/apps/package-and-deploy/deploy-overview)
+* [Windows apps: packaging, deployment, and process](/windows/apps/get-started/intro-pack-dep-proc)
+* [WinUI in the Windows App SDK (WinUI 3)](/windows/apps/winui/winui3/)

hub/apps/windows-app-sdk/deployment-architecture.md

@@ -67,7 +67,7 @@ The bootstrapper is a library that must be included with your packaged with exte
 - Initialize the Dynamic Dependency Lifetime Manager (DDLM) for the Windows App SDK framework package.
 - Find and load the Windows App SDK framework package to the app's package graph.
 
-To accomplish these tasks, the nuget package leverages module initializers to wire up the bootstrapper for you. Simply set `<WindowsPackageType>None</WindowsPackageType>` in your project file. In advanced scenarios, if you want control over the initialization, you can call the bootstrapper API directly in your app's startup code (see [Tutorial: Use the bootstrapper API in an app packaged with external location or unpackaged that uses the Windows App SDK](tutorial-unpackaged-deployment.md)) so that it can properly initialize the system for the unpackaged app. Your app must use the bootstrapper API before it can use Windows App SDK features such as WinUI, App lifecycle, MRT Core, and DWriteCore.
+To accomplish these tasks, the nuget package leverages [auto-initializers](/windows/apps/package-and-deploy/project-properties#auto-initializers-in-the-windows-app-sdk) to wire up the bootstrapper for you. Simply set `<WindowsPackageType>None</WindowsPackageType>` in your project file. In advanced scenarios, if you want control over the initialization, you can call the bootstrapper API directly in your app's startup code (see [Tutorial: Use the bootstrapper API in an app packaged with external location or unpackaged that uses the Windows App SDK](tutorial-unpackaged-deployment.md)) so that it can properly initialize the system for the unpackaged app. Your app must use the bootstrapper API before it can use Windows App SDK features such as WinUI, App lifecycle, MRT Core, and DWriteCore.
 
 The bootstrapper library in the Windows App SDK 1.0 release includes:
 

hub/apps/windows-app-sdk/use-windows-app-sdk-run-time.md

@@ -2,7 +2,7 @@
 title: Use the Windows App SDK runtime for apps packaged with external location or unpackaged
 description: If your app isn't installed by using MSIX (that is, it's packaged with external location or unpackaged), then you must initialize the Windows App SDK for use before you can call Windows App SDK features such as WinUI 3, App Lifecycle, MRT Core, and DWriteCore.
 ms.topic: article
-ms.date: 07/14/2025
+ms.date: 08/29/2025
 ms.localizationpriority: medium
 ---
 
@@ -20,9 +20,9 @@ Either of the two techniques above allows an app that doesn't use MSIX to take a
 
 For background information about dynamic dependencies, see [MSIX framework packages and dynamic dependencies](../desktop/modernize/framework-packages/framework-packages-overview.md).
 
-## Behind the scenes, and opting out of automatic module initialization
+## Behind the scenes, and opting out of auto-initializers
 
-The code generated by the `WindowsPackageType` property mentioned above leverages module initializers to call the bootstrapper API. The bootstrapper does the heavy lifting to find the Windows App SDK and enable the current process to use it. The generated code handles both initialization and shutdown. You can control initialization's behavior with the following project properties:
+The code generated by the `WindowsPackageType` property mentioned above leverages [auto-initializers](/windows/apps/package-and-deploy/project-properties#auto-initializers-in-the-windows-app-sdk) to call the bootstrapper API. The bootstrapper does the heavy lifting to find the Windows App SDK and enable the current process to use it. The generated code handles both initialization and shutdown. You can control initialization's behavior with the following project properties:
 
 * `<WindowsAppSDKBootstrapAutoInitializeOptions_Default>true</WindowsAppSDKBootstrapAutoInitializeOptions_Default>`
     * Use default options.
@@ -46,11 +46,11 @@ If you want your app to have explicit control, then you can directly call the bo
 > [!NOTE]
 > In addition to the automatic initialization and the bootstrapper API, the Windows App SDK also provides an implementation of the *dynamic dependency API*. This API enables your unpackaged apps to take a dependency on *any* framework package (not just the Windows App SDK framework package), and it is used internally by the bootstrapper API. For more information about the dynamic dependency API, see [Use the dynamic dependency API to reference MSIX packages at run time](../desktop/modernize/framework-packages/use-the-dynamic-dependency-api.md).
 
-### Opting out of (or into) automatic module initialization
+### Opting out of (or into) auto-initializers
 
-The project property `<WindowsAppSdkBootstrapInitialize>false</WindowsAppSdkBootstrapInitialize>` disables the automatic module initialization described above (the bootstrapper API isn't called). That allows your app to take responsibility and directly call the bootstrapper API.
+The project property `<WindowsAppSdkBootstrapInitialize>false</WindowsAppSdkBootstrapInitialize>` disables the auto-initializer described above (the bootstrapper API isn't called). That allows your app to take responsibility, and directly call the bootstrapper API.
 
-As of version 1.2 of the Windows App SDK (from the stable channel), automatic module initialization applies only to projects that produce an executable (that is, the **OutputType** project property is set to *Exe* or *WinExe*). This is to prevent adding auto-initializers into class library DLLs and other non-executables by default. If you *do* need an auto-initializer in a non-executable (for example, a test DLL loaded by a host process executable that doesn't initialize the bootstrapper), then you can explicitly enable an auto-initializer in your project with `<WindowsAppSdkBootstrapInitialize>true</WindowsAppSdkBootstrapInitialize>`.
+As of version 1.2 of the Windows App SDK (from the stable channel), auto-initializers apply only to projects that produce an executable (that is, the **OutputType** project property is set to *Exe* or *WinExe*). That's to prevent adding auto-initializers into class library DLLs and other non-executables by default. If you *do* need an auto-initializer in a non-executable (for example, a test DLL loaded by a host process executable that doesn't initialize the bootstrapper), then you can explicitly enable an auto-initializer in your project with `<WindowsAppSdkBootstrapInitialize>true</WindowsAppSdkBootstrapInitialize>`.
 
 ## Using the bootstrapper API