Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions documentation/wiki/ChangeWaves.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
163 changes: 163 additions & 0 deletions src/Build.UnitTests/BackEnd/Handshake_Tests.cs
Original file line number Diff line number Diff line change
@@ -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
{
/// <summary>
/// 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.
/// </summary>
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;

/// <summary>
/// The change wave is cached statically, so drop what these tests cached once the environment
/// variable has been restored.
/// </summary>
public void Dispose() => ChangeWaves.ResetStateForTests();

/// <summary>
/// Change waves are cached statically, so the cache has to be dropped whenever the environment
/// variable driving it changes.
/// </summary>
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);
}

/// <summary>
/// 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.
/// </summary>
[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);
}

/// <summary>
/// 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.
/// </summary>
[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);
}

/// <summary>
/// A task host connection is the one place where the two ends can be different MSBuild versions, and
/// the resolved wave is version-relative: <see cref="ChangeWaves.DisabledWave"/> 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.
/// </summary>
[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);
}

/// <summary>
/// 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.
/// </summary>
[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);
}
}
}
43 changes: 41 additions & 2 deletions src/Framework/BackEnd/Handshake.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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)
Expand All @@ -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);

/// <summary>
/// The part of the handshake salt that represents the change wave this process resolved, so that nodes
/// which disagree about <c>MSBUILDDISABLEFEATURESFROMVERSION</c> 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.
/// <para>
/// 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:
/// <see cref="ChangeWaves.DisabledWave"/> clamps and rounds the environment variable into the binary's own
/// <c>AllWaves</c> 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.
/// </para>
/// </summary>
private string GetChangeWaveSalt()
{
if (IsTaskHost)
{
return string.Empty;
}

Version disabledWave = ChangeWaves.DisabledWave;

return disabledWave == ChangeWaves.EnableAllFeatures ? string.Empty : disabledWave.ToString();
}

/// <summary>
/// Determines whether <paramref name="receivedSalt"/> 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
Expand Down