Item Element (MSBuild)

Article
02/04/2013

Contains a user-defined item and its metadata. Every item that is used in a MSBuild project must be specified as a child of an ItemGroup element.

<Item Include="*.cs"
        Exclude="MyFile.cs"
        Remove="RemoveFile.cs"
        Condition="'String A'=='String B'" >
    <ItemMetadata1>...</ItemMetadata1>
    <ItemMetadata2>...</ItemMetadata2>
</Item>

Attributes and Elements

The following sections describe attributes, child elements, and parent elements.

Attributes

Attribute	Description
Include	Required attribute. The file or wildcard to include in the list of items.
Exclude	Optional attribute. The file or wildcard to exclude from the list of items.
Remove	Optional attribute. The file or wildcard to remove from the list of items. This attribute is only valid when it is specified for an item in an ItemGroup in of a Target.
Condition	Optional attribute. The condition to be evaluated. For more information, see MSBuild Conditions.

Child Elements

Element	Description
ItemMetadata	A user-defined item metadata key, which contains the item metadata value. There may be zero or more ItemMetadata elements in an item.

Parent Elements

Element	Description
ItemGroup	Grouping element for items.

Remarks

Item elements define inputs into the build system, and 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 in the collections to perform the steps of the build process. For more information, see MSBuild Items.

Using the notation @(myType) enables a collection of items of type myType to be expanded into a semicolon-delimited list of strings, and passed to a parameter. If the parameter is of type string, then the value of the parameter is the list of elements, separated by semicolons. If the parameter is an array of strings (string[]), then each element is inserted into the array based on the location of the semicolons. If the task parameter is of type ITaskItem[], then the value is the contents of the item collection together with any metadata attached. To delimit each item by using a character other than a semicolon, use the syntax @(myType, 'separator').

The MSBuild engine can evaluate wildcards such as * and ? and recursive wildcards such as /**/*.cs. For more information, see MSBuild Items.

Example

The following code example shows how to declare two items of type CSFile. The second declared item contains metadata that has myAttribute set to HelloWorld.

<ItemGroup>
    <CSFile Include="engine.cs; form.cs" />
    <CSFile Include="main.cs" >
        <MyMetadata>HelloWorld</MyMetadata>
    </CSFile>
</ItemGroup>