Item 要素 (MSBuild)

ユーザー定義のアイテムおよびそのメタデータが含まれます。 MSBuild プロジェクトで使用されるすべてのアイテムが、ItemGroup 要素の子として指定されている必要があります。

<Project>
<ItemGroup>
<Item>

構文

<Item Include="*.cs"  
        Exclude="MyFile.cs"  
        Remove="RemoveFile.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 省略可能な属性です。

アイテムの一覧から削除するファイルまたはワイルドカードです。

KeepDuplicates 省略可能な属性です。

既存のアイテムの完全な複製である場合に、アイテムをターゲット グループに追加するかどうかを指定します。 ソースとターゲットのアイテムの Include 値が同じでメタデータが異なる場合、KeepDuplicatesfalse に設定されていてもアイテムは追加されます。 詳細については、「MSBuild 項目」をご覧ください。

この属性は、ItemGroup 内にある Target のアイテムに指定されている場合にのみ有効です。
KeepMetadata 省略可能な属性です。

ターゲット アイテムに追加するソース アイテムのメタデータ。 名前がセミコロン区切りのリストで指定されているメタデータのみ、ソース アイテムからターゲット アイテムに転送されます。 詳細については、「MSBuild 項目」をご覧ください。

この属性は、ItemGroup 内にある Target のアイテムに指定されている場合にのみ有効です。
RemoveMetadata 省略可能な属性です。

ターゲット アイテムに転送しないソース アイテムのメタデータ。 名前がセミコロン区切りの名前リストに含まれているメタデータを除いて、すべてのメタデータがソース アイテムからターゲット アイテムに転送されます。 詳細については、「MSBuild 項目」をご覧ください。

この属性は、ItemGroup 内にある Target のアイテムに指定されている場合にのみ有効です。
Update 省略可能な属性です。 (Visual Studio 2017 以降の .NET Core プロジェクトでのみ利用できます。)

glob で追加されたファイルのメタデータを変更できます。

この属性は、Target にない ItemGroup のアイテムに指定されている場合にのみ有効です。

子要素

要素 説明
ItemMetadata アイテム メタデータ値を含むユーザー定義のアイテム メタデータ キーです。 1 つのアイテムに 0 個以上の ItemMetadata 要素を含めることができます。

親要素

要素 説明
ItemGroup アイテムの grouping 要素です。

コメント

Item 要素はビルド システムへの入力を定義し、ユーザー定義のコレクション名に基づいてアイテム コレクションにグループ化されます。 これらのアイテム コレクションは、タスクのパラメーターとして使用できます。タスクは、コレクション内の個々のアイテムを使用してビルド処理の各ステップを実行します。 詳細については、「MSBuild 項目」をご覧ください。

@(myType) という表記を使用すると、myType 型のアイテムのコレクションをセミコロン区切りの文字列リストに展開して、パラメーターに渡すことができます。 パラメーターが string 型の場合は、パラメーターの値がセミコロンで区切られた要素のリストになります。 パラメーターが文字列の配列の場合 (string[])、各要素はセミコロンの位置に基づいて配列に挿入されます。 タスク パラメーターが ITaskItem[] 型の場合、値は、アイテム コレクションの内容と、アタッチされているすべてのメタデータになります。 セミコロン以外の文字を使用して各アイテムを区切るには、@(myType, 'separator') 構文を使用します。

MSBuild エンジンでは、*? などのワイルドカードや、/**/*.cs などの再帰的なワイルドカードを評価できます。 詳細については、「MSBuild 項目」をご覧ください。

次のコード例は、CSFile 型の 2 つのアイテムを宣言する方法を示しています。 2 番目に宣言されているアイテムには、MyMetadataHelloWorld に設定されたメタデータが含まれています。

<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>  

関連項目

項目
MSBuild プロパティ
プロジェクト ファイル スキーマ リファレンス