New Methods for Manipulating Items and Properties (MSBuild)

Beginning in MSBuild 3.5, you can do the following:

  • Define an Item Definition Group to contain metadata that applies to all items in the project.

  • Dynamically create, delete, combine, or change properties, items, and item metadata directly in an Item Group. You can do this instead of using the CreateItem task and the CreateProperty task.

Item Definition Groups

The ItemDefinitionGroup element lets you define a set of Item Definitions, which are metadata values that are applied to all items in the project, by default. For more information, see Item Definitions.

Dynamically Adjust Metadata in an Item Group

MSBuild uses the ItemGroup Element (MSBuild) and the PropertyGroup Element (MSBuild) to statically declare items and properties. In MSBuild 2.0, when you wanted to create or modify properties and items during the build, you had to use the CreateItem Task or the CreateProperty Task. This process was cumbersome and did not support dynamic updates very well. However, MSBuild 3.5 lets you dynamically create, delete, combine, or change properties, items, and item metadata directly in an Item Group.

Compare the following examples. Example 1 shows how to use the CreateItem task to add a task parameter and to create a new item list along with metadata. Example 3 shows the new method of adding metadata directly in the ItemGroup.

Example 1: A simple example of adding a task parameter by using the CreateItem task. The first target uses the CreateItem task to dynamically create a new item list called CultureResource. The second target adds new metadata, called TargetDirectory, for all Culture resources in the original list.

<Target Name="GenerateBeforeCompile">
     <CreateItem Include="SomeGeneratedCode.cs">
        <Output TaskParameter="Include" ItemName="Compile" /> 
    </CreateItem>
</Target>

<Target Name="ProcessCultureResources">
    <CreateItem Include="@(EmbeddedResource)" 
      Condition="'%(Culture)' != ''"
      AdditionalMetadata="TargetDirectory=%
      (EmbeddedResource.Culture)">
    <Output TaskParameter="Include" ItemName="CultureResource" />
    </CreateItem>
</Target>

Example 2: The results from the previous examples can now be achieved by adding parameters and metadata directly into the ItemGroup.

<Target Name="GenerateBeforeCompile">
     <ItemGroup>
        <Compile Include="SomeGeneratedCode.cs" />
    </ItemGroup>
 </Target>
 
<Target Name="ProcessCultureResources">
    <ItemGroup>
        <CultureResource Include="@(EmbeddedResource)"
          Condition="'%(EmbeddedResource.Culture)' != ''">
             <TargetDirectory>%(EmbeddedResource.Culture) </TargetDirectory>
        </CultureResource>
    </ItemGroup>
</Target>

Removing Items

To omit items from lists in prior versions of MSBuild, you had to create new lists. Now, however, you can directly remove items using the new Remove parameter, as shown by the following:

<ItemGroup>
    <!—Remove *.licx from the EmbeddedResource list - ->
    <EmbeddedResource Remove="*.licx" />
 
    <!—Or remove items in @(licx) from EmbeddedResource list -- >
    <EmbeddedResource Remove="@(licx)" />
</ItemGroup>

See Also

Concepts

MSBuild Project File Schema Reference

Other Resources

MSBuild Concepts