Normalize tools directory casing in task host handshake salt

The .NET task host handshake salt is a case-sensitive hash of a filesystem
path. The .NET Framework host passes the SDK directory ($(NetCoreSdkRoot))
as the tools directory while the child task host re-resolves it from its own
process location. On Windows these can differ only by drive-letter casing
(e.g. "D:\..." vs "d:\..."), which produced different salts and caused the
otherwise-valid handshake to fail with MSB4216 (seen with VS 18.6 launching
the .NET 11 SDK task host on hosted CI agents).

Normalize the tools directory casing on Windows before hashing so both sides
compute the same salt. The CLR2 MSBuildTaskHost (Windows-only) is normalized
unconditionally to match.

Fixes #14026

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: ViktorHofer

src/Build.UnitTests/BackEnd/AppHostSupport_Tests.cs

@@ -308,5 +308,43 @@ public void ResolveNetTaskHostLaunchPath_FallsBackToMSBuildDll_WhenAppHostMissin
             useAppHost.ShouldBeFalse();
             launchPath.ShouldBe(msbuildDllPath);
         }
+
+        /// <summary>
+        /// Regression test for MSB4216 caused by drive-letter casing differences (e.g. on
+        /// hosted CI agents the SDK-resolved path is "D:\..." while the child .NET task host
+        /// resolves its own location as "d:\...").
+        ///
+        /// On the .NET Framework → .NET task host path the parent passes the SDK directory
+        /// ($(NetCoreSdkRoot)) as toolsDirectory while the child re-resolves it from its own
+        /// process location. These come from independent sources, so on Windows they can differ
+        /// only in casing. Because Windows paths are case-insensitive, the case-sensitive salt
+        /// hash must normalize casing so both sides still produce the same handshake key.
+        /// </summary>
+        [WindowsOnlyFact]
+        public void Handshake_ToolsDirectoryCasingDoesNotAffectKey()
+        {
+            // Use explicit NET runtime and current architecture so the NET HandshakeOptions
+            // flag is set, which is required for passing toolsDirectory to the constructor.
+            var netTaskHostParams = new TaskHostParameters(
+                runtime: XMakeAttributes.MSBuildRuntimeValues.net,
+                architecture: XMakeAttributes.GetCurrentMSBuildArchitecture(),
+                dotnetHostPath: null,
+                msBuildAssemblyPath: null);
+
+            HandshakeOptions options = CommunicationsUtilities.GetHandshakeOptions(
+                taskHost: true,
+                taskHostParameters: netTaskHostParams,
+                nodeReuse: false);
+
+            const string upperCase = @"D:\a\_work\1\s\.dotnet\sdk\11.0.100-preview.5.26227.104";
+            const string lowerCase = @"d:\a\_work\1\s\.dotnet\sdk\11.0.100-preview.5.26227.104";
+
+            var upperHandshake = new Handshake(options, upperCase);
+            var lowerHandshake = new Handshake(options, lowerCase);
+
+            upperHandshake.GetKey().ShouldBe(lowerHandshake.GetKey(),
+                "On Windows, paths differing only by casing must produce identical handshake keys; " +
+                "otherwise a .NET Framework host and a .NET task host can fail to connect with MSB4216.");
+        }
     }
 }

src/Framework/BackEnd/Handshake.cs

@@ -80,7 +80,14 @@ 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}");
+        // The tools directory can be derived differently by the host and the child node (e.g. the host
+        // passes an explicit path while the child resolves it from its own process location). On Windows
+        // these may differ only in casing (notably the drive letter), and because the salt hash is
+        // case-sensitive that would cause an otherwise valid handshake to fail with MSB4216. Normalize
+        // the casing on Windows, where paths are case-insensitive, so both sides compute the same salt.
+        string normalizedToolsDirectory = NativeMethods.IsWindows ? toolsDirectory.ToUpperInvariant() : toolsDirectory;
+
+        int salt = CommunicationsUtilities.GetHashCode($"{handshakeSalt}{normalizedToolsDirectory}");
 
         CommunicationsUtilities.Trace($"Handshake salt is {handshakeSalt}");
         CommunicationsUtilities.Trace($"Tools directory root is {toolsDirectory}");

src/MSBuildTaskHost/CommunicationsUtilities.cs

@@ -209,7 +209,12 @@ public Handshake(HandshakeOptions nodeType)
 
         // Calculate salt from environment and tools directory
         string handshakeSalt = Environment.GetEnvironmentVariable("MSBUILDNODEHANDSHAKESALT") ?? "";
-        int salt = CommunicationsUtilities.GetHashCode($"{handshakeSalt}{toolsDirectory}");
+
+        // Normalize casing so the salt matches the host, which may derive the same directory with
+        // different casing (e.g. the drive letter). MSBuildTaskHost only runs on Windows, where paths
+        // are case-insensitive, so the case-sensitive salt hash must not depend on casing. See the
+        // matching logic in Microsoft.Build.Internal.Handshake.
+        int salt = CommunicationsUtilities.GetHashCode($"{handshakeSalt}{toolsDirectory.ToUpperInvariant()}");
 
         CommunicationsUtilities.Trace($"Handshake salt is {handshakeSalt}");
         CommunicationsUtilities.Trace($"Tools directory root is {toolsDirectory}");