共用方式為

MSBuild 項目

  • 發行項

MSBuild 項目 (Item) 是建置系統，因此，它們通常代表檔案。項目 (Item) 會依據其項目 (Element) 名稱劃分到各個項目 (Item) 類型中。項目 (Item) 類型是可以做為工作參數之項目 (Item) 的具名清單。工作會使用這些項目 (Item) 值執行建置程序的步驟。

因為項目是由其所屬的項目類型命名的，可以交替使用詞彙「Item」和「項目值」。

本主題內容

  • 在專案檔中建立項目

  • 在執行期間建立項目

  • 在專案檔中參考項目

  • 使用萬用字元指定項目

  • 使用 Exclude 屬性

  • 項目中繼資料

    • 在專案檔中參考項目中繼資料

    • 已知的項目中繼資料

    • 使用中繼資料轉換項目類型

  • 項目定義

  • 項目的屬性目標的 ItemGroup

    • 移除屬性

    • KeepMetadata 屬性

    • RemoveMetadata 屬性

    • KeepDuplicates 屬性

在專案檔中建立項目

您是在專案檔中的項目在 ItemGroup 項目的子項目。子項目 (Element) 的名稱為項目 (Item) 的類型。項目 (Element) 的 Include 屬性會指定該項目 (Item) 類型中包含的項目 (Item)(檔案)。例如，下列 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>

在執行期間建立項目

不在 目標 項目在組建的評估階段內，會指派值。在後續的執行階段期間，您可以透過下列方式建立或修改項目:

  • 所有工作可以發出項目。若要發出項目 (Item)，Task 項目 (Element) 必須具有包含 ItemName 屬性的子項目 (Element) Output。

  • CreateItem 工作可以發出項目。這個使用方式已被取代。

  • 從 .NET Framework 3.5 開始，Target 項目 (Element) 可以包含可能具有項目之項目 (Item Element) 的 ItemGroup 項目 (Element)。

在專案檔中參考項目

若要參考在專案檔中的項目類型，您可以使用語法 @ (ItemType)。例如，您可以使用 @(Compile)，您會參考前述範例中的項目型別。使用此語法時，您可以將項目加入至工作的指定項目型別做為工作的參數。如需詳細資訊，請參閱HOW TO：選取要建置的檔案。

根據預設，項目型別的項目以分號 (;)，當它展開。您可以使用語法 @ (ItemType， 『分隔符號」) 預設值之外，指定分隔符號。如需詳細資訊，請參閱HOW TO：顯示以逗號分隔的項目清單。

使用萬用字元指定項目

您可以使用 **、* 和 ? 萬用字元指定檔案群組做為組建的輸入，而不分別列出每個檔案。

  • ? 萬用字元會比對單一字元。

  • * 萬用字元會比對零個或多個字元。

  • ** 萬用字元序列會比對一部分路徑。

例如，您可以在包含專案檔中使用下列項目在專案檔的目錄中指定所有 .cs 檔案。

<CSFile Include="*.cs"/>

下列項目選取 D 的所有 .vb 檔案:磁碟機:

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

如需萬用字元的詳細資訊，請參閱 HOW TO：選取要建置的檔案。

使用 Exclude 屬性

項目的項目 (Item Element) 可以包含 Exclude 屬性，這個屬性會排除項目 (Item) 類型中的特定項目 (Item) (檔案)。Exclude 屬性通常是搭配萬用字元使用的。例如，下列 XML 會將目錄中的每個 .cs 檔案加入至 CSFile 項目 (Item) 類型，但 DoNotBuild.cs 檔案例外。

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

Exclude 屬性影響由項目中 Include 屬性將包含這兩個方法中的項目。下列範例不會排除檔案 Form1.cs，前面的項目加入。

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

如需詳細資訊，請參閱HOW TO：從組建中排除檔案。

項目中繼資料

項目可以包含中繼資料的資訊以外 Include 和 Exclude 屬性。這項中繼資料可由需要項目的相關詳細資訊的工作使用或批次處理工作和目標。如需詳細資訊，請參閱MSBuild 批次處理。

中繼資料是在專案檔中宣告的索引鍵-值組集合，以做為項目的項目 (Item Element) 的子項目 (Element)。子項目 (Element) 的名稱是中繼資料的名稱，而子項目 (Element) 的值則為中繼資料的值。

中繼資料與其所屬的項目的項目 (Item Element) 是相關聯的。例如，下列 XML 會將 Culture 中繼資料有值 Fr 至 CSFile 項目 (Item) 類型的「one.cs」和「two.cs」項目。

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

項目 (Item) 可以不包含或包含更多中繼資料值。您可以隨時變更中繼資料值。如果您為空值，同時設定中繼資料從組建有效移除它。

ms171453.collapse_all(zh-tw,VS.110).gif在專案檔中參考項目中繼資料

使用 % 語法 (ItemMetadataName)，您可以參考在專案檔中的項目中繼資料。如果模稜兩可 (Ambiguity) 的，使用項目型別的名稱，您可以限定參考。例如，您可以指定ItemType.ItemMetaDataName% ()。下列範例顯示使用中繼資料來批次處理 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>

ms171453.collapse_all(zh-tw,VS.110).gif已知的項目中繼資料

在項目 (Item) 類型中加入項目時，即指派了某些已知的中繼資料給該項目。例如，所有項目都有已知的中繼資料 %(Filename)，這個值是項目的檔案名稱。如需詳細資訊，請參閱MSBuild 已知的項目中繼資料。

ms171453.collapse_all(zh-tw,VS.110).gif使用中繼資料轉換項目類型

使用中繼資料，您可以轉換項目清單分割成新項目清單。例如，您可以轉換使用運算式 @(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 項目開始，才能執行，您可以將預設中繼資料加入到任何項目類型。像已知的中繼資料，預設中繼資料與所指定項目型別的所有項目。您可以明確覆寫項目中所定義的預設中繼資料。例如，下列 XML 會 Compile 項目「one.cs」和「three.cs」與值「、"」的中繼資料 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 項目 (Element) 可以包含可能具有項目之項目 (Item Element) 的 ItemGroup 項目 (Element)。在區段的屬性是有效的，則為 Target項目指定在 ItemGroup 時。

ms171453.collapse_all(zh-tw,VS.110).gif移除屬性

在目標的 ItemGroup 的項目可能包含 Remove 屬性，移除特定的項目 (檔案) 從項目類型。這個屬性在 .NET Framework 中引入的。

下列範例從 Compile 項目類型刪除每個 .config 檔案。

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

ms171453.collapse_all(zh-tw,VS.110).gifKeepMetadata 屬性

如果項目在目標中產生，項目可以包含 KeepMetadata 屬性。如果在名稱以分號分隔的清單中指定的這個屬性指定，，只有中繼資料從來源項目要轉送到目標項目。這個屬性的 Null 值與不指定它就相當於。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: 
-->

ms171453.collapse_all(zh-tw,VS.110).gifRemoveMetadata 屬性

如果項目在目標中產生，項目可以包含 RemoveMetadata 屬性。如果這個屬性指定，所有中繼資料從來源項目轉移到除了名稱在名稱以分號分隔的清單包含目前欄位的中繼資料的目標項目。這個屬性的 Null 值與不指定它就相當於。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: 
-->

ms171453.collapse_all(zh-tw,VS.110).gifKeepDuplicates 屬性

如果項目在目標中產生，項目可以包含 KeepDuplicates 屬性。KeepDuplicates 是指定的 Boolean 屬性是否應該將項目加入至目標 (Target)，如果項目是現有項目的一個執行個體的完全複製。

如果來源和目標項目具有相同的 Include 值，但不同的中繼資料，加入項目，即使 KeepDuplicates 設為 false。這個屬性的 Null 值與不指定它就相當於。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
-->

請參閱

工作

HOW TO：選取要建置的檔案

HOW TO：從組建中排除檔案

HOW TO：顯示以逗號分隔的項目清單

參考

Item 項目 (MSBuild)

概念

項目定義

MSBuild 批次處理

其他資源

MSBuild 概念

MSBuild