MSB4216: .NET task host handshake fails due to case-sensitive drive-letter casing in salt (VS 18.6 + .NET 11 SDK)

[ViktorHofer]

Summary

The .NET task host fails to connect with MSB4216 when launched from a .NET Framework MSBuild host (e.g. VS) on hosted CI agents, because the handshake salt is a case-sensitive hash of a filesystem path and the two sides derive that path from independent sources whose drive-letter casing can differ.

InstallDotNetCore.targets(17,5): error MSB4216: Could not run the "InstallDotNetCore" task
because MSBuild could not create or connect to a task host with runtime "NET" and architecture "x86".
...
Handshake failed. Received -1569896665 from host for Salt but expected -930293759.
Probably the host is a different MSBuild build.

Observed in an internal build: VS MSBuild 18.6.3+84d3e95b4 (host) launching the .NET 11 SDK 11.0.100-preview.5.26227.104 task host.

Root cause

The handshake salt is computed as a case-sensitive hash:

salt = GetHashCode($"{MSBUILDNODEHANDSHAKESALT}{toolsDirectory}")

The two sides derive toolsDirectory differently:

Side	Source	Value in failing build
Host (NodeProviderOutOfProcTaskHost.ResolveAppHostOrFallback, #else branch)	$(NetCoreSdkRoot) via taskHostParameters.MSBuildAssemblyPath	D:\a\_work\1\s\.dotnet\sdk\11.0.100-preview.5.26227.104
Child (NodeEndpointOutOfProcTaskHost.GetHandshake -> new Handshake(options))	BuildEnvironmentHelper.MSBuildToolsDirectoryRoot (self-resolved)	d:\a\_work\1\s\.dotnet\sdk\11.0.100-preview.5.26227.104

Computing the hash of both strings confirms the mismatch exactly matches the on-the-wire values:

• D:\...26227.104 -> -1569896665 (host wrote)
• d:\...26227.104 -> -930293759 (child expected)

The "VS bin vs SDK" tools-directory lines that appear in the diagnostic logs are a red herring from an unrelated handshake context; the actual mismatch is purely drive-letter casing of the same SDK path.

Why it surfaced now / "how could it have ever worked"

This is a latent fragility rather than a single regressing commit. The host-side salt logic in VS 18.6.3 is identical to main. The cross-install path-in-salt was introduced incrementally:

• Resolve net task host params from the project properties #11543 (Aug 2025) - first derived the NET task host SDK path from a project property (RuntimeIdentifierGraphPath).
• Respect NetCoreSdkRoot property for TaskHostParameters #13176 (Feb 2026) - switched the source to $(NetCoreSdkRoot) (exposed by dotnet/sdk e0c4dda, new in .NET 11). Both old and new resolve to $(MSBuildThisFileDirectory), so this did not itself change the casing source.
• Add App Host Support for MSBuild #13175 (Mar 2026) - App Host support wired new Handshake(hostContext, toolsDirectory: msbuildAssemblyPath) for the Framework -> .NET cross-install case, feeding the externally-sourced path into the salt.

It "worked" only while the host-provided path and the child's self-resolved path happened to share casing. The trigger is the VS 18.6.x + .NET 11 SDK combination on hosted agents, where the SDK-resolver path is spelled D:\ but the child resolves d:\. It is environment/SDK-driven, not a product behavior change.

Fix

Normalize path casing on Windows before hashing, on both handshake implementations (the host and the .NET child both use src/Framework/BackEnd/Handshake.cs; the CLR2 host uses src/MSBuildTaskHost/CommunicationsUtilities.cs):

• Handshake.cs: toolsDirectory.ToUpperInvariant() when NativeMethods.IsWindows.
• MSBuildTaskHost/CommunicationsUtilities.cs: unconditional ToUpperInvariant() (Windows-only assembly).

Caveat

Because the NET task host handshake uses sentinel version 99.99.99.99, the host and child can legitimately be different MSBuild versions. Both sides must carry the normalization for the salts to agree, so the fix only fully takes effect once both a VS MSBuild build and the SDK MSBuild include it.

Affected files

• src/Framework/BackEnd/Handshake.cs
• src/MSBuildTaskHost/CommunicationsUtilities.cs
• src/Build/BackEnd/Components/Communications/NodeProviderOutOfProcTaskHost.cs (context)
• src/Build/Instance/TaskFactories/AssemblyTaskFactory.cs (context)

Why this is NOT the VS-path-vs-SDK-path (toolset directory) difference

It is tempting to read the diagnostic log line Tools directory root is c:\program files\...\visual studio\...\bin and conclude the host hashed its own VS tools directory while the child hashed the SDK directory. That is not what happens here:

• For the Framework -> .NET cross-install task host, the host deliberately does not use its own tools directory. ResolveAppHostOrFallback passes toolsDirectory: msbuildAssemblyPath (the resolved SDK path) exactly so the salt matches the SDK child. The VS ...\MSBuild\Current\Bin path is therefore never fed into this handshake's salt.

• The c:\program files\...\visual studio\...\bin "Tools directory root" line in the logs comes from a different, unrelated handshake context (e.g. a regular worker-node handshake), not the .NET task host handshake that produced this MSB4216.

• Decisive evidence: both salt values on the wire decode to the same SDK path, differing only by drive-letter casing:

  • D:\...\sdk\11.0.100-preview.5.26227.104 -> -1569896665 (host wrote)
  • d:\...\sdk\11.0.100-preview.5.26227.104 -> -930293759 (child expected)

  Neither value corresponds to any VS path. If the VS tools directory had actually entered the salt, the host value would hash c:\program files\...\visual studio\...\bin, which produces a completely different number (-617072364 / -199492840). It does not.

So the bug is purely the case-sensitive hashing of the SDK path (drive-letter casing), independent of the VS-vs-SDK install location difference, which is already handled correctly.

[ViktorHofer]

Mechanism: why the child resolves a lowercase d:

Follow-up investigation into why the two sides see different drive-letter casing for the same SDK path. The short answer: MSBuild never lowercases anything — the casing is captured independently on each side, from two different path-producing layers, and Windows does not force drive-letter casing to agree.

The child never lowercases itself

The child task host derives its tools directory from .NET runtime path APIs in BuildEnvironmentHelper.GetProcessFromRunningProcess (Environment.ProcessPath → entry-assembly Assembly.Location → AppContext.BaseDirectory). Empirically, these behave in two different ways depending on how the task host is launched:

1. dotnet MSBuild.dll fallback (what x86 uses, since no x86 apphost ships): the runtime echoes the command-line casing verbatim. Launch with d:\... → child resolves d:\...; launch with D:\... → D:\.... No normalization.
2. apphost MSBuild.exe: Environment.ProcessPath (GetModuleFileNameW) returns the canonical on-disk/volume casing, ignoring how it was invoked.

The host salt comes from a different producer

The host hashes the $(NetCoreSdkRoot) MSBuild property string (AssemblyTaskFactory.AddNetHostParamsIfNeeded → msbuildAssemblyPath). That property is produced by the SDK resolver / $(MSBuildThisFileDirectory) — an entirely different layer than the runtime path API the child reads. (On main, the host's launch path and salt toolsDirectory both come from that same msbuildAssemblyPath, so within a single host they are identical; the divergence is strictly host-string vs child-resolved-string.)

Conclusion

The drive-letter casing on each side is captured independently:

• host: from the SDK-resolver-derived $(NetCoreSdkRoot) string (uppercase D: on the agent, ultimately seeded from an env-derived input such as Build.SourcesDirectory/DOTNET_ROOT);
• child: from a runtime path API, reflecting the true volume canonical casing (apphost) or the launch arg (dotnet fallback) — lowercase d: on that CI volume.

Windows never forces drive-letter casing to agree across these producers, and the salt hash is case-sensitive, so they diverged. The lowercase d: is a property of that specific agent's volume, not of MSBuild's code — it could not be reproduced on volumes that canonicalize to uppercase. This is exactly why the fix must normalize (uppercase) the salt input on both sides rather than try to predict the casing.

[ViktorHofer]

Where the uppercase D: originates

Tracing the source of the divergent casing one step further: the uppercase D: in $(NetCoreSdkRoot) ultimately comes from the Azure DevOps agent path convention, propagated through Arcade into the SDK-locating environment, while the lowercase d: the child reports is the volume's true on-disk casing from GetModuleFileNameW.

Why $(NetCoreSdkRoot) is uppercase D:

$(NetCoreSdkRoot) = $(MSBuildThisFileDirectory) of Microsoft.NETCoreSdk.BundledVersions.props. That value is built entirely by string path manipulation (Path.GetFullPath / GetDirectoryName / Combine), and on Windows those managed Path.* APIs preserve the drive-letter casing of their input — they never query the filesystem to canonicalize it. The chain:

1. ADO seeds the casing. Predefined variables (Agent.WorkFolder, Build.SourcesDirectory) are conventionally spelled with an uppercase drive — D:\a\_work\1\s. That is a string the agent emits; it does not reflect the NTFS volume's canonical casing.
2. Arcade derives the SDK path from it. eng\common\tools.ps1 (InitializeDotNetCli) computes the local SDK dir as ~Join-Path $RepoRoot ".dotnet" (where $RepoRoot traces back to that uppercase sources dir) and exports the SDK-locating env (DOTNET_ROOT, DOTNET_INSTALL_DIR, prepends .dotnet to PATH, resolver dir) — all carrying D:\a\_work\1\s\.dotnet\... verbatim.
3. The MSBuild SDK resolver reads those env vars. Under the desktop (VS) MSBuild host, Microsoft.DotNet.MSBuildSdkResolver locates the SDK from that environment (DOTNET_MSBUILD_SDK_RESOLVER_CLI_DIR / DOTNET_HOST_PATH / DOTNET_ROOT / PATH) and returns the SDK directory string — still uppercase D:.
4. That becomes the property. Importing BundledVersions.props from that path makes $(MSBuildThisFileDirectory) (→ $(NetCoreSdkRoot)) inherit the uppercase D:.

Why the child sees lowercase d:

The child apphost gets its path from GetModuleFileNameW (via Environment.ProcessPath), which reads the actual loaded image's on-disk path and reports the volume's canonical casing — lowercase d: on that agent — regardless of how it was invoked.

Net

• $(NetCoreSdkRoot) → uppercase D: because it is a string-propagated path (preserves the ADO/Arcade caller casing, never canonicalized).
• apphost path → lowercase d: because it is a filesystem-resolved path (reflects the disk's casing).

Nothing forces these two producers to agree on drive-letter casing, which is exactly why the salt must normalize casing on both sides rather than rely on the paths matching.

(The exact env-var carrier in this specific run wasn't pulled from the build artifacts; this is the standard Arcade-on-ADO chain inferred from the D:\a\_work\1\s\.dotnet\... paths in the logs. The SDK resolver trace in the binlog / the run's DOTNET_ROOT/DOTNET_HOST_PATH would confirm the precise variable.)

[ViktorHofer]

Short-term workaround (Arcade)

A draft PR with a temporary, host-side-only mitigation is up in Arcade: dotnet/arcade#17002

It adds an inline task + InitialTargets target that rewrites only the drive letter of $(NetCoreSdkRoot) to the canonical casing the child task host will resolve, so the .NET Framework MSBuild host computes the same handshake salt the child does.

Key points:

• Matches Environment.ProcessPath exactly: it calls the same GetModuleFileNameW API (via LoadLibraryEx(..., LOAD_LIBRARY_AS_DATAFILE) on an image under the SDK root) that backs the child's Environment.ProcessPath, in-process, without launching the SDK. Verified that this ignores the passed-in drive casing and returns the volume's canonical casing.
• Host-side only: the child computes its salt from its own Environment.ProcessPath and never reads $(NetCoreSdkRoot), so the fix only needs to run in the build driven by the host MSBuild — no SDK/child-side change required.
• Gated on MSBuildRuntimeType == 'Full': only the .NET Framework host feeds $(NetCoreSdkRoot) into the salt (the #if NETFRAMEWORK branch in NodeProviderOutOfProcTaskHost); under dotnet build both sides default to BuildEnvironmentHelper and casing is already consistent, so it's a no-op there.
• Windows-only, idempotent, and a safe no-op on any failure. Property mutation in InitialTargets is honored because the salt reads the live, build-mutable property bag (ProjectInstance.GetProperty → _properties[name]), which reflects target-time writes.

This is a stopgap until both the VS MSBuild host and the .NET SDK task host carry the bilateral salt-casing normalization tracked by this issue.

[ViktorHofer]

The real (permanent) fix is now up as a PR: #14027

It normalizes the tools-directory casing (uppercase on Windows) before computing the handshake salt, on both sides (Handshake.cs for the .NET Framework host and the .NET task host child, plus CommunicationsUtilities.cs for the CLR2 MSBuildTaskHost), with a regression test. Unix paths are left untouched.

The Arcade PR (dotnet/arcade#17002) remains as the short-term, host-side-only mitigation until updated MSBuild flows into both the VS host and the .NET SDK.