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
+11-11Lines changed: 11 additions & 11 deletions
Original file line number
Diff line number
Diff line change
@@ -19,7 +19,7 @@ manager: douge
19
19
ms.workload:
20
20
- "multiple"
21
21
---
22
-
# Item Element (MSBuild)
22
+
# Item element (MSBuild)
23
23
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.
24
24
25
25
\<Project>
@@ -38,7 +38,7 @@ Contains a user-defined item and its metadata. Every item that is used in a [!IN
38
38
</Item>
39
39
```
40
40
41
-
## Specify metadata as Attributes
41
+
## Specify metadata as attributes
42
42
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.
43
43
44
44
For example, to specify a list of NuGet packages, you would normally use something like the following syntax.
@@ -59,7 +59,7 @@ Now, however, you can pass the `Version` metadata as an attribute, such as in th
59
59
</ItemGroup>
60
60
```
61
61
62
-
## Attributes and Elements
62
+
## Attributes and elements
63
63
The following sections describe attributes, child elements, and parent elements.
64
64
65
65
### Attributes
@@ -75,13 +75,13 @@ Now, however, you can pass the `Version` metadata as an attribute, such as in th
75
75
|`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`.|
76
76
|`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`.|
77
77
78
-
### Child Elements
78
+
### Child elements
79
79
80
80
|Element|Description|
81
81
|-------------|-----------------|
82
82
|[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.|
83
83
84
-
### Parent Elements
84
+
### Parent elements
85
85
86
86
|Element|Description|
87
87
|-------------|-----------------|
@@ -90,9 +90,9 @@ Now, however, you can pass the `Version` metadata as an attribute, such as in th
90
90
## Remarks
91
91
`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).
92
92
93
-
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*`')`.
93
+
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>').
94
94
95
-
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).
95
+
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).
96
96
97
97
## Examples
98
98
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`.
@@ -105,7 +105,7 @@ Now, however, you can pass the `Version` metadata as an attribute, such as in th
105
105
</CSFile>
106
106
</ItemGroup>
107
107
```
108
-
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.)
108
+
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.)
109
109
110
110
```xml
111
111
<ItemGroup>
@@ -116,7 +116,7 @@ The following code example shows how to use the `Update` attribute to modify the
Copy file name to clipboardExpand all lines: docs/msbuild/item-functions.md
+4-4Lines changed: 4 additions & 4 deletions
Original file line number
Diff line number
Diff line change
@@ -13,10 +13,10 @@ manager: douge
13
13
ms.workload:
14
14
- "multiple"
15
15
---
16
-
# Item Functions
16
+
# Item functions
17
17
Starting with MSBuild 4.0, code in tasks and targets can call item functions to get information about the items in the project. These functions simplify getting Distinct() items and are faster than looping through the items.
18
18
19
-
## String Item Functions
19
+
## String item functions
20
20
You can use string methods and properties in the .NET Framework to operate on any item value. For <xref:System.String> methods, specify the method name. For <xref:System.String> properties, specify the property name after "get_".
21
21
22
22
For items that have multiple strings, the string method or property runs on each string.
@@ -44,7 +44,7 @@ Starting with MSBuild 4.0, code in tasks and targets can call item functions to
44
44
-->
45
45
```
46
46
47
-
## Intrinsic Item Functions
47
+
## Intrinsic item functions
48
48
The table below lists the intrinsic functions available for items.
49
49
50
50
|Function|Example|Description|
@@ -95,5 +95,5 @@ Starting with MSBuild 4.0, code in tasks and targets can call item functions to
Copy file name to clipboardExpand all lines: docs/msbuild/item-metadata-in-target-batching.md
+7-7Lines changed: 7 additions & 7 deletions
Original file line number
Diff line number
Diff line change
@@ -15,12 +15,12 @@ manager: douge
15
15
ms.workload:
16
16
- "multiple"
17
17
---
18
-
# Item Metadata in Target Batching
19
-
[!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)] has the ability to perform dependency analysis on the inputs and outputs of a build target. If it is determined that the inputs or outputs of the target are up-to-date, the target will be skipped and the build will procede. `Target` elements use the `Inputs` and `Outputs` attributes to specify the items to inspect during dependency analysis.
18
+
# Item metadata in target batching
19
+
[!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)] has the ability to perform dependency analysis on the inputs and outputs of a build target. If it is determined that the inputs or outputs of the target are up-to-date, the target will be skipped and the build will proceed. `Target` elements use the `Inputs` and `Outputs` attributes to specify the items to inspect during dependency analysis.
20
20
21
21
If a target contains a task that uses batched items as inputs or outputs, the `Target` element of the target should use batching in its `Inputs` or `Outputs` attributes to enable [!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)] to skip batches of items that are already up-to-date.
22
22
23
-
## Batching Targets
23
+
## Batch targets
24
24
The following example contains an item list named `Res` that is divided into two batches based on the `Culture` item metadata. Each of these batches is passed into the `AL` task, which creates an output assembly for each batch. By using batching on the `Outputs` attribute of the `Target` element, [!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)] can determine if each of the individual batches is up-to-date before running the target. Without using target batching, both batches of items would be run by the task every time the target was executed.
25
25
26
26
```xml
@@ -61,8 +61,8 @@ ms.workload:
61
61
</Project>
62
62
```
63
63
64
-
## See Also
65
-
[How to: Build Incrementally](../msbuild/how-to-build-incrementally.md)
64
+
## See also
65
+
[How to: Build incrementally](../msbuild/how-to-build-incrementally.md)
66
66
[Batching](../msbuild/msbuild-batching.md)
67
-
[Target Element (MSBuild)](../msbuild/target-element-msbuild.md)
68
-
[Item Metadata in Task Batching](../msbuild/item-metadata-in-task-batching.md)
67
+
[Target element (MSBuild)](../msbuild/target-element-msbuild.md)
68
+
[Item metadata in task batching](../msbuild/item-metadata-in-task-batching.md)
Copy file name to clipboardExpand all lines: docs/msbuild/item-metadata-in-task-batching.md
+21-21Lines changed: 21 additions & 21 deletions
Original file line number
Diff line number
Diff line change
@@ -16,7 +16,7 @@ manager: douge
16
16
ms.workload:
17
17
- "multiple"
18
18
---
19
-
# Item Metadata in Task Batching
19
+
# Item metadata in task batching
20
20
[!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)] has the ability to divide item lists into different categories, or batches, based on item metadata, and run a task one time with each batch. It can be confusing to understand exactly what items are being passed with which batch. This topic covers the following common scenarios that involve batching.
21
21
22
22
- Dividing an item list into batches
@@ -26,10 +26,10 @@ ms.workload:
26
26
- Batching one item at a time
27
27
28
28
- Filtering item lists
29
+
30
+
For more information on batching with [!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)], see [Batching](../msbuild/msbuild-batching.md).
29
31
30
-
For more information on batching with [!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)], see [Batching](../msbuild/msbuild-batching.md).
31
-
32
-
## Dividing an Item list into Batches
32
+
## Divide an item list into batches
33
33
Batching allows you to divide an item list into different batches based on item metadata, and pass each of the batches into a task separately. This is useful for building satellite assemblies.
34
34
35
35
The following example shows how to divide an item list into batches based on item metadata. The `ExampColl` item list is divided into three batches based on the `Number` item metadata. The presence of `%(ExampColl.Number)`in the `Text` attribute notifies [!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)] that batching should be performed. The `ExampColl` item list is divided into three batches based on the `Number` metadata, and each batch is passed separately into the task.
@@ -66,22 +66,22 @@ ms.workload:
66
66
67
67
</Project>
68
68
```
69
-
70
-
The [Message Task](../msbuild/message-task.md) task displays the following information:
69
+
70
+
The [Message task](../msbuild/message-task.md) displays the following information:
71
71
72
72
`Number: 1 -- Items in ExampColl: Item1;Item4`
73
73
74
74
`Number: 2 -- Items in ExampColl: Item2;Item5`
75
75
76
76
`Number: 3 -- Items in ExampColl: Item3;Item6`
77
77
78
-
## Dividing Several Item lists into Batches
79
-
[!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)] can divide multiple item lists into batches based on the same metadata. This makes it easy to divide different item lists into batches to build multiple assemblies. For example, you could have an item list of .cs files divided into an application batch and an assembly batch, and an item list of resource files divided into an application batch and an assembly batch. You could then use batching to pass these item lists into one task and build both the application and the assembly.
78
+
## Divide several item lists into batches
79
+
[!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)] can divide multiple item lists into batches based on the same metadata. This makes it easy to divide different item lists into batches to build multiple assemblies. For example, you could have an item list of *.cs* files divided into an application batch and an assembly batch, and an item list of resource files divided into an application batch and an assembly batch. You could then use batching to pass these item lists into one task and build both the application and the assembly.
80
80
81
81
> [!NOTE]
82
82
> If an item list being passed into a task contains no items with the referenced metadata, every item in that item list is passed into every batch.
83
83
84
-
The following example shows how to divide multiple item list into batches based on item metadata. The `ExampColl` and `ExampColl2` item lists are each divided into three batches based on the `Number` item metadata. The presence of `%(Number)`in the `Text` attribute notifies [!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)] that batching should be performed. The `ExampColl` and `ExampColl2` item lists are divided into three batches based on the `Number` metadata, and each batch is passed separately into the task.
84
+
The following example shows how to divide multiple item list into batches based on item metadata. The `ExampColl` and `ExampColl2` item lists are each divided into three batches based on the `Number` item metadata. The presence of `%(Number)`in the `Text` attribute notifies [!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)] that batching should be performed. The `ExampColl` and `ExampColl2` item lists are divided into three batches based on the `Number` metadata, and each batch is passed separately into the task.
85
85
86
86
```xml
87
87
<Project
@@ -119,16 +119,16 @@ ms.workload:
119
119
</Project>
120
120
```
121
121
122
-
The [Message Task](../msbuild/message-task.md) task displays the following information:
122
+
The [Message task](../msbuild/message-task.md) displays the following information:
123
123
124
124
`Number: 1 -- Items in ExampColl: Item1 ExampColl2: Item4`
125
125
126
126
`Number: 2 -- Items in ExampColl: Item2 ExampColl2: Item5`
127
127
128
128
`Number: 3 -- Items in ExampColl: Item3 ExampColl2: Item6`
129
129
130
-
## Batching One Item at a Time
131
-
Batching can also be performed on well-known item metadata that is assigned to every item upon creation. This guarantees that every item in a collection will have some metadata to use for batching. The `Identity` metadata value is unique for every item, and is useful for dividing every item in an item list into a separate batch. For a complete list of well-known item metadata, see [Well-known Item Metadata](../msbuild/msbuild-well-known-item-metadata.md).
130
+
## Batching one item at a time
131
+
Batching can also be performed on well-known item metadata that is assigned to every item upon creation. This guarantees that every item in a collection will have some metadata to use for batching. The `Identity` metadata value is unique for every item, and is useful for dividing every item in an item list into a separate batch. For a complete list of well-known item metadata, see [Well-known item metadata](../msbuild/msbuild-well-known-item-metadata.md).
132
132
133
133
The following example shows how to batch each item in an item list one at a time. Because the `Identity` metadata value of every item is unique, the `ExampColl` item list is divided into six batches, each batch containing one item of the item list. The presence of `%(Identity)`in the `Text` attribute notifies [!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)] that batching should be performed.
134
134
@@ -155,7 +155,7 @@ ms.workload:
155
155
</Project>
156
156
```
157
157
158
-
The [Message Task](../msbuild/message-task.md) task displays the following information:
158
+
The [Message task](../msbuild/message-task.md) displays the following information:
Batching can be used to filter out certain items from an item list before passing it to a task. For example, filtering on the `Extension` well-known item metadata value allows you to run a task on only files with a specific extension.
171
171
172
172
The following example shows how to divide an item list into batches based on item metadata, and then filter those batches when they are passed into a task. The `ExampColl` item list is divided into three batches based on the `Number` item metadata. The `Condition` attribute of the task specifies that only batches with a `Number` item metadata value of `2` will be passed into the task
0 commit comments