Skip to content

docs(msbuild): clarify UsingTask Runtime=NET support #11176

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
fuguiKz wants to merge 1 commit into
base: main
Choose a base branch
from
+14 −7
Open

docs(msbuild): clarify UsingTask Runtime=NET support #11176

Show file tree
Hide file tree
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
19 changes: 13 additions & 6 deletions docs/msbuild/how-to-configure-targets-and-tasks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,7 @@ For most MSBuild tasks, the default process is sufficient. But for custom or mor

## Using the .NET TaskHost

With the release of the .NET 10 SDK and Visual Studio 2026, MSBuild introduced support for a `.NET TaskHost`. This feature allows MSBuild to run Tasks that must use a .NET runtime on a separate .NET process. This is enabled via the `Runtime="NET"` attribute in the `<UsingTask>` element:
With the release of the .NET 10 SDK and Visual Studio 2026, MSBuild introduced support for a `.NET TaskHost`. This feature allows MSBuild to run tasks that must use a .NET runtime in a separate .NET process. This is enabled via the `Runtime="NET"` attribute in the `<UsingTask>` element:

```xml
<UsingTask TaskName="MyNetTask"
Expand All @@ -137,18 +137,25 @@ With the release of the .NET 10 SDK and Visual Studio 2026, MSBuild introduced s
```

When this attribute is set:
- MSBuild automatically manages a pool of .NET TaskHost process and executes the specified task on a node in that pool.
- MSBuild automatically manages a pool of .NET TaskHost processes and executes the specified task on a node in that pool.
- Tasks can take advantage of APIs or libraries exclusive to modern .NET runtimes.
- Isolation protects the build process from dependency or version conflicts.

> [!WARNING]
> This `.NET TaskHost` capability using `Runtime="NET"` is only available in projects that use the Microsoft.NET.Sdk **version 10 or higher** and/or **Visual Studio 2026 and later** (version 18 or higher). It is **not** supported in earlier SDKs, earlier Visual Studio versions, or in projects based on other SDKs. Attempting to use `Runtime="NET"` in these contexts may result in build failures or ignored settings.
> This `.NET TaskHost` capability using `Runtime="NET"` is supported starting in MSBuild 18.0 (.NET SDK 10 / Visual Studio 2026) and is currently only supported for projects using `Microsoft.NET.Sdk`.

Attempting to use the .NET TaskHost feature with a .NET SDK before 10.0.100 results in errors for your users when they build. To prevent this, you can do a version check to determine if the feature is safe to use. Here's, we'll use a version-comparison MSBuild Property Function to see if the current build is happening in a version greater than or equal to 10.0.100, and if so use the `NET` Runtime. Otherwise, if we're below SDK version 10.0.100 and running on the .NET Framework version of MSBuild, then we'll use a .NET Framework Task implementation instead.
If you ship targets that need to work with older MSBuild toolsets, you can conditionally select a `UsingTask` definition based on the current MSBuild version (and, when applicable, `$(MSBuildRuntimeType)`):

```xml
<UsingTask .... AssemblyFile="my/netcore/tasks.dll" Runtime="NET" Condition="$([MSBuild]::VersionGreaterThanOrEquals('$(SdkAnalysisLevel)', '10.0.100'))" />
<UsingTask .... AssemblyFile="my/netframework/tasks.dll" Condition="!$([MSBuild]::VersionGreaterThanOrEquals('$(SdkAnalysisLevel)', '10.0.100')) and $(MSBuildRuntimeType) == 'Full' " />
<UsingTask TaskName="MyTask"
Runtime="NET"
AssemblyFile="my/net/tasks.dll"
Condition="$([MSBuild]::VersionGreaterThanOrEquals('$(MSBuildVersion)', '18.0'))" />

<UsingTask TaskName="MyTask"
Runtime="CLR4"
AssemblyFile="my/netframework/tasks.dll"
Condition="!$([MSBuild]::VersionGreaterThanOrEquals('$(MSBuildVersion)', '18.0')) and '$(MSBuildRuntimeType)' == 'Full'" />
```

### Why Use the .NET TaskHost?
Expand Down
2 changes: 1 addition & 1 deletion docs/msbuild/usingtask-element-msbuild.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ Maps the task that is referenced in a [Task](../msbuild/task-element-msbuild.md)
|`AssemblyName`|Either the `AssemblyName` attribute or the `AssemblyFile` attribute is required.<br /><br /> The name of the assembly to load. The `AssemblyName` attribute accepts strong-named assemblies, although strong-naming is not required. Using this attribute is equivalent to loading an assembly by using the <xref:System.Reflection.Assembly.Load%2A> method in .NET.<br /><br /> You cannot use this attribute if the `AssemblyFile` attribute is used.|
|`AssemblyFile`|Either the `AssemblyName` or the `AssemblyFile` attribute is required.<br /><br /> The file path of the assembly. This attribute accepts full paths or relative paths. Relative paths are relative to the directory of the project file or targets file where the `UsingTask` element is declared. Using this attribute is equivalent to loading an assembly by using the <xref:System.Reflection.Assembly.LoadFrom%2A> method in .NET.<br /><br /> You cannot use this attribute if the `AssemblyName` attribute is used.|
|`Override`|Optional attribute.<br /><br /> Specifies that this `UsingTask` element should be higher priority than other elements defining the same task name. Only one override is permitted per task name. Added in MSBuild 17.2.|
|`Runtime`|Optional attribute.<br /><br /> Specifies that the task must run in a .NET Framework runtime of the specified version. If the current process does not satisfy the requirement, the task runs in a task host process that does.<br /><br /> Supported values are 'NET' (.NET Core and .NET 5 or higher), `CLR2` (.NET Framework 3.5), `CLR4` (.NET Framework 4.7.2 or higher), `CurrentRuntime`, `NET` (starting in .NET 10 or higher), and `*` (any runtime). You can only call `NET` Runtime tasks when you're running the .NET Framework MSBuild when you're using MSBuild 18.0 (Visual Studio 2026 or later) or .NET SDK 10 or higher, and you can't call CLR2/CLR4 tasks from the .NET MSBuild (when running `dotnet build`).|
|`Runtime`|Optional attribute.<br /><br /> Specifies the runtime the task must run under. If the current MSBuild process does not satisfy the requirement, the task runs in a task host process that does.<br /><br /> Supported values are `CLR2` (.NET Framework 3.5), `CLR4` (.NET Framework 4.7.2 or higher), `CurrentRuntime`, `NET` (.NET), and `*` (any runtime). `Runtime="NET"` is supported starting in MSBuild 18.0 (.NET SDK 10/Visual Studio 2026) and is currently only supported for projects using `Microsoft.NET.Sdk`. `dotnet build` (the .NET version of MSBuild) can't run `CLR2`/`CLR4` tasks.|
|`TaskFactory`|Optional attribute.<br /><br /> Specifies the class in the assembly that is responsible for generating instances of the specified `Task` name. The user may also specify a `Task` as a child element that the task factory receives and uses to generate the task. The contents of the `Task` are specific to the task factory. The default `TaskFactory` is `AssemblyTaskFactory`, which loads the task into the running process.|
|`TaskName`|Required attribute.<br /><br /> The name of the task to reference from an assembly. If ambiguities are possible, this attribute should always specify full namespaces. If there are ambiguities, MSBuild chooses an arbitrary match, which could produce unexpected results.|
|`Condition`|Optional attribute.<br /><br /> The condition to evaluate. For more information, see [Conditions](../msbuild/msbuild-conditions.md).|
Expand Down