Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

MSBuild Batching

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

Task batching allows you to simplify your project files by providing a way to divide item lists 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 list into batches based on the Color item metadata value, and passes each of the batches to the MyTask task separately.

NoteNote

If you do not reference the item list 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="http://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 Item Metadata in Task 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 list 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="http://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 Item Metadata in Target Batching.

Batching can be controlled by property functions that include metadata. For example,

$([System.IO.Path]::Combine($(RootPath),%(Compile.Identity)))

uses Combine to combine a root folder path with a Compile item path.

Property functions may not appear within metadata values. For example,

%(Compile.FullPath.Substring(0,3))

is not allowed.

For more information about property functions, see Property Functions.

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.