MSBuild Items
Items are inputs into the build system, and typically represent files. Items are grouped into item types based on their element names. Item types are named lists of items that can be used as parameters for tasks. The tasks use the item values to perform the steps of the build process.
Because items are named by the item type they belong to, the terms "item" and "item value" can be used interchangeably.
Creating Items in a Project File
Items are declared in the project file as child elements of an ItemGroup element. The name of the child element is the type of the item. The Include attribute of the element specifies the items (files) to be included with that item type. For example, the following XML creates an item type named Compile, which includes two files.
<ItemGroup>
<Compile Include = "file1.cs"/>
<Compile Include = "file2.cs"/>
</ItemGroup>
The item "file2.cs" does not replace the item "file1.cs"; instead, it is appended to the list of values for the Compile item type. An item cannot be removed from an item type during the evaluation phase of a build.
The following XML creates the same item type by declaring both files in one Include attribute. Notice that the file names are separated by a semicolon.
<ItemGroup>
<Compile Include = "file1.cs;file2.cs"/>
</ItemGroup>
Creating Items During Execution
Items positioned outside Target elements are assigned values during the evaluation phase of a build. During the subsequent execution phase, items can be created or modified as follows:
Items can be emitted by any task. To emit an item, the Task element must have a child Output element that has an ItemName attribute.
Items can be emitted by the CreateItem task. This usage is deprecated.
Starting in the .NET Framework 3.5, Target elements may contain ItemGroup elements that may contain item elements.
Referencing Items in a Project File
Item types are referenced throughout the project file by using the syntax @(ItemType). For example, the item type in the previous example would be referenced by using @(Compile). This syntax lets you pass items to tasks by specifying the item type as a parameter of that task. For more information, see How to: Select the Files to Build.
By default, the items of an item type are separated by semicolons (;) when it is expanded. Use the syntax @(ItemType, 'separator') to specify a separator other than the default. For more information, see How to: Display an Item List Separated with Commas.
Using Wildcards to Specify Items
You can use the **, *, and ? wildcard characters to specify a group of files as inputs for a build instead of listing each file separately.
The ? wildcard character matches a single character.
The * wildcard character matches zero or more characters.
The ** wildcard character sequence matches a partial path.
For example, to specify all the .cs files in the directory that contains the project file, use the following element in your project file.
<CSFile Include="*.cs"/>
An element that selects all .vb files on the D: drive would be
<VBFile Include="D:/**/*.vb"/>
For more information about wildcard characters, see How to: Select the Files to Build.
Using the Exclude Attribute
Item elements can contain the Exclude attribute, which excludes specific items (files) from the item type. The Exclude attribute is typically used together with wildcard characters. For example, the following XML adds every .cs file in the directory to the CSFile item type, except the DoNotBuild.cs file.
<ItemGroup>
<CSFile Include="*.cs" Exclude="DoNotBuild.cs"/>
</ItemGroup>
The Exclude attribute only affects the items added by the Include attribute in the item element that contains them both. For example,
<Compile Include="*.cs" />
<Compile Include="*.res" Exclude="Form1.cs">
would not exclude the file Form1.cs, which was added in the preceding item element.
For more information, see How to: Exclude Files from the Build.
Using the Remove Attribute
Starting in the .NET Framework 3.5, Target elements may contain ItemGroup elements that may contain item elements. These item elements can contain the Remove attribute, which removes specific items (files) from the item type. For example, the following XML removes every .config file from the Compile item type.
<Target>
<ItemGroup>
<Compile Remove="*.config"/>
</ItemGroup>
</Target>
Item Metadata
Items may contain metadata in addition to the information gathered from the Include and Exclude attributes. This metadata can be used by tasks that require more information about the items, or to batch tasks and targets. For more information about batching, see MSBuild Batching.
Metadata is a collection of key-value pairs that are declared in the project file as child elements of an item element. The name of the child element is the name of the metadata, and the value of the child element is the value of the metadata.
The metadata is associated with the item element that contains it. For example, the following XML adds Culture metadata that has the value Fr to both the "one.cs" and the "two.cs" items of the CSFile item type.
<ItemGroup>
<CSFile Include="one.cs;two.cs">
<Culture>Fr</Culture>
</CSFile>
</ItemGroup>
An item can have zero or more metadata values. Metadata values can be changed at any time. Setting metadata to an empty value effectively removes it from the build.
Referencing Item Metadata in a Project File
Item metadata can be referenced throughout the project file by using the syntax %(ItemMetadataName). When ambiguity exists, this can be qualified by using the name of the item type, for example, %(ItemType.ItemMetaDataName).The following example uses the Display metadata to batch the Message task. For more information about how to use item metadata for batching, see Item Metadata in Task Batching.
<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
<ItemGroup>
<Stuff Include="One.cs" >
<Display>false</Display>
</Stuff>
<Stuff Include="Two.cs">
<Display>true</Display>
</Stuff>
</ItemGroup>
<Target Name="Batching">
<Message Text="@(Stuff)" Condition=" '%(Display)' == 'true' "/>
</Target>
</Project>
Well-known Item Metadata
When an item is added to an item type, that item is assigned some well-known metadata. For example, all items have the well-known metadata %(Filename) whose value is the file name of the item. For a list of well-known item metadata, see MSBuild Well-known Item Metadata.
Transforming Item Types Using Metadata
Item lists can be transformed into new item lists by using metadata. For example, an item type CppFiles that has items that represent .cpp files can be transformed into a corresponding list of .obj files by using the expression @(CppFiles -> '%(Filename).obj').
The following code creates a CultureResource item type that contains copies of all EmbeddedResource items with Culture metadata. The Culture metadata value becomes the value of the new metadata CultureResource.TargetDirectory.
<Target Name="ProcessCultureResources">
<ItemGroup>
<CultureResource Include="@(EmbeddedResource)"
Condition="'%(EmbeddedResource.Culture)' != ''">
<TargetDirectory>%(EmbeddedResource.Culture) </TargetDirectory>
</CultureResource>
</ItemGroup>
</Target>
For more information, see MSBuild Transforms.
Item Definitions
Starting in the .NET Framework 3.5, the ItemDefinitionGroup element lets you add default metadata to any item type. Like well-known metadata, the default metadata is associated with all items of the specified item type. Default metadata can be explicitly overridden in an item definition. For example, the following XML gives the Compile items "one.cs" and "three.cs" the metadata BuildDay with the value "Monday", and gives the item "two.cs" the metadata BuildDay with the value "Tuesday".
<ItemDefinitionGroup>
<Compile>
<BuildDay>Monday</BuildDay>
</Compile>
</ItemDefinitionGroup>
<ItemGroup>
<Compile Include="one.cs;three.cs" />
<Compile Include="two.cs">
<BuildDay>Tuesday</BuildDay>
</Compile>
</ItemGroup>
For more information, see Item Definitions.
See Also
Tasks
How to: Select the Files to Build
How to: Exclude Files from the Build
How to: Display an Item List Separated with Commas