MSBuild 项

项目
08/12/2011

项是生成系统的输入，通常表示文件。项根据其元素名称编组到各种项类型中。项类型是项的命名列表，可以用作任务的参数。任务使用项值来执行生成过程的步骤。

因为项按其所属的项类型进行命名，所以术语“项”和“项值”可以交换使用。

在项目文件中创建项

在项目文件中，项声明为 ItemGroup 元素的子元素。子元素的名称为项的类型。元素的 Include 特性指定该项类型中要包括的项（文件）。例如，下面的 XML 创建一个名为 Compile 的项类型，其中包括两个文件。

</ItemGroup>

项“file2.cs”不替换项“file1.cs”，而是追加到 Compile 项类型的值列表。在生成的计算阶段，不能从项类型中移除项。

下面的 XML 在一个 Include 特性中同时声明两个文件，以此创建与上例相同的项类型。请注意，文件名之间用分号分隔。

</ItemGroup>

在执行过程中创建项

如果项位于 Target 元素之外，则在生成的计算阶段为其赋值。在随后的执行阶段中，可以如下创建或修改项：

项可以由任何任务发出。若要发出项，Task 元素必须有具备 ItemName 特性的 Output 子元素。
项可以由 CreateItem 任务发出。此用法已弃用。
从 .NET Framework 3.5 开始，Target 元素可以包含 ItemGroup 元素，后者可以包含项元素。

在项目文件中引用项

在整个项目文件中，可以使用语法 @(ItemType) 对项类型进行引用。例如，可以使用 @(Compile) 引用上例中的项类型。使用此语法可以将项类型指定为任务的参数，从而将项传递给该任务。有关更多信息，请参见如何：选择要生成的文件。

默认情况下，在展开项类型时，其中的项由分号 (;) 分隔。如需指定非默认分隔符，请使用语法 @(项类型, '分隔符')。有关更多信息，请参见如何：显示用逗号分隔的项列表。

使用通配符指定项

可以使用 **、* 和 ? 通配符将一组文件指定为生成的输入，而不是分别列出每个文件。

? 通配符与单一字符相匹配。
* 通配符与零个或多个字符相匹配。
** 通配符序列与部分路径相匹配。

例如，若要指定包含项目文件的目录中的所有 .cs 文件，请在项目文件中使用下面的元素。

用于选择 D: 驱动器上的所有 .vb 文件的元素为

<VBFile Include="D:/**/*.vb"/>.

有关通配符的更多信息，请参见如何：选择要生成的文件。

使用 Exclude 特性

项元素可以包含 Exclude 特性，该特性将特定的项（文件）排除在项类型之外。 Exclude 特性通常与通配符结合使用。例如，下面的 XML 将目录中除 DoNotBuild.cs 文件外的所有 .cs 文件都添加到 CSFile 项类型。

</ItemGroup>

仅当项元素同时包含 Exclude 特性和 Include 特性时，Exclude 特性才会影响其中由 Include 特性添加的项。例如，

不排除在前面的项元素中添加的文件 Form1.cs。

有关更多信息，请参见如何：将文件排除在生成过程外。

使用 Remove 特性

从 .NET Framework 3.5 开始，Target 元素可以包含 ItemGroup 元素，后者可以包含项元素。这些项元素可以包含 Remove 特性，该特性从项类型中移除特定的项（文件）。例如，下面的 XML 从 Compile 项类型中移除所有 .config 文件。

</ItemGroup>

</Target>

项的元数据

除了从 Include 特性和 Exclude 特性收集的信息，项还可能包含元数据。当任务需要有关项的更多信息时，可以使用这些元数据；元数据还可用来对任务和目标进行批处理。有关批处理的更多信息，请参见 MSBuild 批处理。

元数据是键/值对的集合。在项目文件中，这些键/值对声明为项元素的子元素。子元素的名称为元数据的名称，子元素的值为元数据的值。

元数据与包含自己的项元素相关联。例如，下面的 XML 将值为 Fr 的 Culture 元数据同时添加到 CSFile 项类型的“one.cs”和“two.cs”项。

</CSFile>

</ItemGroup>

项可以有零个或多个元数据值。元数据值可以随时更改。若将元数据设置为空值，等同于从生成中移除该元数据。

在项目文件中引用项元数据

在整个项目文件中，可以使用语法 %(ItemMetadataName) 对项元数据进行引用。当存在多义性时，可以使用项类型的名称对引用进行限定，例如 %(项类型.项元数据名称)。下面的示例使用 Display 元数据对 Message 任务进行批处理。有关如何使用项元数据进行批处理的更多信息，请参见任务批处理中的项元数据。

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
  <ItemGroup>
    <Stuff Include="One.cs" >
      <Display>false</Display>
    </Stuff>
    <Stuff Include="Two.cs">
      <Display>true</Display>
    </Stuff>
  </ItemGroup>
  <Target Name="Batching">
    <Message Text="@(Stuff)" Condition=" '%(Display)' == 'true' "/>
  </Target>
</Project>

已知的项元数据

在将项添加到项类型时，会将某些已知的元数据赋值给该项。例如，所有项都有已知的元数据 %(Filename)，其值为项的文件名。有关已知项元数据的列表，请参见 MSBuild 常见的项元数据。

使用元数据转换项类型

可以使用元数据将项列表转换为新的项列表。例如，可以使用表达式 @(CppFiles -> '%(Filename).obj')，将所含项表示 .cpp 文件的项类型 CppFiles 转换为对应的 .obj 文件列表。

下面的代码创建一个 CultureResource 项类型，该项类型包含具有 Culture 元数据的所有 EmbeddedResource 项的副本。 Culture 元数据值成为新元数据 CultureResource.TargetDirectory 的值。

<Target Name="ProcessCultureResources">
  <ItemGroup>
    <CultureResource Include="@(EmbeddedResource)"
       Condition="'%(EmbeddedResource.Culture)' != ''">
       <TargetDirectory>%(EmbeddedResource.Culture) </TargetDirectory>
    </CultureResource>
  </ItemGroup>
</Target>

有关更多信息，请参见 MSBuild 转换。

项定义

从 .NET Framework 3.5 开始，可以使用 ItemDefinitionGroup 元素将默认元数据添加到任何项类型。与已知元数据一样，默认元数据与所指定项类型的所有项相关联。可以在项定义中显式重写默认元数据。例如，下面的 XML 向 Compile 项“one.cs”和“three.cs”分配值为“Monday”的元数据 BuildDay，向项“two.cs”分配值为“Tuesday”的元数据 BuildDay。

<ItemDefinitionGroup>
  <Compile>
    <BuildDay>Monday</BuildDay>
  </Compile>
</ItemDefinitionGroup>
<ItemGroup>
  <Compile Include="one.cs;three.cs" />
  <Compile Include="two.cs">
    <BuildDay>Tuesday</BuildDay>
  </Compile>
</ItemGroup>

有关更多信息，请参见项定义。

请参见

通过

MSBuild 项

在项目文件中创建项

在执行过程中创建项

在项目文件中引用项

使用通配符指定项

使用 Exclude 特性

使用 Remove 特性

项的元数据

在项目文件中引用项元数据

已知的项元数据

使用元数据转换项类型

项定义

请参见

任务

参考

概念

其他资源

其他资源