From 7db11d47c41aebe755066e65e3fe7a87a4e50074 Mon Sep 17 00:00:00 2001 From: Chet Husk Date: Fri, 17 Oct 2025 09:00:13 -0500 Subject: [PATCH] Update .NET TaskHost docs with some more caveats --- release-notes/10.0/preview/rc2/sdk.md | 30 ++++++++++++++++++++++++--- 1 file changed, 27 insertions(+), 3 deletions(-) diff --git a/release-notes/10.0/preview/rc2/sdk.md b/release-notes/10.0/preview/rc2/sdk.md index f4fc6a4d8a..29fcb67f98 100644 --- a/release-notes/10.0/preview/rc2/sdk.md +++ b/release-notes/10.0/preview/rc2/sdk.md @@ -83,11 +83,35 @@ Thanks to the `Condition` feature of MSBuild, you can load a Task differently de Framework (Visual Studio or `msbuild.exe`) or .NET (the `dotnet` CLI). In this example, the Task will run out-of-process when running in Visual Studio or `msbuild.exe`, but will run in-process when running in the `dotnet` CLI. This gives the best performance when running in the `dotnet` CLI, while still allowing the Task to be used in Visual Studio and `msbuild.exe`. +A [future version](https://github.com/dotnet/msbuild/pull/12642) will simplify this syntax so that only the `Runtime="NET"` +addition is required. There are also small technical limitations to be aware of when using .NET Tasks in MSBuild - the most notable of which is -that the `Host Object` feature of MSBuild Tasks is not yet supported for .NET Tasks running out-of-process. This means -that if your Task relies on a Host Object, it will not work when running in Visual Studio or `msbuild.exe`. We are actively -working on adding support for Host Objects in future releases. +that the `Host Object` feature of MSBuild Tasks is [not yet supported](https://github.com/dotnet/msbuild/issues/11510) for .NET +Tasks running out-of-process. This means that if your Task relies on a Host Object, it will not work when running in Visual Studio +or `msbuild.exe`. We are actively working on adding support for Host Objects in future releases. + +> [!IMPORTANT] +> Support for `Runtime="NET"` is only available in Visual Studio 2026/MSBuild.exe version 18.0 and above. + +Loading a Task declared with `Runtime="NET"` in an earlier version of Visual Studio or MSBuild.exe will result in an error like the following: + +``` +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\2026\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.g__StartNewNode|2(Int32 nodeId) + at Microsoft.Build.BackEnd.NodeProviderOutOfProcBase.<>c__DisplayClass14_0.b__0(Int32 nodeId) +``` + +For this reason, you will likely need two `UsingTask` elements for each Task you want to load: + + * one comparing against `MSBuild::VersionGreaterThanOrEquals('$(MSBuildVersion)', '18.0.0')` for environments that support the .NET TaskHost + * one comparing against `MSBuild::VersionLessThan('$(MSBuildVersion)', '18.0.0')` for environments that do not support the .NET TaskHost + +If you don't do this UsingTask-based version detection, then you should have some other kind of version-checking that issues +some kind of warning message to a user that they are using an unsupported configuration ### Future work