MSBuild Batching

MSBuild has the ability to divide item collections into different categories, or batches, based on item metadata, and run a target or task one time with each batch.

Task Batching

Task batching allows you to simplify your project files by providing a way to divide item collections into different batches and pass each of those batches into a task separately. This means that a project file only needs to have the task and its attributes declared once, even though it can be run several times.

You specify that you want MSBuild to perform batching with a task by using the %(ItemMetaDataName) notation in one of the task attributes. The following example splits the Example item collection into batches based on the Color item metadata value, and passes each of the batches to the MyTask task separately.

Note

If you do not reference the item collection elsewhere in the task attributes, or the metadata name may be ambiguous, you can use the %(ItemCollection.ItemMetaDataName) notation to fully qualify the item metadata value to use for batching.

<Project
    xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
    
    <ItemGroup>
        <Example Include="Item1">
            <Color>Blue</Color>
        </Example>
        <Example Include="Item2">
            <Color>Red</Color>
        </Example>
    </ItemGroup>

    <Target Name="RunMyTask">
        <MyTask
            Sources = "@(Example)"
            Output = "%(Color)\MyFile.txt"/>
    </Target>

</Project>

For more specific batching examples, see How to: Batch Tasks By Using Item Metadata.

Target Batching

MSBuild checks if the inputs and outputs of a target are up-to-date before it runs the target. If both inputs and outputs are up-to-date, the target is skipped. If a task inside of a target uses batching, MSBuild needs to determine if the inputs and outputs for each batch of items is up-to-date. Otherwise, the target is executed every time it is hit.

The following example shows a Target element that contains an Outputs attribute with the %(ItemMetaDataName) notation. MSBuild will divide the Example item collection into batches based on the Color item metadata, and analyze the timestamps of the output files for each batch. If the outputs from a batch are not up-to-date, the target is run. Otherwise, the target is skipped.

<Project
    xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
    
    <ItemGroup>
        <Example Include="Item1">
            <Color>Blue</Color>
        </Example>
        <Example Include="Item2">
            <Color>Red</Color>
        </Example>
    </ItemGroup>

    <Target Name="RunMyTask"
        Inputs="@(Example)"
        Outputs="%(Color)\MyFile.txt">
        <MyTask
            Sources = "@(Example)"
            Output = "%(Color)\MyFile.txt"/>
    </Target>

</Project>

For another example of target batching, see How to: Batch Targets By Using Item Metadata.

See Also

Concepts

MSBuild Advanced Concepts

Reference

ItemMetadata Element (MSBuild)

Other Resources

MSBuild Concepts

MSBuild Reference