How to: Configure targets and tasks
Selected MSBuild tasks can be set to run in the environment they target, when the development computer supports the target environment. For example, when you use a 64-bit Windows computer to build an application that targets a 32-bit Windows architecture, then selected tasks are run in a 32-bit process.
If a build task is written in a .NET language, such as Visual C# or Visual Basic, and does not use native resources or tools, then it will run in any target context without adaptation.
UsingTask attributes and task parameters
UsingTask attributes affect all operations of a task in a particular build process:
Runtimeattribute, if present, sets the common language runtime (CLR) version, and can take any one of these values:
Architectureattribute, if present, sets the platform and bitness, and can take any one of these values:
TaskFactoryattribute, if present, sets the task factory that creates and runs the task instance, and takes only the value
TaskHostFactory. For more information, see Task factories later in this document.
<UsingTask TaskName="SimpleTask" Runtime="CLR2" Architecture="x86" AssemblyFile="$(MSBuildToolsPath)\Microsoft.Build.Tasks.v3.5.dll" />
You can also use the
MSBuildArchitecture parameters to set the target context of an individual task invocation.
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003"> <Target Name="MyTarget"> <SimpleTask MSBuildRuntime="CLR2" MSBuildArchitecture= "x86"/> </Target> </Project>
Before MSBuild runs a task, it looks for a matching
UsingTask that has the same target context. Parameters that are specified in the
UsingTask but not in the corresponding task are considered to be matched. Parameters that specified in the task but not in the corresponding
UsingTask are also considered to be matched. If parameter values are not specified in either the
UsingTask or the task, the values default to
* (any parameter).
If more than one
UsingTask exists and all have matching
Architecture attributes, the first one to be evaluated replaces the others. This is different from behavior of
If parameters are set on the task, MSBuild attempts to find a
UsingTask that matches these parameters or, at least, is not in conflict with them. More than one
UsingTask can specify the target context of the same task. For example, a task that has different executables for different target environments might resemble this one:
<UsingTask TaskName="MyTool" Runtime="CLR2" Architecture="x86" AssemblyFile="$(MyToolsPath)\MyTool.v2.0.dll" /> <UsingTask TaskName="MyTool" Runtime="CLR4" Architecture="x86" AssemblyFile="$(MyToolsPath)\MyTool.4.0.dll" /> <Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003"> <Target Name="MyTarget"> <MyTool MSBuildRuntime="CLR2" MSBuildArchitecture= "x86"/> </Target> </Project>
Overriding default UsingTasks
By default, MSBuild handles UsingTask's as "first one wins." Starting in 17.2, MSBuild supports overriding this behavior via the
Override parameter. A UsingTask with the parameter
Override set to
true will take priority over any other UsingTask of the same TaskName.
<UsingTask TaskName="MyTool" Runtime="CLR4" Architecture="x86" Override="true" AssemblyFile="$(MyToolsPath)\MyTool.4.0.dll" />
This can only be done once per task. Builds that attempt to add multiple overrides for the same task will receive MSBuild error
Before it runs a task, MSBuild checks to see whether it is designated to run in the current software context. If the task is so designated, MSBuild passes it to the AssemblyTaskFactory, which runs it in the current process; otherwise, MSBuild passes the task to the TaskHostFactory, which runs the task in a process that matches the target context. Even if the current context and the target context match, you can force a task to run out-of-process (for isolation, security, or other reasons) by setting
<UsingTask TaskName="MisbehavingTask" TaskFactory="TaskHostFactory" AssemblyFile="$(MSBuildToolsPath)\MyTasks.dll"> </UsingTask>
Phantom task parameters
Like any other task parameters,
MSBuildArchitecture can be set from build properties.
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003"> <PropertyGroup> <FrameworkVersion>3.0</FrameworkVersion> </PropertyGroup> <Target Name="MyTarget"> <SimpleTask MSBuildRuntime="$(FrameworkVerion)" MSBuildArchitecture= "x86"/> </Target> </Project>
Unlike other task parameters,
MSBuildArchitecture are not apparent to the task itself. To write a task that is aware of the context in which it runs, you must either test the context by calling the .NET Framework, or use build properties to pass the context information through other task parameters.
UsingTask attributes can be set from toolset and environment properties.
MSBuildArchitecture parameters provide the most flexible way to set the target context, but also the most limited in scope. On the one hand, because they are set on the task instance itself and are not evaluated until the task is about to run, they can derive their value from the full scope of properties available at both evaluation-time and build-time. On the other hand, these parameters only apply to a particular instance of a task in a particular target.
Task parameters are evaluated in the context of the parent node, not in the context of the task host. Environment variables that are runtime- or architecture- dependent (such as the Program Files location) will evaluate to the value that matches the parent node. However, if the same environment variable is read directly by the task, it will correctly be evaluated in the context of the task host.
Submit and view feedback for