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/msbuild-items.md
+39-71Lines changed: 39 additions & 71 deletions
Original file line number
Diff line number
Diff line change
@@ -13,44 +13,12 @@ manager: douge
13
13
ms.workload:
14
14
- "multiple"
15
15
---
16
-
# MSBuild Items
16
+
# MSBuild items
17
17
MSBuild items are inputs into the build system, and they typically represent files. Items are grouped into item types based on their element names. Item types are named lists of items that can be used as parameters for tasks. The tasks use the item values to perform the steps of the build process.
18
18
19
19
Because items are named by the item type to which they belong, the terms "item" and "item value" can be used interchangeably.
20
20
21
-
**In this topic**
22
-
23
-
-[Creating Items in a Project File](#BKMK_Creating1)
24
-
25
-
-[Creating Items During Execution](#BKMK_Creating2)
26
-
27
-
-[Referencing Items in a Project File](#BKMK_ReferencingItems)
28
-
29
-
-[Using Wildcards to Specify Items](#BKMK_Wildcards)
30
-
31
-
-[Using the Exclude Attribute](#BKMK_ExcludeAttribute)
32
-
33
-
-[Item Metadata](#BKMK_ItemMetadata)
34
-
35
-
-[Referencing Item Metadata in a Project File](#BKMK_ReferencingItemMetadata)
-[Transforming Item Types By Using Metadata](#BKMK_Transforming)
40
-
41
-
-[Item Definitions](#BKMK_ItemDefinitions)
42
-
43
-
-[Attributes for Items in an ItemGroup of a Target](#BKMK_AttributesWithinTargets)
44
-
45
-
-[Remove Attribute](#BKMK_RemoveAttribute)
46
-
47
-
-[KeepMetadata Attribute](#BKMK_KeepMetadata)
48
-
49
-
-[RemoveMetadata Attribute](#BKMK_RemoveMetadata)
50
-
51
-
-[KeepDuplicates Attribute](#BKMK_KeepDuplicates)
52
-
53
-
## <aname="BKMK_Creating1"></a> Creating Items in a Project File
21
+
## Create items in a project file
54
22
You declare items in the project file as child elements of an [ItemGroup](../msbuild/itemgroup-element-msbuild.md) element. The name of the child element is the type of the item. The `Include` attribute of the element specifies the items (files) to be included with that item type. For example, the following XML creates an item type that's named `Compile`, which includes two files.
55
23
56
24
```xml
@@ -60,7 +28,7 @@ MSBuild items are inputs into the build system, and they typically represent fil
60
28
</ItemGroup>
61
29
```
62
30
63
-
The item "file2.cs" doesn't replace the item "file1.cs"; instead, the file name is appended to the list of values for the `Compile` item type. You can't remove an item from an item type during the evaluation phase of a build.
31
+
The item *file2.cs* doesn't replace the item *file1.cs*; instead, the file name is appended to the list of values for the `Compile` item type. You can't remove an item from an item type during the evaluation phase of a build.
64
32
65
33
The following XML creates the same item type by declaring both files in one `Include` attribute. Notice that the file names are separated by a semicolon.
66
34
@@ -70,7 +38,7 @@ MSBuild items are inputs into the build system, and they typically represent fil
70
38
</ItemGroup>
71
39
```
72
40
73
-
## <aname="BKMK_Creating2"></a> Creating Items During Execution
41
+
## Create items during execution
74
42
Items that are outside [Target](../msbuild/target-element-msbuild.md) elements are assigned values during the evaluation phase of a build. During the subsequent execution phase, items can be created or modified in the following ways:
75
43
76
44
- Any task can emit an item. To emit an item, the [Task](../msbuild/task-element-msbuild.md) element must have a child [Output](../msbuild/output-element-msbuild.md) element that has an `ItemName` attribute.
@@ -79,12 +47,12 @@ MSBuild items are inputs into the build system, and they typically represent fil
79
47
80
48
- Starting in the .NET Framework 3.5, `Target` elements may contain [ItemGroup](../msbuild/itemgroup-element-msbuild.md) elements that may contain item elements.
81
49
82
-
## <aname="BKMK_ReferencingItems"></a> Referencing Items in a Project File
83
-
To reference item types throughout the project file, you use the syntax @(`ItemType`). For example, you would reference the item type in the previous example by using `@(Compile)`. By using this syntax, you can pass items to tasks by specifying the item type as a parameter of that task. For more information, see [How to: Select the Files to Build](../msbuild/how-to-select-the-files-to-build.md).
50
+
## Reference items in a project file
51
+
To reference item types throughout the project file, you use the syntax @(\<ItemType>). For example, you would reference the item type in the previous example by using `@(Compile)`. By using this syntax, you can pass items to tasks by specifying the item type as a parameter of that task. For more information, see [How to: Select the files to build](../msbuild/how-to-select-the-files-to-build.md).
84
52
85
-
By default, the items of an item type are separated by semicolons (;) when it's expanded. You can use the syntax @(*ItemType*, '*separator*') to specify a separator other than the default. For more information, see [How to: Display an Item List Separated with Commas](../msbuild/how-to-display-an-item-list-separated-with-commas.md).
53
+
By default, the items of an item type are separated by semicolons (;) when it's expanded. You can use the syntax @(\<ItemType>, '\<separator>') to specify a separator other than the default. For more information, see [How to: Display an item list separated with commas](../msbuild/how-to-display-an-item-list-separated-with-commas.md).
86
54
87
-
## <aname="BKMK_Wildcards"></a> Using Wildcards to Specify Items
55
+
## Use wildcards to specify items
88
56
You can use the **, \*, and ? wildcard characters to specify a group of files as inputs for a build instead of listing each file separately.
89
57
90
58
- The ? wildcard character matches a single character.
@@ -93,44 +61,44 @@ MSBuild items are inputs into the build system, and they typically represent fil
93
61
94
62
- The ** wildcard character sequence matches a partial path.
95
63
96
-
For example, you can specify all the .cs files in the directory that contains the project file by using the following element in your project file.
64
+
For example, you can specify all the *.cs* files in the directory that contains the project file by using the following element in your project file.
97
65
98
66
```xml
99
67
<CSFileInclude="*.cs"/>
100
68
```
101
69
102
-
The following element selects all .vb files on the D: drive:
70
+
The following element selects all *.vb* files on the *D:* drive:
103
71
104
72
```xml
105
73
<VBFileInclude="D:/**/*.vb"/>
106
74
```
107
75
108
-
For more information about wildcard characters, see [How to: Select the Files to Build](../msbuild/how-to-select-the-files-to-build.md).
76
+
For more information about wildcard characters, see [How to: Select the files to build](../msbuild/how-to-select-the-files-to-build.md).
109
77
110
-
## <aname="BKMK_ExcludeAttribute"></a> Using the Exclude Attribute
111
-
Item elements can contain the `Exclude` attribute, which excludes specific items (files) from the item type. The `Exclude` attribute is typically used together with wildcard characters. For example, the following XML adds every .cs file in the directory to the CSFile item type, except the `DoNotBuild.cs` file.
78
+
## Use the Exclude attribute
79
+
Item elements can contain the `Exclude` attribute, which excludes specific items (files) from the item type. The `Exclude` attribute is typically used together with wildcard characters. For example, the following XML adds every *.cs* file in the directory to the CSFile item type, except the *DoNotBuild.cs* file.
112
80
113
81
```xml
114
82
<ItemGroup>
115
83
<CSFileInclude="*.cs"Exclude="DoNotBuild.cs"/>
116
84
</ItemGroup>
117
85
```
118
86
119
-
The `Exclude` attribute affects only the items that are added by the `Include` attribute in the item element that contains them both. The following example wouldn't exclude the file Form1.cs, which was added in the preceding item element.
87
+
The `Exclude` attribute affects only the items that are added by the `Include` attribute in the item element that contains them both. The following example wouldn't exclude the file *Form1.cs*, which was added in the preceding item element.
120
88
121
89
```xml
122
90
<CompileInclude="*.cs" />
123
91
<CompileInclude="*.res"Exclude="Form1.cs">
124
92
```
125
93
126
-
For more information, see [How to: Exclude Files from the Build](../msbuild/how-to-exclude-files-from-the-build.md).
94
+
For more information, see [How to: Exclude files from the build](../msbuild/how-to-exclude-files-from-the-build.md).
127
95
128
-
## <aname="BKMK_ItemMetadata"></a> Item Metadata
96
+
## Item metadata
129
97
Items may contain metadata in addition to the information in the `Include` and `Exclude` attributes. This metadata can be used by tasks that require more information about the items or to batch tasks and targets. For more information, see [Batching](../msbuild/msbuild-batching.md).
130
98
131
99
Metadata is a collection of key-value pairs that are declared in the project file as child elements of an item element. The name of the child element is the name of the metadata, and the value of the child element is the value of the metadata.
132
100
133
-
The metadata is associated with the item element that contains it. For example, the following XML adds `Culture` metadata that has the value `Fr` to both the "one.cs" and the "two.cs" items of the CSFile item type.
101
+
The metadata is associated with the item element that contains it. For example, the following XML adds `Culture` metadata that has the value `Fr` to both the *one.cs* and the *two.cs* items of the CSFile item type.
134
102
135
103
```xml
136
104
<ItemGroup>
@@ -142,8 +110,8 @@ MSBuild items are inputs into the build system, and they typically represent fil
142
110
143
111
An item can have zero or more metadata values. You can change metadata values at any time. If you set metadata to an empty value, you effectively remove it from the build.
144
112
145
-
### <aname="BKMK_ReferencingItemMetadata"></a> Referencing Item Metadata in a Project File
146
-
You can reference item metadata throughout the project file by using the syntax %(`ItemMetadataName`). If ambiguity exists, you can qualify a reference by using the name of the item type. For example, you can specify %(*ItemType.ItemMetaDataName*).The following example uses the Display metadata to batch the Message task. For more information about how to use item metadata for batching, see [Item Metadata in Task Batching](../msbuild/item-metadata-in-task-batching.md).
113
+
### <aname="BKMK_ReferencingItemMetadata"></a> Reference item metadata in a project file
114
+
You can reference item metadata throughout the project file by using the syntax %(\<ItemMetadataName>). If ambiguity exists, you can qualify a reference by using the name of the item type. For example, you can specify %(\<ItemType.ItemMetaDataName>).The following example uses the Display metadata to batch the Message task. For more information about how to use item metadata for batching, see [Item metadata in task batching](../msbuild/item-metadata-in-task-batching.md).
When an item is added to an item type, that item is assigned some well-known metadata. For example, all items have the well-known metadata `%(Filename)`, whose value is the file name of the item. For more information, see [Well-known Item Metadata](../msbuild/msbuild-well-known-item-metadata.md).
When an item is added to an item type, that item is assigned some well-known metadata. For example, all items have the well-known metadata %(\<Filename>), whose value is the file name of the item. For more information, see [Well-known item metadata](../msbuild/msbuild-well-known-item-metadata.md).
166
134
167
-
### <aname="BKMK_Transforming"></a> Transforming Item Types By Using Metadata
168
-
You can transform item lists into new item lists by using metadata. For example, you can transform an item type `CppFiles` that has items that represent .cpp files into a corresponding list of .obj files by using the expression `@(CppFiles -> '%(Filename).obj')`.
135
+
### <aname="BKMK_Transforming"></a> Transform item types by using metadata
136
+
You can transform item lists into new item lists by using metadata. For example, you can transform an item type `CppFiles` that has items that represent *.cpp* files into a corresponding list of *.obj* files by using the expression `@(CppFiles -> '%(Filename).obj')`.
169
137
170
138
The following code creates a `CultureResource` item type that contains copies of all `EmbeddedResource` items with `Culture` metadata. The `Culture` metadata value becomes the value of the new metadata `CultureResource.TargetDirectory`.
171
139
@@ -182,8 +150,8 @@ MSBuild items are inputs into the build system, and they typically represent fil
182
150
183
151
For more information, see [Transforms](../msbuild/msbuild-transforms.md).
Starting in the .NET Framework 3.5, you can add default metadata to any item type by using the [ItemDefinitionGroup element](../msbuild/itemdefinitiongroup-element-msbuild.md). Like well-known metadata, the default metadata is associated with all items of the item type that you specify. You can explicitly override default metadata in an item definition. For example, the following XML gives the `Compile` items "one.cs" and "three.cs" the metadata `BuildDay` with the value "Monday". The code gives the item "two.cs" the metadata `BuildDay` with the value "Tuesday".
153
+
## Item definitions
154
+
Starting in the .NET Framework 3.5, you can add default metadata to any item type by using the [ItemDefinitionGroup element](../msbuild/itemdefinitiongroup-element-msbuild.md). Like well-known metadata, the default metadata is associated with all items of the item type that you specify. You can explicitly override default metadata in an item definition. For example, the following XML gives the `Compile` items *one.cs* and *three.cs* the metadata `BuildDay` with the value "Monday". The code gives the item *two.cs* the metadata `BuildDay` with the value "Tuesday".
187
155
188
156
```xml
189
157
<ItemDefinitionGroup>
@@ -199,15 +167,15 @@ MSBuild items are inputs into the build system, and they typically represent fil
199
167
</ItemGroup>
200
168
```
201
169
202
-
For more information, see [Item Definitions](../msbuild/item-definitions.md).
170
+
For more information, see [Item definitions](../msbuild/item-definitions.md).
203
171
204
-
## <aname="BKMK_AttributesWithinTargets"></a> Attributes for Items in an ItemGroup of a Target
172
+
## Attributes for items in an ItemGroup of a Target
205
173
Starting in the .NET Framework 3.5, `Target` elements may contain [ItemGroup](../msbuild/itemgroup-element-msbuild.md) elements that may contain item elements. The attributes in this section are valid when they are specified for an item in an `ItemGroup` that's in a `Target`.
Items in an `ItemGroup` of a target may contain the `Remove` attribute, which removes specific items (files) from the item type. This attribute was introduced in the .NET Framework 3.5.
209
177
210
-
The following example removes every .config file from the Compile item type.
178
+
The following example removes every *.config* file from the Compile item type.
211
179
212
180
```xml
213
181
<Target>
@@ -217,7 +185,7 @@ MSBuild items are inputs into the build system, and they typically represent fil
If an item is generated within a target, the item element can contain the `KeepMetadata` attribute. If this attribute is specified, only the metadata that is specified in the semicolon-delimited list of names will be transferred from the source item to the target item. An empty value for this attribute is equivalent to not specifying it. The `KeepMetadata` attribute was introduced in the .NET Framework 4.5.
222
190
223
191
The following example illustrates how to use the `KeepMetadata` attribute.
If an item is generated within a target, the item element can contain the `RemoveMetadata` attribute. If this attribute is specified, all metadata is transferred from the source item to the target item except metadata whose names are contained in the semicolon-delimited list of names. An empty value for this attribute is equivalent to not specifying it. The `RemoveMetadata` attribute was introduced in the .NET Framework 4.5.
264
232
265
233
The following example illustrates how to use the `RemoveMetadata` attribute.
If an item is generated within a target, the item element can contain the `KeepDuplicates` attribute. `KeepDuplicates` is a `Boolean` attribute that specifies whether an item should be added to the target group if the item is an exact duplicate of an existing item.
313
281
314
282
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`. An empty value for this attribute is equivalent to not specifying it. The `KeepDuplicates` attribute was introduced in the .NET Framework 4.5.
0 commit comments