diff --git a/docs/msbuild/how-to-configure-targets-and-tasks.md b/docs/msbuild/how-to-configure-targets-and-tasks.md index 227c12dc3d2..d24f99ad7df 100644 --- a/docs/msbuild/how-to-configure-targets-and-tasks.md +++ b/docs/msbuild/how-to-configure-targets-and-tasks.md @@ -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 `` 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 `` element: ```xml [!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 - - + + + ``` ### Why Use the .NET TaskHost? diff --git a/docs/msbuild/usingtask-element-msbuild.md b/docs/msbuild/usingtask-element-msbuild.md index f877330ac95..6667d024e19 100644 --- a/docs/msbuild/usingtask-element-msbuild.md +++ b/docs/msbuild/usingtask-element-msbuild.md @@ -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.

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 method in .NET.

You cannot use this attribute if the `AssemblyFile` attribute is used.| |`AssemblyFile`|Either the `AssemblyName` or the `AssemblyFile` attribute is required.

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 method in .NET.

You cannot use this attribute if the `AssemblyName` attribute is used.| |`Override`|Optional attribute.

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.

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.

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.

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.

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.

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.

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.

The condition to evaluate. For more information, see [Conditions](../msbuild/msbuild-conditions.md).|