From 4a56d8089dbc06f163fc54bcb3d8a043757b0ca3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Provazn=C3=ADk?= Date: Tue, 28 Jul 2026 16:02:50 +0200 Subject: [PATCH 1/4] Update change-waves.md with process disposal instructions Added instructions to dispose stale MSBuild processes after modifying a ChangeWave. --- docs/msbuild/change-waves.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/msbuild/change-waves.md b/docs/msbuild/change-waves.md index fbb240679bd..f3770a9e06f 100644 --- a/docs/msbuild/change-waves.md +++ b/docs/msbuild/change-waves.md @@ -19,7 +19,7 @@ When you upgrade to a new version of MSBuild, changes that are potentially break ## Opt out of change wave features -To disable the features in a change wave, set the environment variable `MSBuildDisableFeaturesFromVersion` to the change wave (or MSBuild version) that contains the feature you want **disabled**. This is the version of MSBuild that the features were developed for. See the mapping of change waves to features below. +To disable the features in a change wave, set the environment variable `MSBuildDisableFeaturesFromVersion` to the change wave (or MSBuild version) that contains the feature you want **disabled**. This is the version of MSBuild that the features were developed for. See the mapping of change waves to features below. After modifying a ChangeWave make sure to dispose stale persistent MSBuild processes with `dotnet build-server shutdown` or killing `MSBuild.exe`. ### MSBuildDisableFeaturesFromVersion Values From 7b229cf966ca299943769c8733d8f43529b9da32 Mon Sep 17 00:00:00 2001 From: chcomley <35748196+chcomley@users.noreply.github.com> Date: Thu, 13 Aug 2026 12:15:36 -0700 Subject: [PATCH 2/4] Update change waves documentation and add new section Updated the date for the MSBuild change waves documentation and added a section on change waves and reused processes. --- docs/msbuild/change-waves.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/msbuild/change-waves.md b/docs/msbuild/change-waves.md index f3770a9e06f..f1c9d12b91a 100644 --- a/docs/msbuild/change-waves.md +++ b/docs/msbuild/change-waves.md @@ -1,7 +1,7 @@ --- title: Change waves description: Learn how to enable or disable features in MSBuild that are potentially disruptive. -ms.date: 5/22/2026 +ms.date: 08/13/2026 ms.topic: whats-new helpviewer_keywords: - Change waves [MSBuild] @@ -19,7 +19,13 @@ When you upgrade to a new version of MSBuild, changes that are potentially break ## Opt out of change wave features -To disable the features in a change wave, set the environment variable `MSBuildDisableFeaturesFromVersion` to the change wave (or MSBuild version) that contains the feature you want **disabled**. This is the version of MSBuild that the features were developed for. See the mapping of change waves to features below. After modifying a ChangeWave make sure to dispose stale persistent MSBuild processes with `dotnet build-server shutdown` or killing `MSBuild.exe`. +To disable the features in a change wave, set the environment variable `MSBuildDisableFeaturesFromVersion` to the change wave (or MSBuild version) that contains the feature you want **disabled**. This is the version of MSBuild that the features were developed for. See the mapping of change waves to the following features. + +### Change waves and reused processes + +`MSBuildDisableFeaturesFromVersion` is read once per process, so a process that outlives a single build, such as a reused worker node or an MSBuild Server node, keeps the change wave it started with. To ensure that every process taking part in a build agrees on the change wave, the resolved change wave is part of the node handshake. A node that resolves a different change wave refuses the connection, and MSBuild starts a new node instead. Changing `MSBuildDisableFeaturesFromVersion` between builds therefore starts new nodes rather than reusing the existing ones. Values that resolve to the same change wave, such as an unset variable and a value in an invalid format, still allow node reuse. + +Task hosts don't use this handshake. A task host connection can involve two different MSBuild versions. For example, a .NET Framework parent process, such as Visual Studio, can communicate with a child process from the installed .NET SDK. The resolved change wave is version-relative because the environment variable is clamped and rounded to the wave list of the binary that reads it. Two versions can therefore resolve the same variable to different waves. Unlike a worker node, a task host can't be replaced with a compatible node when the resolved change wave differs, because the parent can only restart the same executable. In that case, the build would fail with MSB4216. A task host consequently keeps the change wave it started with across builds. ### MSBuildDisableFeaturesFromVersion Values From a0d26a9105a94692c408b26325fd717d38d309e2 Mon Sep 17 00:00:00 2001 From: chcomley <35748196+chcomley@users.noreply.github.com> Date: Thu, 13 Aug 2026 12:26:18 -0700 Subject: [PATCH 3/4] Remove change waves and reused processes section Removed section about change waves and reused processes from the documentation, as this is confirmed unshipped behavior. --- docs/msbuild/change-waves.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/msbuild/change-waves.md b/docs/msbuild/change-waves.md index f1c9d12b91a..71307d19ad4 100644 --- a/docs/msbuild/change-waves.md +++ b/docs/msbuild/change-waves.md @@ -21,12 +21,6 @@ When you upgrade to a new version of MSBuild, changes that are potentially break To disable the features in a change wave, set the environment variable `MSBuildDisableFeaturesFromVersion` to the change wave (or MSBuild version) that contains the feature you want **disabled**. This is the version of MSBuild that the features were developed for. See the mapping of change waves to the following features. -### Change waves and reused processes - -`MSBuildDisableFeaturesFromVersion` is read once per process, so a process that outlives a single build, such as a reused worker node or an MSBuild Server node, keeps the change wave it started with. To ensure that every process taking part in a build agrees on the change wave, the resolved change wave is part of the node handshake. A node that resolves a different change wave refuses the connection, and MSBuild starts a new node instead. Changing `MSBuildDisableFeaturesFromVersion` between builds therefore starts new nodes rather than reusing the existing ones. Values that resolve to the same change wave, such as an unset variable and a value in an invalid format, still allow node reuse. - -Task hosts don't use this handshake. A task host connection can involve two different MSBuild versions. For example, a .NET Framework parent process, such as Visual Studio, can communicate with a child process from the installed .NET SDK. The resolved change wave is version-relative because the environment variable is clamped and rounded to the wave list of the binary that reads it. Two versions can therefore resolve the same variable to different waves. Unlike a worker node, a task host can't be replaced with a compatible node when the resolved change wave differs, because the parent can only restart the same executable. In that case, the build would fail with MSB4216. A task host consequently keeps the change wave it started with across builds. - ### MSBuildDisableFeaturesFromVersion Values You will receive a warning and/or default to a specific wave if you don't set `MSBuildDisableFeaturesFromVersion` to a valid change wave. The following table shows the possible settings: From 49373b0455063e6a93994e4d9895eafbb524036b Mon Sep 17 00:00:00 2001 From: chcomley <35748196+chcomley@users.noreply.github.com> Date: Thu, 13 Aug 2026 12:36:26 -0700 Subject: [PATCH 4/4] Update change-waves.md with MSBuild process info Added information about persistent MSBuild processes and the need to shut them down after changing the environment variable. --- docs/msbuild/change-waves.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/msbuild/change-waves.md b/docs/msbuild/change-waves.md index 71307d19ad4..f71dfb7a4a1 100644 --- a/docs/msbuild/change-waves.md +++ b/docs/msbuild/change-waves.md @@ -21,6 +21,8 @@ When you upgrade to a new version of MSBuild, changes that are potentially break To disable the features in a change wave, set the environment variable `MSBuildDisableFeaturesFromVersion` to the change wave (or MSBuild version) that contains the feature you want **disabled**. This is the version of MSBuild that the features were developed for. See the mapping of change waves to the following features. +Persistent MSBuild processes keep the value of `MSBuildDisableFeaturesFromVersion` that they started with. After you change the environment variable, shut down persistent build processes before you run another build. For builds run with the .NET CLI, use `dotnet build-server shutdown`. For builds run with Visual Studio or `MSBuild.exe`, close Visual Studio and end any remaining `MSBuild.exe` processes. Otherwise, reused processes might continue to use the previous value, and projects built in parallel might use different values. + ### MSBuildDisableFeaturesFromVersion Values You will receive a warning and/or default to a specific wave if you don't set `MSBuildDisableFeaturesFromVersion` to a valid change wave. The following table shows the possible settings: