項目の定義

2025-08-08

MSBuild 2.0 では、 ItemGroup 要素を使用してプロジェクトファイル内の項目を静的に宣言できます。ただし、メタデータがすべての項目で同一である場合でも、メタデータは項目レベルでのみ追加できます。 MSBuild 3.5 以降では、 ItemDefinitionGroup という名前のプロジェクト要素がこの制限を克服します。 ItemDefinitionGroup を使用すると、一連の項目定義を定義できます。これにより、名前付き項目の種類のすべての項目に既定のメタデータ値が追加されます。

ItemDefinitionGroup 要素は、プロジェクトファイルの Project 要素の直後に表示されます。項目定義には、次の機能があります。

ターゲットの外部にある項目のグローバルな既定のメタデータを定義できます。つまり、指定した型のすべての項目に同じメタデータが適用されます。
項目の種類には、複数の定義を含めることができます。追加のメタデータ仕様が型に追加されると、最後の指定が優先されます。 (メタデータは、プロパティと同じインポート順序に従います)。
メタデータは追加可能です。たとえば、CDefines 値は、設定されているプロパティに応じて条件付きで累積されます。たとえば、MT;STD_CALL;DEBUG;UNICODE のようにします。
メタデータは削除できます。
条件を使用して、メタデータの包含を制御できます。

項目メタデータの既定値

ItemDefinitionGroup で定義されている項目メタデータは、既定のメタデータの宣言にすぎません。 ItemGroup を使用してメタデータ値を格納する Item を定義しない限り、メタデータは適用されません。

注

このトピックの多くの例では、ItemDefinitionGroup 要素が表示されますが、わかりやすくするために、対応する ItemGroup 定義は省略されています。

ItemGroup で明示的に定義されたメタデータは、ItemDefinitionGroup のメタデータよりも優先されます。 ItemDefinitionGroup のメタデータは、ItemGroup 内の未定義のメタデータにのみ適用されます。例えば次が挙げられます。

<ItemDefinitionGroup>
    <i>
        <m>m1</m>
        <n>n1</n>
    </i>
</ItemDefinitionGroup>
<ItemGroup>
    <i Include="a">
        <o>o1</o>
        <n>n2</n>
    </i>
</ItemGroup>

この例では、メタデータ "m" が Item "i" によって明示的に定義されていないため、既定のメタデータ "m" が Item "i" に適用されます。ただし、既定のメタデータ "n" は項目 "i" には適用されません。メタデータ "n" は項目 "i" によって既に定義されているためです。

注

XML 要素名とパラメーター名では、大文字と小文字が区別されます。項目メタデータとアイテム/プロパティ名では、大文字と小文字は区別されません。したがって、大文字と小文字のみが異なる名前を持つ ItemDefinitionGroup 項目は、同じ ItemGroup として扱う必要があります。

値ソース

ItemDefinitionGroup で定義されているメタデータの値は、次のようにさまざまなソースから取得できます。

PropertyGroup プロパティ
ItemDefinitionGroup の項目
ItemDefinitionGroup 項目の項目変換
環境変数
グローバルプロパティ ( MSBuild.exe コマンドラインから)
予約済みプロパティ
ItemDefinitionGroup の項目に関する既知のメタデータ
CDATA セクション <![CDATA[ここには何も解析されません]]>

注

ItemDefinitionGroup 要素は ItemGroup 要素の前に処理されるため、ItemGroup の項目メタデータは ItemDefinitionGroup メタデータ宣言では役に立ちません。

加法と複数の定義

定義を追加したり、複数の ItemDefinitionGroups を使用したりする場合は、次の点に注意してください。

追加のメタデータ仕様が型に追加されます。
最後の指定が優先されます。

複数の ItemDefinitionGroup がある場合、後続の各仕様では、そのメタデータが前の定義に追加されます。例えば次が挙げられます。

<ItemDefinitionGroup>
    <i>
        <m>m1</m>
        <n>n1</n>
    </i>
</ItemDefinitionGroup>
<ItemDefinitionGroup>
    <i>
        <o>o1</o>
    </i>
</ItemDefinitionGroup>

この例では、メタデータ "o" が "m" と "n" に追加されています。

さらに、以前に定義したメタデータ値を追加することもできます。例えば次が挙げられます。

<ItemDefinitionGroup>
    <i>
        <m>m1</m>
    </i>
</ItemDefinitionGroup>
<ItemDefinitionGroup>
    <i>
        <m>%(m);m2</m>
    </i>
</ItemDefinitionGroup>

この例では、メタデータ "m" (m1) の以前に定義された値が新しい値 (m2) に追加され、最終的な値が "m1; になります。m2"

注

これは、同じ ItemDefinitionGroup でも発生する可能性があります。

前に定義したメタデータをオーバーライドすると、最後の指定が優先されます。次の例では、メタデータ "m" の最終的な値は "m1" から "m1a" になります。

<ItemDefinitionGroup>
    <i>
        <m>m1</m>
    </i>
</ItemDefinitionGroup>
<ItemDefinitionGroup>
    <i>
        <m>m1a</m>
    </i>
</ItemDefinitionGroup>

ItemDefinitionGroup で条件を使用する

ItemDefinitionGroup の条件を使用して、メタデータの包含を制御できます。例えば次が挙げられます。

<ItemDefinitionGroup Condition="'$(Configuration)'=='Debug'">
    <i>
        <m>m1</m>
    </i>
</ItemDefinitionGroup>

この場合、項目 "i" の既定のメタデータ "m1" は、"Configuration" プロパティの値が "Debug" の場合にのみ含まれます。

注

条件では、ローカルメタデータ参照のみがサポートされます。

以前の ItemDefinitionGroup で定義されたメタデータへの参照は、定義グループではなく、項目に対してローカルです。つまり、参照のスコープは項目固有です。例えば次が挙げられます。

<ItemDefinitionGroup>
    <test>
        <yes>1</yes>
    </test>
    <i>
        <m>m0</m>
        <m Condition="'%(test.yes)'=='1'">m1</m>
    </i>
</ItemDefinitionGroup>

上記の例では、項目 "i" は条件の項目 "test" を参照します。 MSBuild は ItemDefinitionGroup 内の別の項目のメタデータへの参照を空の文字列として解釈するため、この条件は当てはまりません。したがって、"m" は "m0" に設定されます。

  <ItemDefinitionGroup>
    <i>
      <m>m0</m>
      <yes>1</yes>
      <m Condition="'%(i.yes)'=='1'">m1</m>
    </i>
  </ItemDefinitionGroup>

上記の例では、条件が項目 "i" の項目 "yes" のメタデータ値を参照するため、"m" は値 "m1" に設定されます。

メタデータのオーバーライドと削除

ItemDefinitionGroup 要素で定義されたメタデータは、メタデータ値を別の値に設定することで、後の ItemDefinitionGroup 要素でオーバーライドできます。メタデータ項目を空の値に設定することで、効果的に削除することもできます。例えば次が挙げられます。

<ItemDefinitionGroup>
    <i>
        <m>m1</m>
    </i>
</ItemDefinitionGroup>
<ItemDefinitionGroup>
    <i>
        <m></m>
    </i>
</ItemDefinitionGroup>

項目 "i" にはメタデータ "m" がまだ含まれていますが、その値は空になりました。

メタデータのスコープ

ItemDefinitionGroups は、定義されている場所を問わず、定義されたプロパティとグローバルプロパティにグローバルスコープを持ちます。 ItemDefinitionGroup の既定のメタデータ定義は、自己参照型にすることができます。たとえば、次の例では単純なメタデータ参照を使用します。

<ItemDefinitionGroup>
    <i>
        <m>m1</m>
        <m>%(m);m2</m>
    </i>
</ItemDefinitionGroup>

修飾されたメタデータ参照を使用することもできます。

<ItemDefinitionGroup>
    <i>
        <m>m1</m>
        <m>%(i.m);m2</m>
    </i>
</ItemDefinitionGroup>

ただし、以下は無効です。

<ItemDefinitionGroup>
    <i>
        <m>m1</m>
        <m>@(x)</m>
    </i>
</ItemDefinitionGroup>

MSBuild 3.5 以降では、ItemGroups を自己参照することもできます。例えば次が挙げられます。

<ItemGroup>
    <item Include="a">
        <m>m1</m>
        <m>%(m);m2</m>
    </item>
</ItemGroup>

バッチ処理

フィードバック

このページはお役に立ちましたか?