.NET MU docs

docs/core/install/includes/microsoft-update.md

@@ -0,0 +1,41 @@
+---
+author: joeloff
+ms.author: joeloff
+ms.date: 11/12/2024
+ms.topic: include
+---
+
+The .NET installer executables are independent products that can be serviced using Microsoft Update (MU) on Windows. This is different from Windows Update (WU) that is used to service operating system components like .NET Framework.
+
+Both security and non-security fixes for supported versions of .NET are provided through MU using multiple distribution channels. Automatic Updates (AU) is relevant to end-users and consumers while Window Server Update Services (WSUS) and Windows Update Catalog are relevant to IT administrators.
+
+The .NET installer executables support side-by-side (SxS) installations across major/minor releases for different architectures and components (runtime, SDK, etc.). For example, users can install both the 6.0.15 (x64) and 6.0.17 (x86) runtime. When MU triggers, it will offer the latest installer for both installations.
+
+#### Blocking Updates
+
+While most users prefer to be kept up to date, it is possible to block .NET updates using the registry keys in the table below.  
+
+| .NET Version | Registry Key | Name | Type | Value |
+| -------------- | :--------- | :---------- | :---------- | :---------- |
+| All | HKLM\SOFTWARE\Microsoft\\.NET | BlockMU | REG_DWORD | 0x00000001 |
+| .NET 9 | HKLM\SOFTWARE\Microsoft\\.NET\9.0 | BlockMU | REG_DWORD | 0x00000001 |
+| .NET 8 | HKLM\SOFTWARE\Microsoft\\.NET\8.0 | BlockMU | REG_DWORD | 0x00000001 |
+| .NET 7 | HKLM\SOFTWARE\Microsoft\\.NET\7.0 | BlockMU | REG_DWORD | 0x00000001 |
+| .NET 6 | HKLM\SOFTWARE\Microsoft\\.NET\6.0 | BlockMU | REG_DWORD | 0x00000001 |
+| .NET 5 | HKLM\SOFTWARE\Microsoft\\.NET\5.0 | BlockMU | REG_DWORD | 0x00000001 |
+| .NET Core 3.1 | HKLM\SOFTWARE\Microsoft\\.NET\3.1 | BlockMU | REG_DWORD | 0x00000001 |
+| .NET Core 2.1 | HKLM\SOFTWARE\Microsoft\\.NET\2.1 | BlockMU | REG_DWORD | 0x00000001 |
+
+#### Automatic Updates for Server OS
+
+Updates for server operating systems are supported by WSUS and Microsoft Update Catalog, but not AU. Server operating systems can opt in to receive updates through AU using the following registry keys.
+
+| .NET Version | Registry Key | Name | Type | Value |
+| -------------- | :--------- | :---------- | :---------- | :---------- |
+| All | HKLM\SOFTWARE\Microsoft\\.NET | AllowAUOnServerOS | REG_DWORD | 0x00000001 |
+| .NET 9 | HKLM\SOFTWARE\Microsoft\\.NET\9.0 | AllowAUOnServerOS | REG_DWORD | 0x00000001 |
+| .NET 8 | HKLM\SOFTWARE\Microsoft\\.NET\8.0 | AllowAUOnServerOS | REG_DWORD | 0x00000001 |
+| .NET 7 | HKLM\SOFTWARE\Microsoft\\.NET\7.0 | AllowAUOnServerOS | REG_DWORD | 0x00000001 |
+| .NET 6 | HKLM\SOFTWARE\Microsoft\\.NET\6.0 | AllowAUOnServerOS | REG_DWORD | 0x00000001 |
+| .NET 5 | HKLM\SOFTWARE\Microsoft\\.NET\5.0 | AllowAUOnServerOS | REG_DWORD | 0x00000001 |
+| .NET Core 3.1 | HKLM\SOFTWARE\Microsoft\\.NET\3.1 | AllowAUOnServerOS | REG_DWORD | 0x00000001 |

docs/core/install/windows.md

@@ -222,6 +222,30 @@ dotnet-sdk-9.0.100-win-x64.exe /install /quiet /norestart
 > [!TIP]
 > The installer returns an exit code of **0** for success and an exit code of **3010** to indicate that a restart is required. Any other value is most likely an error code.
 
+### Microsoft Update
+
+[!INCLUDE [microsoft-update](includes/microsoft-update.md)]
+
+### Choose when previous versions are removed
+
+The installer executables always install new content before removing the previous installation. Running applications may be interrupted or crash when older runtimes are. To minimize the impact of updating .NET, users can specify when a previous .NET installation should be removed using a registry key.
+
+| .NET Version | Registry Key | Name | Type | Value |
+| -------------- | :--------- | :---------- | :---------- | :---------- |
+| All | HKLM\SOFTWARE\Microsoft\\.NET | RemovePreviousVersion | REG_SZ | _always_, _never_, or _nextSession_ |
+| .NET 9 | HKLM\SOFTWARE\Microsoft\\.NET\9.0 | RemovePreviousVersion | REG_SZ | _always_, _never_, or _nextSession_ |
+| .NET 8 | HKLM\SOFTWARE\Microsoft\\.NET\8.0 | RemovePreviousVersion | REG_SZ | _always_, _never_, or _nextSession_ |
+
+- _never_ retains previous installations and requires manual intervention to remove previous .NET installations.
+- _always_ removes previous installations after the new version is installed. This is the default behavior in .NET.
+- _nextSession_ defers the removal until the next logon session from members in the Administrators group.
+- Values are case-insensitive and invalid values default to _always_.
+
+When the removal is deferred, the installer writes a command to the [RunOnce](/windows/win32/setupapi/run-and-runonce-registry-keys) registry key to uninstall the previous version. The command only executes if users in the Administrators group logs on to the machine.
+
+> [!NOTE]
+> This feature is only available starting with .NET 8 (8.0.11), 9 and later versions of .NET. It only applies to the standalone installer executables and will impact distributions like WinGet that use them.
+
 ## Install with Windows Package Manager (WinGet)
 
 You can install and manage .NET through the Windows Package Manager service, using the `winget.exe` tool. For more information about how to install and use **WinGet**, see [Use the winget tool to install and manage applications](/windows/package-manager/winget/).