MSBuild Task

Builds MSBuild projects from another MSBuild project.

Parameters

The following table describes the parameters of the MSBuild task.

Remarks

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.

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:

a.proj

<Project xmlns="https://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="https://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="https://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="https://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="https://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="https://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>

See Also

Concepts

MSBuild Tasks

Other Resources

MSBuild Task Reference

Change History