Item 項目 (MSBuild)

  • 發行項

包含使用者定義的項目及其中繼資料。 MSBuild 專案中使用的每個項目，都必須指定為 ItemGroup 元素的子系。

<計畫>
 <ItemGroup>
  <項目>

語法

<Item Include="*.cs"
        Exclude="MyFile.cs"
        Condition="'String A'=='String B'">
    <ItemMetadata1>...</ItemMetadata1>
    <ItemMetadata2>...</ItemMetadata2>
</Item>

將中繼資料指定為屬性

在 MSBuild 15.1 或更新版本中，如果任何中繼資料的名稱未與目前的屬性清單衝突，您即可選擇將其表示為屬性。

例如，若要指定 NuGet 套件清單，您通常會使用類似下列的語法。

<ItemGroup>
  <PackageReference Include="Newtonsoft.Json">
    <Version>9.0.1-beta1<Version>
  </PackageReference>
</ItemGroup>

不過，您現在可以將 Version 中繼資料作為屬性傳遞，如下列語法所示：

<ItemGroup>
  <PackageReference Include="Newtonsoft.Json" Version="9.0.1-beta1" />
</ItemGroup>

屬性和元素

下列章節說明屬性、子元素和父元素。

屬性

屬性 描述
Include 選用屬性。

要包含在項目清單中的檔案或萬用字元。
Exclude 選用屬性。

要從項目清單中排除的檔案或萬用字元。
Condition 選用屬性。

要評估的條件。 如需詳細資訊，請參閱條件。
Remove 選用屬性。

要從項目清單移除的檔案或萬用字元。
MatchOnMetadata 選用屬性。

修改參考其他項目的 Remove 屬性，使其與指定的中繼資料名稱相符，而不是與參考項目的值相符。

此屬性只有在與僅包含其他項目 (例如，Remove="@(Compile);@(Content)") 所參考的 Remove 屬性一起指定時才有效。 項目中的詳細資料。
MatchOnMetadataOptions 選用屬性。

指定 MatchOnMetadata 所使用的字串比對原則。 可能的值為 CaseSensitive、CaseInsensitive 或 PathLike。 預設值是 CaseInsensitive。
KeepDuplicates 選用屬性。

指定項目如果與現有項目完全重複，是否應加入目標群組。 如果來源和目標項目具有相同的 Include 值，但中繼資料不同，則即使 KeepDuplicates 設定為 false，也會加入該項目。 如需詳細資訊，請參閱項目。

這個屬性只有在針對 ItemGroup 中的 Target 項目指定時才有效。
KeepMetadata 選用屬性。

要加入目標項目之來源項目的中繼資料。 只有其名稱指定在分號分隔清單中的中繼資料，會從來源項目傳輸到目標項目。 如需詳細資訊，請參閱項目。

這個屬性只有在針對 ItemGroup 中的 Target 項目指定時才有效。
RemoveMetadata 選用屬性。

不要傳輸到目標項目之來源項目的中繼資料。 所有中繼資料會從來源項目傳輸到目標項目，名稱包含在以分號分隔的名稱清單中之中繼資料除外。 如需詳細資訊，請參閱項目。

這個屬性只有在針對 ItemGroup 中的 Target 項目指定時才有效。
Update 選用屬性。 (僅適用於 Visual Studio 2017 或更新版本的 .NET Core 專案)。

可讓您修改專案的元數據;一開始指定一組項目之後，通常會用來覆寫特定項目的預設元數據（例如通配符）。

僅有當項目所在的 ItemGroup 不屬於 Target 時，針對該項目指定這個屬性才有效。

子元素

元素 描述
ItemMetadata 使用者定義的項目中繼資料索引鍵，其中含有項目中繼資料值。 項目中可能有零個或多個 ItemMetadata 項目。

父元素

元素 描述
ItemGroup 項目的群組項目。

備註

Item 項目定義建置系統的輸入，且會依據使用者定義的集合名稱，分組成為項目集合。 這些項目集合可以用來做為工作的參數，工作會使用集合中個別的項目來執行建置程序的步驟。 如需詳細資訊，請參閱項目。

使用標記法 @(<myType>)，可讓類型 <myType> 的項目集合展開為以分號分隔的字串清單，並傳遞至參數。 如果參數的類型是 string，則參數的值會是以分號分隔的項目清單。 如果參數是字串陣列 (string[])，則每個項目都會根據分號的位置，插入到陣列中。 如果工作參數的類型是 ITaskItem[]，則值就是項目集合的內容再加上任何附加的中繼資料。 若要使用分號以外的字元來分隔每個項目，請使用 @(<myType>, '<分隔符號>') 語法。

MSBuild 引擎可以評估萬用字元 (例如 * 和 ?) 以及遞迴萬用字元 (例如 /**/*.cs)。 如需詳細資訊，請參閱項目。

範例

下列程式碼範例示範如何宣告類型為 CSFile 的兩個項目。 第二個宣告項目包含 MyMetadata 設定為 HelloWorld 的中繼資料。

<ItemGroup>
    <CSFile Include="engine.cs; form.cs" />
    <CSFile Include="main.cs" >
        <MyMetadata>HelloWorld</MyMetadata>
    </CSFile>
</ItemGroup>

下列程式碼範例示範如何使用 Update 屬性，修改透過 Glob 隨附之 somefile.cs 檔案的中繼資料。 (僅適用於 Visual Studio 2017 或更新版本的 .NET Core 專案)。

<ItemGroup>
    <Compile Update="somefile.cs">  // or Update="*.designer.cs"
        <MetadataKey>MetadataValue</MetadataKey>
    </Compile>
</ItemGroup>

另請參閱