You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/msbuild/item-element-msbuild.md
+61-62Lines changed: 61 additions & 62 deletions
Original file line number
Diff line number
Diff line change
@@ -2,39 +2,39 @@
2
2
title: "Item Element (MSBuild) | Microsoft Docs"
3
3
ms.date: "03/13/2017"
4
4
ms.topic: "reference"
5
-
dev_langs:
5
+
dev_langs:
6
6
- "VB"
7
7
- "CSharp"
8
8
- "C++"
9
9
- "jsharp"
10
-
helpviewer_keywords:
10
+
helpviewer_keywords:
11
11
- "Item Element [MSBuild]"
12
12
- "<Item> Element [MSBuild]"
13
13
ms.assetid: dcef5f91-0613-4bfc-8ee9-d7004bb6d3a9
14
14
author: mikejo5000
15
15
ms.author: mikejo
16
16
manager: jillfra
17
-
ms.workload:
17
+
ms.workload:
18
18
- "multiple"
19
19
---
20
20
# Item element (MSBuild)
21
-
Contains a user-defined item and its metadata. Every item that is used in a [!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)] project must be specified as a child of an `ItemGroup` element.
21
+
Contains a user-defined item and its metadata. Every item that is used in a [!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)] project must be specified as a child of an `ItemGroup` element.
22
22
23
-
\<Project>
24
-
\<ItemGroup>
25
-
\<Item>
23
+
\<Project>
24
+
\<ItemGroup>
25
+
\<Item>
26
26
27
-
## Syntax
27
+
## Syntax
28
28
29
-
```xml
30
-
<ItemInclude="*.cs"
31
-
Exclude="MyFile.cs"
32
-
Remove="RemoveFile.cs"
33
-
Condition="'String A'=='String B'" >
34
-
<ItemMetadata1>...</ItemMetadata1>
35
-
<ItemMetadata2>...</ItemMetadata2>
36
-
</Item>
37
-
```
29
+
```xml
30
+
<ItemInclude="*.cs"
31
+
Exclude="MyFile.cs"
32
+
Remove="RemoveFile.cs"
33
+
Condition="'String A'=='String B'" >
34
+
<ItemMetadata1>...</ItemMetadata1>
35
+
<ItemMetadata2>...</ItemMetadata2>
36
+
</Item>
37
+
```
38
38
39
39
## Specify metadata as attributes
40
40
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.
@@ -53,69 +53,68 @@ Now, however, you can pass the `Version` metadata as an attribute, such as in th
The following sections describe attributes, child elements, and parent elements.
60
+
## Attributes and elements
61
+
The following sections describe attributes, child elements, and parent elements.
62
62
63
-
### Attributes
63
+
### Attributes
64
64
65
-
|Attribute|Description|
66
-
|---------------|-----------------|
67
-
|`Include`|Optional attribute.<br /><br /> The file or wildcard to include in the list of items.|
68
-
|`Exclude`|Optional attribute.<br /><br /> The file or wildcard to exclude from the list of items.|
69
-
|`Condition`|Optional attribute.<br /><br /> The condition to be evaluated. For more information, see [Conditions](../msbuild/msbuild-conditions.md).|
70
-
|`Remove`|Optional attribute.<br /><br /> The file or wildcard to remove from the list of items.<br /><br />|
71
-
|`KeepDuplicates`|Optional attribute.<br /><br /> 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](../msbuild/msbuild-items.md).<br /><br /> This attribute is valid only if it's specified for an item in an `ItemGroup` that's in a `Target`.|
72
-
|`KeepMetadata`|Optional attribute.<br /><br /> 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](../msbuild/msbuild-items.md).<br /><br /> This attribute is valid only if it's specified for an item in an `ItemGroup` that's in a `Target`.|
73
-
|`RemoveMetadata`|Optional attribute.<br /><br /> 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](../msbuild/msbuild-items.md).<br /><br /> This attribute is valid only if it's specified for an item in an `ItemGroup` that's in a `Target`.|
74
-
|`Update`|Optional attribute. (Available only for .NET Core projects in Visual Studio 2017 or later.)<br /><br /> Enables you to modify metadata of a file that was included by using a glob.<br /><br /> This attribute is valid only if it's specified for an item in an `ItemGroup` that is not in a `Target`.|
65
+
|Attribute|Description|
66
+
|---------------|-----------------|
67
+
|`Include`|Optional attribute.<br /><br /> The file or wildcard to include in the list of items.|
68
+
|`Exclude`|Optional attribute.<br /><br /> The file or wildcard to exclude from the list of items.|
69
+
|`Condition`|Optional attribute.<br /><br /> The condition to be evaluated. For more information, see [Conditions](../msbuild/msbuild-conditions.md).|
70
+
|`Remove`|Optional attribute.<br /><br /> The file or wildcard to remove from the list of items.<br /><br />|
71
+
|`KeepDuplicates`|Optional attribute.<br /><br /> 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](../msbuild/msbuild-items.md).<br /><br /> This attribute is valid only if it's specified for an item in an `ItemGroup` that's in a `Target`.|
72
+
|`KeepMetadata`|Optional attribute.<br /><br /> 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](../msbuild/msbuild-items.md).<br /><br /> This attribute is valid only if it's specified for an item in an `ItemGroup` that's in a `Target`.|
73
+
|`RemoveMetadata`|Optional attribute.<br /><br /> 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](../msbuild/msbuild-items.md).<br /><br /> This attribute is valid only if it's specified for an item in an `ItemGroup` that's in a `Target`.|
74
+
|`Update`|Optional attribute. (Available only for .NET Core projects in Visual Studio 2017 or later.)<br /><br /> Enables you to modify metadata of a file that was included by using a glob.<br /><br /> This attribute is valid only if it's specified for an item in an `ItemGroup` that is not in a `Target`.|
75
75
76
-
### Child elements
76
+
### Child elements
77
77
78
-
|Element|Description|
79
-
|-------------|-----------------|
80
-
|[ItemMetadata](../msbuild/itemmetadata-element-msbuild.md)|A user-defined item metadata key, which contains the item metadata value. There may be zero or more `ItemMetadata` elements in an item.|
78
+
|Element|Description|
79
+
|-------------|-----------------|
80
+
|[ItemMetadata](../msbuild/itemmetadata-element-msbuild.md)|A user-defined item metadata key, which contains the item metadata value. There may be zero or more `ItemMetadata` elements in an item.|
81
81
82
-
### Parent elements
82
+
### Parent elements
83
83
84
-
|Element|Description|
85
-
|-------------|-----------------|
86
-
|[ItemGroup](../msbuild/itemgroup-element-msbuild.md)|Grouping element for items.|
84
+
|Element|Description|
85
+
|-------------|-----------------|
86
+
|[ItemGroup](../msbuild/itemgroup-element-msbuild.md)|Grouping element for items.|
87
87
88
-
## Remarks
89
-
`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](../msbuild/msbuild-tasks.md), which use the individual items in the collections to perform the steps of the build process. For more information, see [Items](../msbuild/msbuild-items.md).
88
+
## Remarks
89
+
`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](../msbuild/msbuild-tasks.md), which use the individual items in the collections to perform the steps of the build process. For more information, see [Items](../msbuild/msbuild-items.md).
90
90
91
-
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 <xref:Microsoft.Build.Framework.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>').
91
+
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 <xref:Microsoft.Build.Framework.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>').
92
92
93
-
The [!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)] engine can evaluate wildcards such as `*` and `?` and recursive wildcards such as */\*\*/\*.cs*. For more information, see [Items](../msbuild/msbuild-items.md).
93
+
The [!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)] engine can evaluate wildcards such as `*` and `?` and recursive wildcards such as */\*\*/\*.cs*. For more information, see [Items](../msbuild/msbuild-items.md).
94
94
95
-
## Examples
96
-
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`.
95
+
## Examples
96
+
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`.
97
97
98
-
```xml
99
-
<ItemGroup>
100
-
<CSFileInclude="engine.cs; form.cs" />
101
-
<CSFileInclude="main.cs" >
102
-
<MyMetadata>HelloWorld</MyMetadata>
103
-
</CSFile>
104
-
</ItemGroup>
105
-
```
98
+
```xml
99
+
<ItemGroup>
100
+
<CSFileInclude="engine.cs; form.cs" />
101
+
<CSFileInclude="main.cs" >
102
+
<MyMetadata>HelloWorld</MyMetadata>
103
+
</CSFile>
104
+
</ItemGroup>
105
+
```
106
106
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.)
107
107
108
-
```xml
108
+
```xml
109
109
<ItemGroup>
110
110
<CompileUpdate="somefile.cs"> // or Update="*.designer.cs"
0 commit comments