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