MSBuild Items
Items represent inputs into the build system that are grouped into item collections based on their user-defined collection names. These item collections can be used as parameters for tasks, which use the individual items contained in the collection to perform the steps of the build process.
Creating Items in a Project File
Items are declared in the project file by creating an element as a child of an ItemGroup element with the name of the item. The Include attribute of the element specifies what files to include with that item collection. For example, the following code creates an item collection named Compile, which includes two files.
<ItemGroup>
<Compile Include = "file1.cs"/>
<Compile Include = "file2.cs"/>
</ItemGroup>
The following code creates the same item collection by declaring both files in one Include attribute, separated by a semicolon.
<ItemGroup>
<Compile Include = "file1.cs;file2.cs"/>
</ItemGroup>
Referencing Items in a Project File
You reference item collections throughout the project file with the syntax @(ItemCollectionName). For example, you would reference the item collection in the previous example with @(Compile). This syntax allows you to pass item collections to tasks by specifying the item collection as a parameter of that task. For more information, see How to: Use Wildcards to Build All Files in a Directory.
By default, items in item collections are separated by semicolons (;) when expanded. Use the syntax @(ItemCollectionName, 'separator') to specify a separator other than the default. For more information, see How to: Display an Item Collection 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: Use Wildcards to Build All Files in a Directory.
Using the Exclude Attribute
Items can also contain the Exclude attribute, which excludes specific files from the item collection. The Exclude attribute is useful when used in conjunction with wildcards. For example, the following code adds every .cs file in the directory except the DoNotBuild.cs file.
<ItemGroup>
<CSFile
Include="*.cs"
Exclude="DoNotBuild.cs"/>
</ItemGroup>
For more information, see How to: Build All Files in a Directory Except One.
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 items, or to batch tasks and targets. For more information on batching, see MSBuild Batching.
Item metadata is declared in the project file by creating an element with the name of the metadata as a child element of the item. An item can have zero or more metadata values. For example, the following element has Culture metadata with a value of Fr.
<ItemGroup>
<CSFile Include="main.cs">
<Culture>Fr</Culture>
</CSFile>
</ItemGroup>
Referencing Item Metadata in a Project File
You reference item metadata throughout the project file with the syntax %(ItemMetadataName). When ambiguity exists, this can be qualified by the name of the item collection, for example %(ItemCollectionName.ItemMetaDataName).The following example uses the Display metadata to batch the Message task. For more information on using item metadata for batching, see How to: Batch Tasks By Using Item Metadata.
<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
Whenever an item is added to an item collection, that item is created and assigned some well-known item metadata, such as %(Filename), which contains the file name of the item. For a complete list of well-known item metadata, see MSBuild Well-known Item Metadata.
Transforming Item Collections
Item collections can be transformed into new item collections. For example, an item collection of .cpp files can be transformed into a collection of .obj files using an expression like @(CppFiles -> '%(Filename).obj'). For more information, see MSBuild Transforms.
See Also
Tasks
How to: Use Wildcards to Build All Files in a Directory
How to: Build All Files in a Directory Except One