How to: Configure Targets and Tasks

Selected MSBuild tasks can be set to run in the environment they target, regardless of the environment of the development computer. For example, when you use a 64-bit computer to build an application that targets a 32-bit architecture, selected tasks are run in a 32-bit process.

UsingTask Attributes and Task Parameters

The following UsingTask attributes affect all operations of a task in a particular build process:

• The Runtime attribute, if present, sets the common language runtime (CLR) version, and can take any one of these values: CLR2, CLR4, CurrentRuntime, or * (any runtime).

• The Architecture attribute, if present, sets the platform and bitness, and can take any one of these values: x86, x64, CurrentArchitecture, or * (any architecture).

• The TaskFactory attribute, if present, sets the task factory that creates and runs the task instance, and takes only the value TaskHostFactory. For more information, see the Task Factories section later in this document.

<UsingTask TaskName="SimpleTask"   
   Runtime="CLR2"  
   Architecture="x86"  
   AssemblyFile="$(MSBuildToolsPath)\Microsoft.Build.Tasks.v3.5.dll" />  

You can also use the MSBuildRuntime and MSBuildArchitecture parameters to set the target context of an individual task.

<Project xmlns="https://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 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="https://schemas.microsoft.com/developer/msbuild/2003">  
   <Target Name="MyTarget">  
      <MyTool MSBuildRuntime="CLR2" MSBuildArchitecture= "x86"/>  
   </Target>  
</Project>  
  

Task Factories

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 TaskFactory to TaskHostFactory.

<UsingTask TaskName="MisbehavingTask"   
   TaskFactory="TaskHostFactory"  
   AssemblyFile="$(MSBuildToolsPath)\MyTasks.dll">  
</UsingTask>  

Phantom Task Parameters

Like any other task parameters, MSBuildRuntime and MSBuildArchitecture can be set from build properties.

<Project xmlns="https://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, MSBuildRuntime and 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.

The MSBuildRuntime and 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.

See Also

Configuring Targets and Tasks