MSBuild task
Builds MSBuild projects from another MSBuild project.
Parameters
The following table describes the parameters of the MSBuild task.
| Parameter | Description |
|---|---|
BuildInParallel |
Optional Boolean parameter.If true, the projects specified in the Projects parameter are built in parallel if it is possible. Default is false. |
Projects |
Required ITaskItem[] parameter.Specifies the project files to build. |
Properties |
Optional String parameter.A semicolon-delimited list of property name/value pairs to apply as global properties to the child project. When you specify this parameter, it is functionally equivalent to setting properties that have the -property switch when you build with MSBuild.exe. For example: Properties="Configuration=Debug;Optimize=$(Optimize)"When you pass properties to the project through the Properties parameter, MSBuild might create a new instance of the project even if the project file has already been loaded. MSBuild creates a single project instance for a given project path and a unique set of global properties. For example, this behavior allows you to create multiple MSBuild tasks that call myproject.proj, with Configuration=Release and you get a single instance of myproject.proj (if no unique properties are specified in the task). If you specify a property that has not yet been seen by MSBuild, MSBuild creates a new instance of the project, which can be built in parallel to other instances of the project. For example, a Release configuration can build at the same time as a Debug configuration. |
RebaseOutputs |
Optional Boolean parameter.If true, the relative paths of target output items from the built projects have their paths adjusted to be relative to the calling project. Default is false. |
RemoveProperties |
Optional String parameter.Specifies the set of global properties to remove. |
RunEachTargetSeparately |
Optional Boolean parameter.If true, the MSBuild task invokes each target in the list passed to MSBuild one at a time, instead of at the same time. Setting this parameter to true guarantees that subsequent targets are invoked even if previously invoked targets failed. Otherwise, a build error would stop invocation of all subsequent targets. Default is false. |
SkipNonexistentProjects |
Optional Boolean parameter.If true, project files that do not exist on the disk will be skipped. Otherwise, such projects will cause an error. Defaults to false. |
SkipNonexistentTargets |
Optional Boolean parameter.If true, project files that exist but do not contain the named Targets will be skipped. Otherwise, such projects will cause an error. Defaults to false. Introduced in MSBuild 15.5. |
StopOnFirstFailure |
Optional Boolean parameter.If true, when one of the projects fails to build, no more projects will be built. Currently this is not supported when building in parallel (with multiple processors). |
TargetAndPropertyListSeparators |
Optional String[] parameter.Specifies a list of targets and properties as Project item metadata). Separators will be un-escaped before processing. e.g. %3B (an escaped ';') will be treated as if it were an un-escaped ';'. |
TargetOutputs |
Optional ITaskItem[] read-only output parameter.Returns the outputs of the built targets from all the project files. Only the outputs from the targets that were specified are returned, not any outputs that may exist on targets that those targets depend on. The TargetOutputs parameter also contains the following metadata:- MSBuildSourceProjectFile: The MSBuild project file that contains the target that set the outputs.- MSBuildSourceTargetName: The target that set the outputs. Note: If you want to identify the outputs from each project file or target separately, run the MSBuild task separately for each project file or target. If you run the MSBuild task only once to build all the project files, the outputs of all the targets are collected into one array. |
Targets |
Optional String parameter.Specifies the target or targets to build in the project files. Use a semicolon to separate a list of target names. If no targets are specified in the MSBuild task, the default targets specified in the project files are built. Note: The targets must occur in all the project files. If they do not, a build error occurs. |
ToolsVersion |
Optional String parameter.Specifies the ToolsVersion to use when building projects passed to this task.Enables an MSBuild task to build a project that targets a different version of the .NET Framework than the one specified in the project. Valid values are 2.0, 3.0 and 3.5. Default value is 3.5. |
Remarks
In addition to the parameters listed above, this task inherits parameters from the TaskExtension class, which itself inherits from the Task class. For a list of these additional parameters and their descriptions, see TaskExtension base class.
Unlike using the Exec task to start MSBuild.exe, this task uses the same MSBuild process to build the child projects. The list of already-built targets that can be skipped is shared between the parent and child builds. This task is also faster because no new MSBuild process is created.
This task can process not only project files but also solution files.
Any configuration that is required by MSBuild to enable projects to build at the same time, even if the configuration involves remote infrastructure (for example, ports, protocols, timeouts, retries, and so forth), must be made configurable by using a configuration file. When possible, configuration items should be able to be specified as task parameters on the MSBuild task.
Beginning in MSBuild 3.5, Solution projects now surface TargetOutputs from all of the sub-projects it builds.
Pass properties to projects
In versions of MSBuild prior to MSBuild 3.5, passing different sets of properties to different projects listed in the MSBuild item was challenging. If you used the Properties attribute of the MSBuild task, then its setting was applied to all of the projects being built unless you batched the MSBuild task and conditionally provided different properties for each project in the item list.
MSBuild 3.5, however, provides two new reserved metadata items, Properties and AdditionalProperties, that provide you a flexible way to pass different properties for different projects being built using the MSBuild task.
Note
These new metadata items are applicable only to items passed in the Projects attribute of the MSBuild task.
Multi-processor build benefits
One of the major benefits of using this new metadata occurs when you build your projects in parallel on a multi-processor system. The metadata allows you to consolidate all projects into a single MSBuild task call without having to perform any batching or conditional MSBuild tasks. And when you call only a single MSBuild task, all of the projects listed in the Projects attribute will be built in parallel. (Only, however, if the BuildInParallel=true attribute is present in the MSBuild task.) For more information, see Build multiple projects in parallel.
Properties metadata
When specified, Properties metadata overrides the task's Properties parameter, while AdditionalProperties metadata gets appended to the parameter's definitions.
A common scenario is when you are building multiple solution files using the MSBuild task, only using different build configurations. You may want to build solution a1 using the Debug configuration and solution a2 using the Release configuration. In MSBuild 2.0, this project file would look like the following:
Note
In the following example, "..." represents additional solution files.
a.proj
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<Target Name="Build">
<MSBuild Projects="a1.sln..." Properties="Configuration=Debug"/>
<MSBuild Projects="a2.sln" Properties="Configuration=Release"/>
</Target>
</Project>
By using the Properties metadata, however, you can simplify this to use a single MSBuild task, as shown by the following:
a.proj
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<ItemGroup>
<ProjectToBuild Include="a1.sln...">
<Properties>Configuration=Debug</Properties>
</ProjectToBuild>
<ProjectToBuild Include="a2.sln">
<Properties>Configuration=Release</Properties>
</ProjectToBuild>
</ItemGroup>
<Target Name="Build">
<MSBuild Projects="@(ProjectToBuild)"/>
</Target>
</Project>
- or -
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<ItemGroup>
<ProjectToBuild Include="a1.sln..."/>
<ProjectToBuild Include="a2.sln">
<Properties>Configuration=Release</Properties>
</ProjectToBuild>
</ItemGroup>
<Target Name="Build">
<MSBuild Projects="@(ProjectToBuild)"
Properties="Configuration=Debug"/>
</Target>
</Project>
AdditionalProperties metadata
Consider the following scenario where you are building two solution files using the MSBuild task, both using the Release configuration, but one using the x86 architecture and the other using the ia64 architecture. In MSBuild 2.0, you would need to create multiple instances of the MSBuild task: one to build the project using the Release configuration with the x86 Architecture, the other using the Release configuration with the ia64 architecture. Your project file would look like the following:
a.proj
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<Target Name="Build">
<MSBuild Projects="a1.sln..." Properties="Configuration=Release;
Architecture=x86"/>
<MSBuild Projects="a2.sln" Properties="Configuration=Release;
Architecture=ia64"/>
</Target>
</Project>
By using the AdditionalProperties metadata, you can simplify this to use a single MSBuild task by using the following:
a.proj
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<ItemGroup>
<ProjectToBuild Include="a1.sln...">
<AdditionalProperties>Architecture=x86
</AdditionalProperties>
</ProjectToBuild>
<ProjectToBuild Include="a2.sln">
<AdditionalProperties>Architecture=ia64
</AdditionalProperties>
</ProjectToBuild>
</ItemGroup>
<Target Name="Build">
<MSBuild Projects="@(ProjectToBuild)"
Properties="Configuration=Release"/>
</Target>
</Project>
Example
The following example uses the MSBuild task to build the projects specified by the ProjectReferences item collection. The resulting target outputs are stored in the AssembliesBuiltByChildProjects item collection.
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<ItemGroup>
<ProjectReferences Include="*.*proj" />
</ItemGroup>
<Target Name="BuildOtherProjects">
<MSBuild
Projects="@(ProjectReferences)"
Targets="Build">
<Output
TaskParameter="TargetOutputs"
ItemName="AssembliesBuiltByChildProjects" />
</MSBuild>
</Target>
</Project>