diff --git a/documentation/wiki/ChangeWaves.md b/documentation/wiki/ChangeWaves.md
index 7ae79c7d648..3115536c667 100644
--- a/documentation/wiki/ChangeWaves.md
+++ b/documentation/wiki/ChangeWaves.md
@@ -10,6 +10,12 @@ The opt-out comes in the form of setting the environment variable `MSBUILDDISABL
The opt-out should be just a *temporary* workaround for a problem - as the feature will anyways become permanent eventually. For this reason - **please make sure to create or upvote a bug describing the issue making you opt-out**.
+### Change waves and reused processes
+
+`MSBUILDDISABLEFEATURESFROMVERSION` is read once per process, so a process that outlives a single build - a reused worker node or an MSBuild Server node - keeps the change wave it started with. To make sure 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 resolved a different change wave refuses the connection and MSBuild starts a fresh one instead. Changing `MSBUILDDISABLEFEATURESFROMVERSION` between builds therefore starts new nodes rather than reusing the existing ones. Values that resolve to the same change wave (for example an unset variable and a value in an invalid format) still allow node reuse.
+
+Task hosts are deliberately left out of this. A task host connection can span two different MSBuild versions - most notably the .NET task host, where a .NET Framework parent such as Visual Studio talks to a child taken from the installed .NET SDK - and the resolved change wave is version-relative, because the environment variable is clamped and rounded into the wave list of whichever binary reads it. Two versions can therefore resolve the same variable to different waves. Unlike a worker node, a task host that fails the handshake cannot be replaced by a compatible one, since the parent can only relaunch the very same executable, so the build would fail with MSB4216. A task host consequently keeps the change wave it started with even across builds.
+
## When do they become permanent?
A wave of features is eligible to "rotate out" (i.e. become standard functionality) six months after its release. For example, wave 16.8 stayed opt-out through wave 16.10, becoming standard functionality when wave 17.0 is introduced.
diff --git a/src/Build.UnitTests/BackEnd/Handshake_Tests.cs b/src/Build.UnitTests/BackEnd/Handshake_Tests.cs
new file mode 100644
index 00000000000..f1c9457df8d
--- /dev/null
+++ b/src/Build.UnitTests/BackEnd/Handshake_Tests.cs
@@ -0,0 +1,163 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using Microsoft.Build.Framework;
+using Microsoft.Build.Internal;
+using Microsoft.Build.Shared;
+using Microsoft.Build.UnitTests;
+using Shouldly;
+using Xunit;
+
+namespace Microsoft.Build.Engine.UnitTests.BackEnd
+{
+ ///
+ /// Tests that the change wave a process resolved participates in the handshake. A node caches its
+ /// change wave for its whole lifetime, so a node reused by a later build would otherwise keep
+ /// applying the change wave of the build that started it.
+ ///
+ public sealed class Handshake_Tests : IDisposable
+ {
+ private const string DisableFeaturesFromVersion = "MSBUILDDISABLEFEATURESFROMVERSION";
+
+ private static readonly HandshakeOptions s_workerNodeOptions = CommunicationsUtilities.GetHandshakeOptions(
+ taskHost: false,
+ taskHostParameters: TaskHostParameters.Empty);
+
+ private readonly ITestOutputHelper _output;
+
+ public Handshake_Tests(ITestOutputHelper output) => _output = output;
+
+ ///
+ /// The change wave is cached statically, so drop what these tests cached once the environment
+ /// variable has been restored.
+ ///
+ public void Dispose() => ChangeWaves.ResetStateForTests();
+
+ ///
+ /// Change waves are cached statically, so the cache has to be dropped whenever the environment
+ /// variable driving it changes.
+ ///
+ private static void SetChangeWave(string? wave, TestEnvironment env)
+ {
+ ChangeWaves.ResetStateForTests();
+ env.SetEnvironmentVariable(DisableFeaturesFromVersion, wave);
+ }
+
+ private static string GetKeyForChangeWave(string? wave, TestEnvironment env, HandshakeOptions options)
+ {
+ SetChangeWave(wave, env);
+
+ return new Handshake(options).GetKey();
+ }
+
+ [Fact]
+ public void DifferentChangeWavesProduceDifferentHandshakes()
+ {
+ using TestEnvironment env = TestEnvironment.Create(_output);
+
+ string firstKey = GetKeyForChangeWave(ChangeWaves.LowestWave.ToString(), env, s_workerNodeOptions);
+ string secondKey = GetKeyForChangeWave(ChangeWaves.HighestWave.ToString(), env, s_workerNodeOptions);
+
+ secondKey.ShouldNotBe(firstKey);
+ }
+
+ [Fact]
+ public void SameChangeWaveProducesTheSameHandshake()
+ {
+ using TestEnvironment env = TestEnvironment.Create(_output);
+
+ string firstKey = GetKeyForChangeWave(ChangeWaves.LowestWave.ToString(), env, s_workerNodeOptions);
+ string secondKey = GetKeyForChangeWave(ChangeWaves.LowestWave.ToString(), env, s_workerNodeOptions);
+
+ secondKey.ShouldBe(firstKey);
+ }
+
+ ///
+ /// Values that resolve to the same change wave have to keep producing the same handshake, otherwise
+ /// nodes that behave identically would needlessly refuse to talk to each other.
+ ///
+ [Theory]
+ [InlineData("")]
+ [InlineData("999.999")]
+ [InlineData("not a version")]
+ public void EquivalentChangeWaveValuesProduceTheSameHandshake(string wave)
+ {
+ using TestEnvironment env = TestEnvironment.Create(_output);
+
+ string unsetKey = GetKeyForChangeWave(null, env, s_workerNodeOptions);
+ string equivalentKey = GetKeyForChangeWave(wave, env, s_workerNodeOptions);
+
+ equivalentKey.ShouldBe(unsetKey);
+ }
+
+ ///
+ /// MSBuild Server clients find their server by a pipe name derived from the handshake, so a server
+ /// that resolved a different change wave must not be reused.
+ ///
+ [Fact]
+ public void DifferentChangeWavesProduceDifferentServerNodeHandshakes()
+ {
+ using TestEnvironment env = TestEnvironment.Create(_output);
+
+ HandshakeOptions options = CommunicationsUtilities.GetHandshakeOptions(
+ taskHost: false,
+ taskHostParameters: TaskHostParameters.Empty,
+ architectureFlagToSet: XMakeAttributes.GetCurrentMSBuildArchitecture());
+
+ SetChangeWave(ChangeWaves.LowestWave.ToString(), env);
+ string firstHash = new ServerNodeHandshake(options).ComputeHash();
+
+ SetChangeWave(ChangeWaves.HighestWave.ToString(), env);
+ string secondHash = new ServerNodeHandshake(options).ComputeHash();
+
+ secondHash.ShouldNotBe(firstHash);
+ }
+
+ ///
+ /// A task host connection is the one place where the two ends can be different MSBuild versions, and
+ /// the resolved wave is version-relative: clamps and rounds the
+ /// environment variable into that binary's own wave list. The CLR2 task host additionally computes its
+ /// handshake from a separate legacy copy of this code that knows nothing about change waves. Unlike a
+ /// worker node, a task host mismatch cannot be recovered from by starting a different host, so no task
+ /// host may take the change wave into account.
+ ///
+ [Theory]
+ [InlineData((int)(HandshakeOptions.TaskHost | HandshakeOptions.CLR2))]
+ [InlineData((int)(HandshakeOptions.TaskHost | HandshakeOptions.NET))]
+ [InlineData((int)(HandshakeOptions.TaskHost | HandshakeOptions.NET | HandshakeOptions.X64))]
+ [InlineData((int)(HandshakeOptions.TaskHost | HandshakeOptions.NET | HandshakeOptions.SidecarTaskHost))]
+ [InlineData((int)HandshakeOptions.TaskHost)]
+ public void TaskHostHandshakeIgnoresChangeWave(int taskHostOptions)
+ {
+ using TestEnvironment env = TestEnvironment.Create(_output);
+
+ var options = (HandshakeOptions)taskHostOptions;
+
+ string firstKey = GetKeyForChangeWave(ChangeWaves.LowestWave.ToString(), env, options);
+ string secondKey = GetKeyForChangeWave(ChangeWaves.HighestWave.ToString(), env, options);
+
+ secondKey.ShouldBe(firstKey);
+ }
+
+ ///
+ /// The .NET task host is the connection at risk: a .NET Framework parent (e.g. Visual Studio) talks to
+ /// a child taken from the installed .NET SDK, which resolves the same environment variable against a
+ /// different wave list. Its handshake has to stay identical to what a version without change wave
+ /// salting computes, otherwise the build fails with MSB4216 and the parent can only relaunch the same
+ /// SDK binary rather than start a compatible host.
+ ///
+ [Fact]
+ public void NetTaskHostHandshakeIsUnaffectedByChangeWave()
+ {
+ using TestEnvironment env = TestEnvironment.Create(_output);
+
+ HandshakeOptions options = HandshakeOptions.TaskHost | HandshakeOptions.NET;
+
+ string unsetKey = GetKeyForChangeWave(null, env, options);
+ string waveSetKey = GetKeyForChangeWave(ChangeWaves.LowestWave.ToString(), env, options);
+
+ waveSetKey.ShouldBe(unsetKey);
+ }
+ }
+}
diff --git a/src/Framework/BackEnd/Handshake.cs b/src/Framework/BackEnd/Handshake.cs
index a8dbf87984f..22b5c167d80 100644
--- a/src/Framework/BackEnd/Handshake.cs
+++ b/src/Framework/BackEnd/Handshake.cs
@@ -92,7 +92,13 @@ protected Handshake(HandshakeOptions nodeType, bool includeSessionId, string? to
// Calculate salt from environment and tools directory
string handshakeSalt = Environment.GetEnvironmentVariable("MSBUILDNODEHANDSHAKESALT") ?? "";
- int salt = CommunicationsUtilities.GetHashCode($"{handshakeSalt}{toolsDirectory}");
+ // A node resolves its change wave once and keeps it for the rest of its lifetime, so a node reused
+ // by a later build would silently keep applying the change wave of the build that started it. Fold
+ // the change wave into the salt so that a node which resolved a different change wave rejects the
+ // connection and the parent starts a fresh node instead. Task hosts are excluded, see GetChangeWaveSalt.
+ string changeWaveSalt = GetChangeWaveSalt();
+
+ int salt = CommunicationsUtilities.GetHashCode($"{handshakeSalt}{toolsDirectory}{changeWaveSalt}");
// The .NET task host parent (.NET Framework MSBuild, e.g. Visual Studio) and child
// (.NET SDK MSBuild) compute this salt independently from different sources, and on Windows
@@ -102,10 +108,11 @@ protected Handshake(HandshakeOptions nodeType, bool includeSessionId, string? to
// the parent's spelling (see IsNetTaskHostSaltMatch). Only the child consults this value.
if (IsNetTaskHost && TryGetDriveLetterCaseVariant(toolsDirectory, out string? alternateToolsDirectory))
{
- _netTaskHostSaltDriveCaseVariant = CommunicationsUtilities.GetHashCode($"{handshakeSalt}{alternateToolsDirectory}");
+ _netTaskHostSaltDriveCaseVariant = CommunicationsUtilities.GetHashCode($"{handshakeSalt}{alternateToolsDirectory}{changeWaveSalt}");
}
CommunicationsUtilities.Trace($"Handshake salt is {handshakeSalt}");
+ CommunicationsUtilities.Trace($"Change wave salt is {changeWaveSalt}");
CommunicationsUtilities.Trace($"Tools directory root is {toolsDirectory}");
// Get session ID if needed (expensive call)
@@ -128,6 +135,38 @@ protected Handshake(HandshakeOptions nodeType, bool includeSessionId, string? to
private bool IsNetTaskHost
=> IsHandshakeOptionEnabled(HandshakeOptions, HandshakeOptions.NET | HandshakeOptions.TaskHost);
+ private bool IsTaskHost
+ => IsHandshakeOptionEnabled(HandshakeOptions, HandshakeOptions.TaskHost);
+
+ ///
+ /// The part of the handshake salt that represents the change wave this process resolved, so that nodes
+ /// which disagree about MSBUILDDISABLEFEATURESFROMVERSION never talk to each other. The resolved
+ /// wave is used rather than the raw environment variable so that values which resolve to the same wave
+ /// (for example an unset variable and one in an invalid format) still allow node reuse.
+ ///
+ /// Returns an empty string for every task host, because a task host connection is the one place where the
+ /// two sides can be different MSBuild versions and the resolved wave is a version-relative value:
+ /// clamps and rounds the environment variable into the binary's own
+ /// AllWaves list, which differs between versions. The CLR2 task host computes its handshake from a
+ /// separate legacy copy of this code in MSBuildTaskHost.exe that knows nothing about change waves, and the
+ /// .NET task host pairs a .NET Framework parent (e.g. Visual Studio) with a child from the installed .NET
+ /// SDK, so the same variable can legitimately resolve to different waves on either side. Unlike a worker
+ /// node or an MSBuild Server node, a task host mismatch is not self-healing: the parent can only relaunch
+ /// the very same SDK binary, so the build fails with MSB4216 instead of starting a compatible host.
+ ///
+ ///
+ private string GetChangeWaveSalt()
+ {
+ if (IsTaskHost)
+ {
+ return string.Empty;
+ }
+
+ Version disabledWave = ChangeWaves.DisabledWave;
+
+ return disabledWave == ChangeWaves.EnableAllFeatures ? string.Empty : disabledWave.ToString();
+ }
+
///
/// Determines whether matches this node's salt computed for the
/// alternate drive-letter casing of its tools directory. Used only by the .NET task host child to