項目定義Item Definitions

MSBuildMSBuild 2.0 では、ItemGroup 要素を使用することにより、プロジェクト ファイルに項目を静的に宣言できます。 2.0 enables the static declaration of items in project files by using the ItemGroup element. ただし、メタデータは、すべての項目に共通であっても項目単位でしか追加できません。However, metadata may be added only at the item level, even if the metadata is identical for all items. MSBuildMSBuild 3.5 以降には、この制限を克服する ItemDefinitionGroup という名前のプロジェクト要素が導入されました。Starting in MSBuildMSBuild 3.5, a project element named ItemDefinitionGroup overcomes this limitation. ItemDefinitionGroup を使用して一連の項目定義を定義すると、名前付きの項目の種類に含まれるすべての項目に既定のメタデータ値を追加できます。ItemDefinitionGroup lets you define a set of item definitions, which add default metadata values to all items in the named item type.

ItemDefinitionGroup 要素は、プロジェクト ファイルの Project 要素の直後にあります。The ItemDefinitionGroup element appears immediately after the Project element of the project file. 項目定義によって、次の機能が使用可能になります。Item definitions provide the following functionality:

  • 項目の既定のグローバル メタデータをターゲットの外部で定義できます。You can define global default metadata for items outside a target. これにより、指定した種類のすべての項目に同じメタデータが適用されます。That is, the same metadata applies to all items of the specified type.

  • 項目の種類には複数の定義を指定できます。Item types can have multiple definitions. 項目の種類に複数のメタデータ指定を追加すると、最後の指定が優先されます When additional metadata specifications are added to the type, the last specification takes precedence. (メタデータのインポート順序はプロパティの場合と同じです。)(The metadata follows the same import order as properties follow.)

  • メタデータは追加的に指定できます。Metadata can be additive. たとえば、CDefines の値は設定されるプロパティに応じて条件付きで累積されます。For example, CDefines values are accumulated conditionally, depending on the properties that are being set. たとえば、MT;STD_CALL;DEBUG;UNICODE のようにします。For example, MT;STD_CALL;DEBUG;UNICODE.

  • メタデータを削除することができます。Metadata can be removed.

  • 条件を使用してメタデータの追加を制御できます。Conditions can be used to control the inclusion of metadata.

項目メタデータの既定値Item Metadata Default Values

ItemDefinitionGroup に定義された項目メタデータは、既定のメタデータの宣言に過ぎません。Item metadata that is defined in an ItemDefinitionGroup is just a declaration of default metadata. ItemGroup からメタデータ値を取り込む項目を定義しない限り、ItemDefinitionGroup に定義されたメタデータは適用されません。The metadata does not apply unless you define an Item that uses an ItemGroup to contain the metadata values.

注意

このトピックでは、多くの例に ItemDefinitionGroup 要素が示されていますが、それに対応する ItemGroup 定義は例の簡潔さを保つために省略しています。In many of the examples in this topic, an ItemDefinitionGroup element is shown but its corresponding ItemGroup definition is omitted for clarity.

ItemGroup に明示的に定義されたメタデータは、ItemDefinitionGroup 内のメタデータより優先されます。Metadata explicitly defined in an ItemGroup takes precedence over metadata in ItemDefinitionGroup. ItemDefinitionGroup 内のメタデータは、ItemGroup に対応するメタデータが定義されていない場合のみ適用されます。Metadata in ItemDefinitionGroup is applied only for undefined metadata in an ItemGroup. 例:For example:

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

この例では、項目 "i" ではメタデータ "m" が明示的に定義されていないため、既定のメタデータ "m" が項目 "i" に適用されます。In this example, the default metadata "m" is applied to Item "i" because metadata "m" is not explicitly defined by Item "i". ただし、項目 "i" でメタデータ "n" が既に定義されているため、既定のメタデータ "n" は項目 "i" には適用されません。However, default metadata "n" is not applied to Item "i" because metadata "n" is already defined by Item "i".

注意

XML 要素名およびパラメーター名では、大文字と小文字が区別されます。XML Element and Parameter names are case-sensitive. 項目メタデータ名と項目//プロパティ名では、大文字と小文字は区別されません。Item metadata and Item/Property names are not case-sensitive. したがって、大文字と小文字のみが異なる名前の ItemDefinitionGroup 項目は同じ ItemGroup として扱う必要があります。Therefore, ItemDefinitionGroup items that have names that differ only by case should be treated as the same ItemGroup.

値のソースValue Sources

ItemDefinitionGroup に定義されたメタデータには、以下のさまざまなソースから値を割り当てることができます。The values for metadata that is defined in an ItemDefinitionGroup can come from many different sources, as follows:

  • PropertyGroup プロパティPropertyGroup Property

  • ItemDefinitionGroup 内の項目Item from an ItemDefinitionGroup

  • ItemDefinitionGroup 項目の項目変換Item transform on an ItemDefinitionGroup Item

  • 環境変数Environment variable

  • グローバル プロパティ (MSBuild.exe コマンド ラインで指定)Global property (from the MSBuild.exe command line)

  • 予約済みのプロパティReserved property

  • ItemDefinitionGroup 内の項目の既知のメタデータWell-known metadata on an Item from an ItemDefinitionGroup

  • CDATA セクション <![CDATA[この部分は解析されない]]>CDATA section <![CDATA[anything here is not parsed]]>

注意

ItemDefinitionGroup 要素は ItemGroup 要素より先に処理されるため、ItemGroup の項目メタデータは ItemDefinitionGroup メタデータの宣言では役に立ちません。Item metadata from an ItemGroup is not useful in an ItemDefinitionGroup metadata declaration because ItemDefinitionGroup elements are processed before ItemGroup elements.

追加が可能な複数の定義Additive and Multiple Definitions

定義を追加したり複数の ItemDefinitionGroup を使用したりするときには、次の点に注意してください。When you add definitions or use multiple ItemDefinitionGroups, remember the following:

  • 追加のメタデータ指定は、その型に追加されます。Additional metadata specification is added to the type.

  • 最後のメタデータ指定が優先されます。The last specification takes precedence.

    複数の ItemDefinitionGroup がある場合、それ以降メタデータ指定を行うたびに、そのメタデータが前の定義に追加されます。When you have multiple ItemDefinitionGroups, each subsequent specification adds its metadata to the previous definition. 例:For example:

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

この例では、メタデータ "o" が "m" および "n" に追加されます。In this example, the metadata "o" is added to "m" and "n".

さらに、定義済みのメタデータ値も追加できます。In addition, previously defined metadata values can also be added. 例:For example:

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

この例では、メタデータ "m" (m1) の定義済みの値が新しい値 (m2) に追加されるため、最終的な値は "m1;m2" となります。In this example, the previously defined value for metadata "m" (m1) is added to the new value (m2), so that the final value is "m1;m2".

注意

これは同じ ItemDefinitionGroup でも発生します。This can also occur in the same ItemDefinitionGroup.

定義済みのメタデータ指定をオーバーライドすると、最後の指定が優先されます。When you override the previously defined metadata, the last specification takes precedence. 次の例では、メタデータ "m" の最終的な値が "m1" から "m1a" に変わります。In the following example, the final value of metadata "m" goes from "m1" to "m1a".

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

ItemDefinitionGroup での条件の使用Using Conditions in an ItemDefinitionGroup

ItemDefinitionGroup では、条件を使用してメタデータの追加を制御できます。You can use conditions in an ItemDefinitionGroup to control the inclusion of metadata. 例:For example:

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

この例では、"Configuration" プロパティの値が "Debug" である場合のみ項目 "i" の既定のメタデータ "m1" が追加されます。In this case, the default metadata "m1" on item "i" is included only if the value of the "Configuration" property is "Debug".

注意

条件では、ローカル メタデータ参照のみサポートされます。Only local metadata references are supported in conditions.

前の ItemDefinitionGroup に定義されたメタデータへの参照は、定義グループではなく項目に対してローカルです。References to metadata defined in an earlier ItemDefinitionGroup are local to the item, not the definition group. つまり、参照は項目をスコープとします。That is, the scope of the references are item-specific. 例:For example:

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

上の例では、項目 "i" がその条件に含まれる項目 "test" を参照しています。In the above example, item "i" references item "test" in its Condition. この条件が true になることはありません。MSBuild は、ItemDefinitionGroup の別項目のメタデータの参照を空の文字列として解釈するためです。This Condition will never be true because MSBuild interprets a reference to another item's metadata in an ItemDefinitionGroup as the empty string. そのため、"m" は "m0" に設定されます。Therefore, "m" would be set to "m0."

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

上の例では、条件が項目 "yes" に対して項目 "i" のメタデータ値を参照するので、"m" が値 "m1" に設定されます。In the above example, "m" would be set to the value "m1" as the Condition references item "i"'s metadata value for item "yes."

メタデータのオーバーライドと削除Overriding and Deleting Metadata

ItemDefinitionGroup 要素に定義されたメタデータは、値を空白に設定することにより、後の ItemDefinitionGroup 要素でオーバーライドできます。Metadata defined in an ItemDefinitionGroup element can be overridden in a later ItemDefinitionGroup element by setting the metadata value to blank. また、メタデータ項目は空の値に設定することによって削除できます。You can also effectively delete a metadata item by setting it to an empty value. 例:For example:

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

項目 "i" はメタデータ "m" を含んでいますが、その値は空です。The item "i" still contains metadata "m", but its value is now empty.

メタデータのスコープScope of Metadata

ItemDefinitionGroup は、それが定義されている定義済みプロパティおよびグローバル プロパティの全体をスコープとします。ItemDefinitionGroups have global scope on defined and global properties wherever they are defined. ItemDefinitionGroup 内の既定のメタデータ定義は自己参照が可能です。Default metadata definitions in an ItemDefinitionGroup can be self-referential. たとえば、次の例では簡単なメタデータ参照を使用しています。For example, the following uses a simple metadata reference:

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

次のような修飾されたメタデータ参照も使用できます。A qualified metadata reference can also be used:

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

ただし、次のコードは無効です。However, the following is not valid:

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

MSBuildMSBuild 3.5 以降では、ItemGroup も自己参照が可能です。Beginning in MSBuildMSBuild 3.5, ItemGroups can also be self-referential. 例:For example:

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

関連項目See Also

バッチ処理Batching