Skip to content

Update .NET TaskHost docs with some more caveats #10127

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update .NET TaskHost docs with some more caveats #10127

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
30 changes: 27 additions & 3 deletions release-notes/10.0/preview/rc2/sdk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.<GetNodes>g__StartNewNode|2(Int32 nodeId)
at Microsoft.Build.BackEnd.NodeProviderOutOfProcBase.<>c__DisplayClass14_0.<GetNodes>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

Expand Down