MSBuild 項目

[アーティクル]
02/21/2013

MSBuild項目はビルドシステムへの入力であり、通常はファイルを表します。項目はその要素名に基づいて項目の種類にグループ化されます。項目の種類は項目の名前付きリストであり、タスクのパラメーターとして使用できます。タスクは項目値を使用して、ビルド処理のステップを実行します。

項目が属する項目の種類によって指定されるため、用語「項目」と「項目値」と同じように使用できます。

このトピックの内容

プロジェクトファイルでの項目の作成
実行時の項目の作成
プロジェクトファイルでの項目の参照
ワイルドカードの使用による項目の指定
Exclude 属性の使用
アイテムメタデータ
- プロジェクトファイルでのアイテムメタデータの参照
- 既知のアイテムメタデータ
- メタデータを使用して項目の種類の変換
項目定義
ターゲットItemGroupの項目の属性
- 属性の削除
- KeepMetadataの属性
- RemoveMetadataの属性
- KeepDuplicatesの属性

プロジェクトファイルでの項目の作成

[ItemGroup] 要素の子要素としてプロジェクトファイル内の項目を宣言します。子要素の名前が項目の種類になります。要素の Include 属性は、その項目の種類に含める項目 (ファイル) を指定します。たとえば、次のXMLでは Compileという項目の種類を作成して、2ファイルを含む。

<ItemGroup>
    <Compile Include = "file1.cs"/>
    <Compile Include = "file2.cs"/>
</ItemGroup>

項目「file2.cs」は項目「file1.cs」は置き換えられません; 代わりに、ファイル名は Compile の項目の種類の値のリストに追加されます。ビルドの評価フェーズで項目の種類から項目を削除することはできません。

次の XML では、両方のファイルを 1 つの Include 属性で宣言することで、同じ項目の種類を作成しています。ファイル名はセミコロンで区切ります。

<ItemGroup>
    <Compile Include = "file1.cs;file2.cs"/>
</ItemGroup>

実行時の項目の作成

[ターゲット] の外側の要素である項目はビルドの評価フェーズで値が割り当てられます。その後の実行フェーズで項目は、次の方法で作成または変更できます:

すべてのタスクが項目を生成できます。項目を生成するには、Task 要素の子要素として、ItemName 属性を持つ Output 要素を定義する必要があります。
CreateItem のタスクは、項目を生成できます。この使用法は推奨されていません。
.NET Framework 3.5 以降では、項目要素を格納できる ItemGroup 要素を Target 要素に含めることができます。

プロジェクトファイルでの項目の参照

プロジェクトファイルでの項目の種類を参照するには、次の構文を使用しますItemType (@)。たとえば、前の例で @(Compile)を使用して項目の種類を参照します。この構文を使用して、タスクにそのタスクパラメーターとして項目の種類の指定を項目を渡すことができます。詳細については、「方法: ビルドするファイルを選択する」を参照してください。

既定では、項目の種類に含まれる項目に配置したときは、セミコロン (;) で区切って指定します。(ItemType、「」区切り記号) 既定以外の区切り記号を指定するには、構文@を使用できます。詳細については、「方法: 項目リストをコンマ区切りで表示する」を参照してください。

ワイルドカードの使用による項目の指定

**、*、および ? の各ワイルドカードを使用すると、各ファイルを個別にリストする代わりに、ファイルのグループをビルドの入力として指定できます。

?ワイルドカード文字は 1 文字と一致します。
* ワイルドカード文字は 0 文字以上と一致します。
** ワイルドカード文字シーケンスは部分パスと一致します。

たとえば、プロジェクトファイルで次の要素を使用して、プロジェクトファイルを含むディレクトリ内のすべての.csファイルを指定できます。

<CSFile Include="*.cs"/>

次の要素は、Dのすべての.vbファイルを選択します: ドライブ:

<VBFile Include="D:/**/*.vb"/>

ワイルドカード文字の詳細については、「方法: ビルドするファイルを選択する」を参照してください。

Exclude 属性の使用

項目要素には、Exclude 属性を含めることができます。この属性は、特定の項目 (ファイル) を項目の種類から除外します。Exclude 属性は通常、ワイルドカード文字と共に使用します。たとえば、次の XML は、ディレクトリ内の DoNotBuild.cs ファイルを除くすべての .cs ファイルを CSFile 項目の種類に追加します。

<ItemGroup>
    <CSFile  Include="*.cs"  Exclude="DoNotBuild.cs"/>
</ItemGroup>

Exclude の属性の影響、同一の項目要素の Include 属性によって追加された項目のみ。前の項目要素で追加次の例では、ファイルの例では、Form1.cs。

<Compile Include="*.cs" />
<Compile Include="*.res" Exclude="Form1.cs">

詳細については、「方法: ビルドからファイルを除外する」を参照してください。

アイテムメタデータ

項目は Include と Exclude の属性の情報に加えて、メタデータが含まれる場合があります。このメタデータは、項目に関するまたはタスクおよびターゲットのバッチ処理への詳細情報を必要とするタスクで使用できます。詳細については、「MSBuild バッチ」を参照してください。

メタデータとは、プロジェクトファイル内で項目要素の子要素として宣言された、キーと値のペアのコレクションです。子要素の名前がメタデータの名前になり、子要素の値がメタデータの値になります。

メタデータは、それを含む項目要素に関連付けられます。たとえば、次のXMLでは Culture のメタデータCSFile項目の種類に「one.cs」と「two.cs」の値が Fr に項目を追加します。

<ItemGroup>
    <CSFile Include="one.cs;two.cs">
        <Culture>Fr</Culture>
    </CSFile>
</ItemGroup>

項目には 0 以上のメタデータ値を指定できます。メタデータの値はいつでも変更できます。ビルドから、空の値に対してメタデータ効果的に削除します。

プロジェクトファイルでのアイテムメタデータの参照

構文 %(ItemMetadataName) を使用してプロジェクトファイル内の項目のメタデータを参照できます。あいまいさが残る場合は、項目の種類名を使用して参照を限定できます。たとえば、% (ItemType.ItemMetaDataName) を指定できます。次の例では、Messageタスクを分割するには、メタデータを使用します。バッチ処理に項目メタデータを使用する方法の詳細については、「タスクのバッチの項目メタデータ」を参照してください。

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <Stuff Include="One.cs" >
            <Display>false</Display>
        </Stuff>
        <Stuff Include="Two.cs">
            <Display>true</Display>
        </Stuff>
    </ItemGroup>
    <Target Name="Batching">
        <Message Text="@(Stuff)" Condition=" '%(Display)' == 'true' "/>
    </Target>
</Project>

既知のアイテムメタデータ

項目の種類に追加した項目には、既知の項目メタデータがいくつか割り当てられます。たとえば、すべての項目に項目のファイル名を値で、既知のメタデータ %(Filename)があります。詳細については、「MSBuild 既知のアイテムメタデータ」を参照してください。

メタデータを使用して項目の種類の変換

新しい項目リストにメタデータを使用して項目リストを変換できます。たとえば、.objファイルの対応するリストに @(CppFiles -> '%(Filename).obj')式を使用して、.cppファイルを表す項目を含む項目の種類 CppFiles を変換できます。

次のコードは、Culture メタデータを持つすべての EmbeddedResource 項目のコピーを含む CultureResource 項目の種類を作成します。Culture メタデータの値が新しいメタデータ CultureResource.TargetDirectory の値になります。

<Target Name="ProcessCultureResources">
    <ItemGroup>
        <CultureResource Include="@(EmbeddedResource)"
            Condition="'%(EmbeddedResource.Culture)' != ''">
            <TargetDirectory>%(EmbeddedResource.Culture) </TargetDirectory>
        </CultureResource>
    </ItemGroup>
</Target>

詳細については、「MSBuild 変換」を参照してください。

項目定義

.NET Framework 3.5以降では、作業項目の種類に [ItemDefinitionGroup element]を使用して、既定のメタデータを追加できます。既知のメタデータのように、既定のメタデータは、指定した項目の種類に含まれるすべての項目に関連付けられます。明示的に項目定義の既定のメタデータをオーバーライドできます。たとえば、次のXMLでは Compile の項目「one.cs」と「three.cs」値「Monday」のメタデータ BuildDay できます。コードは項目「two.cs」に値「Tuesday」のメタデータ BuildDay を示します。

<ItemDefinitionGroup>
    <Compile>
        <BuildDay>Monday</BuildDay>
    </Compile>
</ItemDefinitionGroup>
<ItemGroup>
    <Compile Include="one.cs;three.cs" />
    <Compile Include="two.cs">
        <BuildDay>Tuesday</BuildDay>
    </Compile>
</ItemGroup>

詳細については、「項目定義」を参照してください。

ターゲットItemGroupの項目の属性

.NET Framework 3.5 以降では、項目要素を格納できる ItemGroup 要素を Target 要素に含めることができます。このセクションの属性は、ItemGroup で Targetにある項目に指定した場合に有効です。

属性の削除

ターゲットの ItemGroup の項目を項目の種類から特定の項目 (ファイル) を削除 Remove の属性が含まれる場合があります。この属性は.NET Framework 3.5で導入されました。

次の例では、Compile項目の種類からすべての.configファイルを削除します。

<Target>
    <ItemGroup>
        <Compile Remove="*.config"/>
    </ItemGroup>
</Target>

KeepMetadataの属性

項目がターゲット内に生成された場合、項目要素には KeepMetadata の属性を含めることができます。名前のセミコロン区切りのリストで指定するこの属性を指定する場合は、メタデータだけがソースの項目からターゲット項目に移動します。この属性に空の値は、指定したのと同じです。KeepMetadata の属性は.NET Framework 4.5で導入されました。

次の例に KeepMetadata の属性を使用する方法を示します。

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003"
ToolsVersion="4.0">

    <ItemGroup>
        <FirstItem Include="rhinoceros">
            <Class>mammal</Class>
            <Size>large</Size>
        </FirstItem>

    </ItemGroup>
    <Target Name="MyTarget">
        <ItemGroup>
            <SecondItem Include="@(FirstItem)" KeepMetadata="Class" />
        </ItemGroup>

        <Message Text="FirstItem: %(FirstItem.Identity)" />
        <Message Text="  Class: %(FirstItem.Class)" />
        <Message Text="  Size:  %(FirstItem.Size)"  />

        <Message Text="SecondItem: %(SecondItem.Identity)" />
        <Message Text="  Class: %(SecondItem.Class)" />
        <Message Text="  Size:  %(SecondItem.Size)"  />
    </Target>
</Project>

<!--
Output:
  FirstItem: rhinoceros
    Class: mammal
    Size:  large
  SecondItem: rhinoceros
    Class: mammal
    Size: 
-->

RemoveMetadataの属性

項目がターゲット内に生成された場合、項目要素には RemoveMetadata の属性を含めることができます。この属性を指定する場合は、すべてのメタデータは、ソースの項目の名前のセミコロン区切りのリストに含まれるメタデータを除くターゲット項目に移動します。この属性に空の値は、指定したのと同じです。RemoveMetadata の属性は.NET Framework 4.5で導入されました。

次の例に RemoveMetadata の属性を使用する方法を示します。

<Project ToolsVersion="4.0" xmlns="https://schemas.microsoft.com/developer/msbuild/2003">

    <PropertyGroup>
        <MetadataToRemove>Size;Material</MetadataToRemove>
    </PropertyGroup>

    <ItemGroup>
        <Item1 Include="stapler">
            <Size>medium</Size>
            <Color>black</Color>
            <Material>plastic</Material>
        </Item1>
    </ItemGroup>

    <Target Name="MyTarget">
        <ItemGroup>
            <Item2 Include="@(Item1)" RemoveMetadata="$(MetadataToRemove)" />
        </ItemGroup>

        <Message Text="Item1: %(Item1.Identity)" />
        <Message Text="  Size:     %(Item1.Size)" />
        <Message Text="  Color:    %(Item1.Color)" />
        <Message Text="  Material: %(Item1.Material)" />
        <Message Text="Item2: %(Item2.Identity)" />
        <Message Text="  Size:     %(Item2.Size)" />
        <Message Text="  Color:    %(Item2.Color)" />
        <Message Text="  Material: %(Item2.Material)" />
    </Target>
</Project>

<!--
Output: 
  Item1: stapler
    Size:     medium
    Color:    black
    Material: plastic
  Item2: stapler
    Size:     
    Color:    black
    Material: 
-->

KeepDuplicatesの属性

項目がターゲット内に生成された場合、項目要素には KeepDuplicates の属性を含めることができます。KeepDuplicates は、項目が既存の項目の正確な複製が項目は、ターゲットグループに追加するかどうかを指定する Boolean の属性です。

ソースとターゲットの項目が同じ値を異なるメタデータが含まれているが、項目は KeepDuplicatesfalseがに設定されている場合でも追加されます。この属性に空の値は、指定したのと同じです。KeepDuplicates の属性は.NET Framework 4.5で導入されました。

次の例に KeepDuplicates の属性を使用する方法を示します。

<Project ToolsVersion="4.0" xmlns="https://schemas.microsoft.com/developer/msbuild/2003">

    <ItemGroup>
        <Item1 Include="hourglass;boomerang" />
        <Item2 Include="hourglass;boomerang" />
    </ItemGroup>

    <Target Name="MyTarget">
        <ItemGroup>
            <Item1 Include="hourglass" KeepDuplicates="false" />
            <Item2 Include="hourglass" />
        </ItemGroup>

        <Message Text="Item1: @(Item1)" />
        <Message Text="  %(Item1.Identity)  Count: @(Item1->Count())" />
        <Message Text="Item2: @(Item2)" />
        <Message Text="  %(Item2.Identity)  Count: @(Item2->Count())" />
    </Target>
</Project>

<!--
Output: 
  Item1: hourglass;boomerang
    hourglass  Count: 1
    boomerang  Count: 1
  Item2: hourglass;boomerang;hourglass
    hourglass  Count: 2
    boomerang  Count: 1
-->

参照

次の方法で共有

MSBuild 項目

プロジェクトファイルでの項目の作成

実行時の項目の作成

プロジェクトファイルでの項目の参照

ワイルドカードの使用による項目の指定

Exclude 属性の使用

アイテムメタデータ

プロジェクトファイルでのアイテムメタデータの参照

既知のアイテムメタデータ

メタデータを使用して項目の種類の変換

項目定義

ターゲットItemGroupの項目の属性

属性の削除

KeepMetadataの属性

RemoveMetadataの属性

KeepDuplicatesの属性

参照

処理手順

関連項目

概念

その他の技術情報

その他のリソース

次の方法で共有

MSBuild 項目

プロジェクト ファイルでの項目の作成

実行時の項目の作成

プロジェクト ファイルでの項目の参照

ワイルドカードの使用による項目の指定

Exclude 属性の使用

アイテム メタデータ

プロジェクト ファイルでのアイテム メタデータの参照

既知のアイテム メタデータ

メタデータを使用して項目の種類の変換

項目定義

ターゲットItemGroupの項目の属性

属性の削除

KeepMetadataの属性

RemoveMetadataの属性

KeepDuplicatesの属性

参照

処理手順

関連項目

概念

その他の技術情報

その他のリソース

プロジェクトファイルでの項目の作成

プロジェクトファイルでの項目の参照

アイテムメタデータ

プロジェクトファイルでのアイテムメタデータの参照

既知のアイテムメタデータ