Item 要素 (MSBuild)

  • [アーティクル]

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

<プロジェクト>
 <ItemGroup>
  <Item>

構文

<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 属性 (たとえば、Remove="@(Compile);@(Content)") と共に指定されている場合にのみ有効です。 詳細については、項目に関する記事を参照してください。
MatchOnMetadataOptions 省略可能な属性です。

MatchOnMetadata によって使用される文字列照合の方法を指定します。 設定可能な値は、CaseSensitive、CaseInsensitive、または PathLike です。 既定値は CaseInsensitive です。
KeepDuplicates 省略可能な属性です。

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

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

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

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

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

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

アイテムのメタデータを変更できます。通常は、項目のグループが最初に指定された後に特定の項目の既定のメタデータをオーバーライドするために使用されます (ワイルドカードなど)。

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

子要素

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

親要素

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

解説

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

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

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

例

次のコード例は、CSFile 型の 2 つのアイテムを宣言する方法を示しています。 2 番目に宣言されているアイテムには、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>

関連項目