Export (0) Print
Expand All

MSBuild Task

Updated: December 2009

Builds MSBuild projects from another MSBuild project.

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 true.

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 creates a new instance of the project even if the project file has already been loaded. When a new instance of the project has been created, MSBuild treats it as a different project that has different global properties and that can be built in parallel with other instances of the project. For example, a Release configuration could build at the same time as a Debug configuration.

ToolsVersion

Optional String parameter.

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.

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.

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.

StopOnFirstFailure

Optional Boolean parameter.

If true, forces the task to stop building the remaining projects as soon as any one of them may not work.

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:

  • MSBuildProjectFile: The MSBuild project file that contains the target that set the outputs.

  • MSBuildTargetName: The target that set the outputs.

NoteNote:

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.

NoteNote:

The targets must occur in all the project files. If they do not, a build error occurs.

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.

Passing 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.

NoteNote:

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 Building for Multiple Processors.

Properties Metadata

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:

NoteNote:

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>

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>

Date

History

Reason

December 2009

Changed default value for BuildInParallel.

Content bug fix.

Changed BuildInParallel default back to true, per Microsoft.Common.Targets file.

Content bug fix.

Community Additions

ADD
Show:
© 2014 Microsoft