Item element (MSBuild)

Article
03/10/2023

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

Syntax

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

Specify metadata as attributes

In MSBuild 15.1 or later, any metadata with a name that doesn't conflict with the current list of attributes can optionally be expressed as an attribute.

For example, to specify a list of NuGet packages, you would normally use something like the following syntax.

<ItemGroup>
  <PackageReference Include="Newtonsoft.Json">
    <Version>9.0.1-beta1<Version>
  </PackageReference>
</ItemGroup>

Now, however, you can pass the Version metadata as an attribute, such as in the following syntax:

<ItemGroup>
  <PackageReference Include="Newtonsoft.Json" Version="9.0.1-beta1" />
</ItemGroup>

Attributes and elements

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

Attributes

Attribute	Description
`Include`	Optional 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.
`Condition`	Optional attribute. The condition to be evaluated. For more information, see Conditions.
`Remove`	Optional attribute. The file or wildcard to remove from the list of items.
`MatchOnMetadata`	Optional attribute. Modifies `Remove` attributes that reference other items to match on the specified metadata names instead of matching on the referenced items' values. This attribute is valid only if it's specified together with a `Remove` attribute that only contains references to other items (for example, `Remove="@(Compile);@(Content)"`). More details in Items.
`MatchOnMetadataOptions`	Optional attribute. Specifies the string matching strategy used by `MatchOnMetadata`. Possible values are `CaseSensitive`, `CaseInsensitive`, or `PathLike`. The default value is `CaseInsensitive`.
`KeepDuplicates`	Optional attribute. Specifies whether an item should be added to the target group if it's an exact duplicate of an existing item. If the source and target item have the same `Include` value but different metadata, the item is added even if `KeepDuplicates` is set to `false`. For more information, see Items. This attribute is valid only if it's specified for an item in an `ItemGroup` that's in a `Target`.
`KeepMetadata`	Optional attribute. The metadata for the source items to add to the target items. Only the metadata whose names are specified in the semicolon-delimited list are transferred from a source item to a target item. For more information, see Items. This attribute is valid only if it's specified for an item in an `ItemGroup` that's in a `Target`.
`RemoveMetadata`	Optional attribute. The metadata for the source items to not transfer to the target items. All metadata is transferred from a source item to a target item except metadata whose names are contained in the semicolon-delimited list of names. For more information, see Items. This attribute is valid only if it's specified for an item in an `ItemGroup` that's in a `Target`.
`Update`	Optional attribute. (Available only for .NET Core projects in Visual Studio 2017 or later.) Enables you to modify metadata of an item; typically used to override the default metadata of specific items after a group of items is initially specified (such as with a wildcard). This attribute is valid only if it's specified for an item in an `ItemGroup` that is not in a `Target`.

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 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 Items.

Examples

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

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

The following code example shows how to use the Update attribute to modify the metadata in a file called somefile.cs that was included via a glob. (Available only for .NET Core projects in Visual Studio 2017 or later.)

<ItemGroup>
    <Compile Update="somefile.cs">  // or Update="*.designer.cs"
        <MetadataKey>MetadataValue</MetadataKey>
    </Compile>
</ItemGroup>

Share via