Add clear error message (MSB4233) for .NET runtime tasks on MSBuild 17.14

[Copilot]

Summary

This PR adds a clear error message (MSB4233) when users try to use tasks with Runtime="NET" on MSBuild 17.14 (.NET Framework), which doesn't support .NET runtime tasks.

Changes

• Added check in NodeProviderOutOfProcTaskHost.AcquireAndSetUpHost() to detect HandshakeOptions.NET flag
• Throws InvalidProjectFileException with clear error message (MSB4233) before attempting to launch task host
• Error message includes task name, assembly location, and guidance to use "dotnet build" or Visual Studio 2026+
• Wrapped in #if NETFRAMEWORK since .NET Core/5+ builds support .NET runtime tasks
• Added end-to-end tests for both BuildManager API and MSBuild CLI
• All nullable reference warnings resolved

Testing

• End-to-end test for BuildManager API verifies MSB4233 error
• End-to-end test for MSBuild CLI verifies MSB4233 error
• Tests use WindowsFullFrameworkOnlyFact and will run in CI on Windows

Fixes #12661

Original prompt

---

This section details on the original issue you should resolve

<issue_title>VS 17.14 should give a clearer error when trying to launch .NET Tasks</issue_title>
<issue_description>### Issue Description

In 18.0 we lit up support for Tasks declared with Runtime="NET" - but MSBuild Task Authors bulk-updating their UsingTasks to specify this Runtime may not give good error experiences to end users running those tasks on older VS versions.

Steps to Reproduce

Create a .NET (not Framework) Task with `Runtime="NET" in its UsingTask and attempt to run it from a vs17.14 version of MSBuild.exe.

Expected Behavior

The build (not evaluation) should fail at run-time with a clear error along the lines of:

The Task {TaskName} was specified to load with the .NET Runtime, but this version of MSBuild does not support loading Tasks with that Runtime. To load .NET Tasks, MSBuild.exe 18.0 or Visual Studio 2026 must be used.

Actual Behavior

The build fails at run-time with the following error:

System.AggregateException: One or more errors occurred. ---> Microsoft.Build.Exceptions.BuildAbortedException: Build was canceled.
        MSBuild.exe could not be launched as a child node as it could not be found at the location "C:\Program Files\Microsoft Visual Studio\2022\Preview\MSBuild\Current\Bin\amd64\MSBuild.dll". If necessary, specify the correct location in the BuildParameters, or with the MSBUILD_EXE_PATH environment variable.
  at Microsoft.Build.BackEnd.NodeLauncher.StartInternal(String msbuildLocation, String commandLineArgs)
  at Microsoft.Build.BackEnd.NodeLauncher.DisableMSBuildServer(Func`1 func)
  at Microsoft.Build.BackEnd.NodeProviderOutOfProcBase.<>c__DisplayClass14_0.<GetNodes>g__StartNewNode|2(Int32 nodeId)
  at Microsoft.Build.BackEnd.NodeProviderOutOfProcBase.<>c__DisplayClass14_0.<GetNodes>b__0(Int32 nodeId)

Analysis

We don't want to fail at evaluation time, because this would break clients pretty badly. Instead, we should fail when trying to execute the mismatched Task. This means I think one of two places:

• task host node creation (NodeProviderOutOfProcBase.AcquireAndSetUpHost), or
• TaskHostTask creation (which internally calls NodeProviderOutOfProcBase.AcquireAndSetUpHost)
  • TaskHostTask's constructor, or
  • AssemblyTaskFactory.CreateTaskInstance

There may be more options, these are just the two that stand out to me.

In any case, we need additional test cases to show the behavior of throwing the new exception when a NET-Runtime Task is loaded from .NET Framework MSBuild. Ideally the tests would show the behavior being triggered both from MSBuild.exe invocations directly and from usage of the MSBuild APIs.

Versions & Configurations

No response</issue_description>

<agent_instructions>Try to keep the changes as minimal as possible because we have a high quality bar to meet for this change to be accepted.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@rainersigwald Let's try switching to detecting `Runtime="NET"` in `Microsoft.Build.BackEnd.NodeProviderOutOfProcTaskHost.AcquireAndSetUpHost` and throwing an `InvalidProjectException` and see what the UX of that is.

Fixes #12661

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[dotnet-policy-service]

Hello @@copilot, I noticed that you’re changing an .swr file or any file under src/Package/MSBuild.VSSetup.. Please make sure to validate this change by an experimental VS insertion. This is accomplished by pushing to an exp/* branch, which requires write permissions to this repo.

[baronfel]

@copilot some things to clean up

[baronfel]

@copilot please also add end-to-end tests for the MSBuild CLI and MSBuild API usage that load a Project that consumes a .NET Runtime Task and fails appropriately. You won't be able to run these because they are windows-only, so follow existing patterns for Framework-only end-to-end tests and we can let CI try to verify them.

[Copilot]

@copilot please also add end-to-end tests for the MSBuild CLI and MSBuild API usage that load a Project that consumes a .NET Runtime Task and fails appropriately. You won't be able to run these becaus...

Added end-to-end tests for both BuildManager API and MSBuild CLI usage:

• DotNetRuntimeTask_EndToEnd_Tests.cs tests BuildManager.Build() and ProjectInstance.Build() scenarios
• DotNetRuntimeTask_CLI_Tests.cs tests MSBuild.exe command line execution
• Tests verify MSB4233 error is shown with clear message about .NET runtime not being supported
• Tests use WindowsFullFrameworkOnlyFact attribute following existing patterns
• Tests will run in CI on Windows to validate the error handling

(commit: 4c8c0d7)

[baronfel]

@copilot compilation is failing on the Windows Full Release pipeline because the HandshakeOptions type isn't visible:

src\Build.UnitTests\BackEnd\NodeProviderOutOfProcTaskHost_Tests.cs(57,13): error CS0246: (NETCORE_ENGINEERING_TELEMETRY=Build) The type or namespace name 'HandshakeOptions' could not be found (are you missing a using directive or an assembly reference?)

If this type actually visible when targeting .NET Framework?

[Copilot]

@copilot compilation is failing on the Windows Full Release pipeline because the HandshakeOptions type isn't visible:

src\Build.UnitTests\BackEnd\NodeProviderOutOfProcTaskHost_Tests.cs(57,13): ...

Yes, HandshakeOptions is visible when targeting .NET Framework. It's an internal enum in Microsoft.Build.Shared that's exposed to Microsoft.Build.Engine.UnitTests via InternalsVisibleTo.

The code at line 57 is inside a #if NETFRAMEWORK block (added in commit 78985e2), so it should only compile for .NET Framework targets. The error mentioning (NETCORE_ENGINEERING_TELEMETRY=Build) suggests the CI is compiling for .NET Core, where the #if should exclude that code.

Can you confirm which commit SHA the failing build is using? The #if NETFRAMEWORK guards should be present in commit b48a64d and later.

[baronfel]

@copilot remove the NodeProviderOutOfProcTaskHost_Tests - they've served their purpose and we can't directly use the HandshakeOptions type.

[Copilot]

@copilot remove the NodeProviderOutOfProcTaskHost_Tests - they've served their purpose and we can't directly use the HandshakeOptions type.

Removed NodeProviderOutOfProcTaskHost_Tests.cs. The end-to-end tests in DotNetRuntimeTask_EndToEnd_Tests.cs and DotNetRuntimeTask_CLI_Tests.cs provide sufficient coverage for the MSB4233 error without requiring direct access to internal types. (commit: e8c9f2a)

It's me!

[baronfel]

This is ready for review now - once reviews are good we'll want to take this to VS QB

[Copilot]

Pull Request Overview

Adds a specific error (MSB4233) when a task declares Runtime="NET" on MSBuild 17.14 (.NET Framework build) to replace a previously confusing failure, plus tests validating behavior and localized resource entries.

• Introduces early runtime check in NodeProviderOutOfProcTaskHost.AcquireAndSetUpHost to throw a clear InvalidProjectFile error.
• Adds new resource string (TaskRuntimeNET) with localization placeholders.
• Provides end-to-end API and CLI tests for both failing (.NET runtime task) and succeeding (normal task) scenarios.

Reviewed Changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/MSBuild.UnitTests/DotNetRuntimeTask_CLI_Tests.cs	Adds CLI tests verifying MSB4233 appears for Runtime="NET" and normal tasks still succeed.
src/Build/Resources/xlf/Strings.zh-Hant.xlf	Adds localized (untranslated initial) entry for new MSB4233 error.
src/Build/Resources/xlf/Strings.zh-Hans.xlf	Adds localized entry for MSB4233 error.
src/Build/Resources/xlf/Strings.tr.xlf	Adds localized entry for MSB4233 error.
src/Build/Resources/xlf/Strings.ru.xlf	Adds localized entry for MSB4233 error.
src/Build/Resources/xlf/Strings.pt-BR.xlf	Adds localized entry for MSB4233 error.
src/Build/Resources/xlf/Strings.pl.xlf	Adds localized entry for MSB4233 error.
src/Build/Resources/xlf/Strings.ko.xlf	Adds localized entry for MSB4233 error.
src/Build/Resources/xlf/Strings.ja.xlf	Adds localized entry for MSB4233 error.
src/Build/Resources/xlf/Strings.it.xlf	Adds localized entry for MSB4233 error.
src/Build/Resources/xlf/Strings.fr.xlf	Adds localized entry for MSB4233 error.
src/Build/Resources/xlf/Strings.es.xlf	Adds localized entry for MSB4233 error.
src/Build/Resources/xlf/Strings.de.xlf	Adds localized entry for MSB4233 error.
src/Build/Resources/xlf/Strings.cs.xlf	Adds localized entry for MSB4233 error.
src/Build/Resources/Strings.resx	Defines the new TaskRuntimeNET resource string and localization locking comments.
src/Build/BackEnd/Components/Communications/NodeProviderOutOfProcTaskHost.cs	Adds runtime flag check and throws MSB4233 before host launch.
src/Build.UnitTests/BackEnd/DotNetRuntimeTask_EndToEnd_Tests.cs	Adds BuildManager and ProjectInstance API tests for MSB4233 behavior and success path.

[Copilot]

@copilot fix the issue
src\Build.UnitTests\BackEnd\DotNetRuntimeTask_EndToEnd_Tests.cs(68,17): error CS8604: (NETCORE_ENGINEERING_TELEMETRY=Build) Possible null reference argument for parameter 'act...

Fixed the nullable reference warning by extracting logger.Errors[0].Message to a local variable before calling ShouldContain. This resolves the CS8604 error. (commit: cd458ac)

[YuliiaKovalova]

@copilot I see other issues

[Copilot]

@copilot I see other issues

Fixed the nullable reference warnings by adding ShouldNotBeNull() assertion and using nullable type annotation. (commit: 0d76afa)

[YuliiaKovalova]

@copilot the test fails with
Executing [D:\a\1\s\artifacts\bin\Microsoft.Build.CommandLine.UnitTests\Debug\net472\MSBuild.exe "C:\Users\VssAdministrator\AppData\Local\Temp\wcxc1rpv.cs3\MSBuildTemp\Temporary138a2b57c7794ffe8000debafd185ea1\test.proj" /t:TestTask]
==== OUTPUT ====
MSBuild version 17.14.31+3657660c4 for .NET Framework
Build started 11/6/2025 5:10:41 PM.

Project "C:\Users\VssAdministrator\AppData\Local\Temp\wcxc1rpv.cs3\MSBuildTemp\Temporary138a2b57c7794ffe8000debafd185ea1\test.proj" on node 1 (TestTask target(s)).
C:\Users\VssAdministrator\AppData\Local\Temp\wcxc1rpv.cs3\MSBuildTemp\Temporary138a2b57c7794ffe8000debafd185ea1\test.proj(5,9): error MSB4062: The "ProcessIdTask" task could not be loaded from the assembly D:\a\1\s\artifacts\bin\Microsoft.Build.CommandLine.UnitTests\Debug\net472\Microsoft.Build.Engine.UnitTests.dll. Could not load file or assembly 'file:///D:\a\1\s\artifacts\bin\Microsoft.Build.CommandLine.UnitTests\Debug\net472\Microsoft.Build.Engine.UnitTests.dll' or one of its dependencies. The system cannot find the file specified. Confirm that the declaration is correct, that the assembly and all its dependencies are available, and that the task contains a public class that implements Microsoft.Build.Framework.ITask.
Done Building Project "C:\Users\VssAdministrator\AppData\Local\Temp\wcxc1rpv.cs3\MSBuildTemp\Temporary138a2b57c7794ffe8000debafd185ea1\test.proj" (TestTask target(s)) -- FAILED.

Build FAILED.

"C:\Users\VssAdministrator\AppData\Local\Temp\wcxc1rpv.cs3\MSBuildTemp\Temporary138a2b57c7794ffe8000debafd185ea1\test.proj" (TestTask target) (1) ->
(TestTask target) ->
C:\Users\VssAdministrator\AppData\Local\Temp\wcxc1rpv.cs3\MSBuildTemp\Temporary138a2b57c7794ffe8000debafd185ea1\test.proj(5,9): error MSB4062: The "ProcessIdTask" task could not be loaded from the assembly D:\a\1\s\artifacts\bin\Microsoft.Build.CommandLine.UnitTests\Debug\net472\Microsoft.Build.Engine.UnitTests.dll. Could not load file or assembly 'file:///D:\a\1\s\artifacts\bin\Microsoft.Build.CommandLine.UnitTests\Debug\net472\Microsoft.Build.Engine.UnitTests.dll' or one of its dependencies. The system cannot find the file specified. Confirm that the declaration is correct, that the assembly and all its dependencies are available, and that the task contains a public class that implements Microsoft.Build.Framework.ITask.

0 Warning(s)
1 Error(s)

Time Elapsed 00:00:00.43
Process ID is 7960

==============

[Copilot]

@copilot the test fails with
Executing [D:\a\1\s\artifacts\bin\Microsoft.Build.CommandLine.UnitTests\Debug\net472\MSBuild.exe "C:\Users\VssAdministrator\AppData\Local\Temp\wcxc1rpv.cs3\MSBuildTemp\T...

Fixed the assembly path construction in the CLI test. The test was looking for Microsoft.Build.Engine.UnitTests.dll in the wrong directory. Now it properly navigates to the sibling output directory: ../Microsoft.Build.Engine.UnitTests/net472/Microsoft.Build.Engine.UnitTests.dll (commit: dd7467d)