MSBuild 项

项目
02/21/2013

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

由于项目由其所属的项类型进行命名，可以互换使用术语“项”和“项值”。

主题内容

在项目文件中创建项
在执行过程中创建项
在项目文件中引用项
使用通配符指定项
使用 Exclude 特性
项的元数据
- 在项目文件中引用项元数据
- 已知的项元数据
- 可以使用元数据转换项类型
项定义
项目的属性在目标的 ItemGroup
- 移除特性
- KeepMetadata 属性
- RemoveMetadata 属性
- KeepDuplicates 属性

在项目文件中创建项

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

<ItemGroup>
    <Compile Include = "file1.cs"/>
    <Compile Include = "file2.cs"/>
</ItemGroup>

该项“file2.cs”不替换项“file1.cs”;相反，文件名追加到值列表 Compile 项类型。在生成的计算阶段，您不能从项类型中移除项。

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

<ItemGroup>
    <Compile Include = "file1.cs;file2.cs"/>
</ItemGroup>

在执行过程中创建项

是外部目标元素在生成的计算阶段的项目中，为其赋值。在随后的执行阶段中，可以按下列方式创建或修改项：

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

在项目文件中引用项

若要在整个项目文件中引用的项类型，请使用语法 @ (ItemType)。例如，通过使用 @(Compile)，则会引用该项目输入例。使用此语法，可以通过项目到任务通过指定项类型作为该任务的参数。有关更多信息，请参见如何：选择要生成的文件。

默认情况下，项目类型的项由分号 (;)，则扩展。可以使用语法 @ (ItemType，“分隔符”) 除默认外，指定分隔符。有关更多信息，请参见如何：显示用逗号分隔的项列表。

使用通配符指定项

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

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

例如，在包含项目文件使用以下元素在项目文件的内容可以指定所有 .cs 文件。

<CSFile Include="*.cs"/>

以下组件选择 D 的所有 .vb 文件：驱动程序：

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

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

使用 Exclude 特性

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

<ItemGroup>
    <CSFile  Include="*.cs"  Exclude="DoNotBuild.cs"/>
</ItemGroup>

Exclude 属性影响由项元素的 Include 属性将包含这两个仅的项目。下面的示例不排除文件 Form1.cs，在前面的项元素中添加。

<Compile Include="*.cs" />
<Compile Include="*.res" Exclude="Form1.cs">

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

项的元数据

项目可以包含元数据除了信息外在 Include 和 Exclude 属性。此元数据可由需要有关项的更多信息的任务使用或批处理任务和目标。有关更多信息，请参见MSBuild 批处理。

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

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

<ItemGroup>
    <CSFile Include="one.cs;two.cs">
        <Culture>Fr</Culture>
    </CSFile>
</ItemGroup>

项可以有零个或多个元数据值。可以在 + 任何 + 时间更改元数据值。如果将元数据设置为空值，则从生成有效移除它。

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

使用语法 % (ItemMetadataName)，则可以在整个项目文件中引用的项元数据。如果存在多义性，可以使用项类型的名称，则可以限定引用。例如，可以指定 % (ItemType.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 文件添加到对应的 .obj 文件列表的项目类型 CppFiles。

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

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

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

项定义

使用 ItemDefinitionGroup element，开始在 .NET Framework 3.5 中，可以将默认元数据添加到任何项类型。与已知的元数据，默认元数据与您指定项目类型的所有项。可以显式重写项目定义的默认元数据。例如，下面的 XML 向 Compile 项“one.cs”和“three.cs”分配值为“mon”的元数据 BuildDay。代码出自该项目“two.cs”为值“、”的元数据 BuildDay。

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

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

项目的属性在目标的 ItemGroup

从 .NET Framework 3.5 开始，Target 元素可以包含 ItemGroup 元素，后者可以包含项元素。本节中的特性是有效的，则为 Target的项目指定在 ItemGroup 时。

移除特性

在目标的 ItemGroup 的项目可以包含 Remove 属性，移除特定的项 (文件) 从项目类型。此属性在 .NET Framework 3.5 中引入的。

下面的示例从 compile 项类型中移除所有 .config 文件。

<Target>
    <ItemGroup>
        <Compile Remove="*.config"/>
    </ItemGroup>
</Target>

KeepMetadata 属性

如果项目在目标中启动，项元素可以包含 KeepMetadata 属性。如果在分号分隔的指定此特性指定，因此，只有元数据名称列表从源项目将转到目标项目。此属性的空值与不指定它是等效的。 KeepMetadata 属性在 .NET Framework 4.5 中引入的。

下面的示例演示如何使用 KeepMetadata 属性。

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003"
ToolsVersion="4.0">

    <ItemGroup>
        <FirstItem Include="rhinoceros">
            <Class>mammal</Class>
            <Size>large</Size>
        </FirstItem>

    </ItemGroup>
    <Target Name="MyTarget">
        <ItemGroup>
            <SecondItem Include="@(FirstItem)" KeepMetadata="Class" />
        </ItemGroup>

        <Message Text="FirstItem: %(FirstItem.Identity)" />
        <Message Text="  Class: %(FirstItem.Class)" />
        <Message Text="  Size:  %(FirstItem.Size)"  />

        <Message Text="SecondItem: %(SecondItem.Identity)" />
        <Message Text="  Class: %(SecondItem.Class)" />
        <Message Text="  Size:  %(SecondItem.Size)"  />
    </Target>
</Project>

<!--
Output:
  FirstItem: rhinoceros
    Class: mammal
    Size:  large
  SecondItem: rhinoceros
    Class: mammal
    Size: 
-->

RemoveMetadata 属性

如果项目在目标中启动，项元素可以包含 RemoveMetadata 属性。如果此特性指定，所有元数据从源项目传输到除名称以分号分隔的列表包含名称的元数据的目标项目。此属性的空值与不指定它是等效的。 RemoveMetadata 属性在 .NET Framework 4.5 中引入的。

下面的示例演示如何使用 RemoveMetadata 属性。

<Project ToolsVersion="4.0" xmlns="https://schemas.microsoft.com/developer/msbuild/2003">

    <PropertyGroup>
        <MetadataToRemove>Size;Material</MetadataToRemove>
    </PropertyGroup>

    <ItemGroup>
        <Item1 Include="stapler">
            <Size>medium</Size>
            <Color>black</Color>
            <Material>plastic</Material>
        </Item1>
    </ItemGroup>

    <Target Name="MyTarget">
        <ItemGroup>
            <Item2 Include="@(Item1)" RemoveMetadata="$(MetadataToRemove)" />
        </ItemGroup>

        <Message Text="Item1: %(Item1.Identity)" />
        <Message Text="  Size:     %(Item1.Size)" />
        <Message Text="  Color:    %(Item1.Color)" />
        <Message Text="  Material: %(Item1.Material)" />
        <Message Text="Item2: %(Item2.Identity)" />
        <Message Text="  Size:     %(Item2.Size)" />
        <Message Text="  Color:    %(Item2.Color)" />
        <Message Text="  Material: %(Item2.Material)" />
    </Target>
</Project>

<!--
Output: 
  Item1: stapler
    Size:     medium
    Color:    black
    Material: plastic
  Item2: stapler
    Size:     
    Color:    black
    Material: 
-->

KeepDuplicates 属性

如果项目在目标中启动，项元素可以包含 KeepDuplicates 属性。 KeepDuplicates 是指定的 Boolean 属性是否应将项添加到目标组，如果项目完全相同的副本现有项目。

如果源页和目标项目具有同一包括值，但不同的元数据，该项将添加，即使 KeepDuplicates 设置为 false。此属性的空值与不指定它是等效的。 KeepDuplicates 属性在 .NET Framework 4.5 中引入的。

下面的示例演示如何使用 KeepDuplicates 属性。

<Project ToolsVersion="4.0" xmlns="https://schemas.microsoft.com/developer/msbuild/2003">

    <ItemGroup>
        <Item1 Include="hourglass;boomerang" />
        <Item2 Include="hourglass;boomerang" />
    </ItemGroup>

    <Target Name="MyTarget">
        <ItemGroup>
            <Item1 Include="hourglass" KeepDuplicates="false" />
            <Item2 Include="hourglass" />
        </ItemGroup>

        <Message Text="Item1: @(Item1)" />
        <Message Text="  %(Item1.Identity)  Count: @(Item1->Count())" />
        <Message Text="Item2: @(Item2)" />
        <Message Text="  %(Item2.Identity)  Count: @(Item2->Count())" />
    </Target>
</Project>

<!--
Output: 
  Item1: hourglass;boomerang
    hourglass  Count: 1
    boomerang  Count: 1
  Item2: hourglass;boomerang;hourglass
    hourglass  Count: 2
    boomerang  Count: 1
-->

请参见