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 .
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.
Using Wildcards to Specify Items
You can use the **, * and ? wildcards to specify a group of files as inputs for a build instead of listing each file separately. For example, to specify all the .cs files or .vb files in the same directory as the project file, use one of the following elements in your project file:
– or –
You can only use wildcards with items to specify the inputs for a build. For example, you cannot use wildcards to specify the inputs to the Sources parameter in the Csc task. MSBuild will accept wildcards as parameter values, but will treat them as string literals and not evaluate them. The following example would use the string literal *.cs as the Sources parameter value.
<Target Name="Compile"> <CSC Sources="*.cs" /> </Target>
For more information on wildcards, see.
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.
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.
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 .
<Project xmlns="http://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.
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.