MSBuild 項目MSBuild Items

MSBuild 項目はビルド システムへの入力であり、通常はファイルを表します。MSBuild items are inputs into the build system, and they typically represent files. 項目は要素名に基づいてアイテムの種類にグループ化されます。Items are grouped into item types based on their element names. 項目の種類は項目の名前付きリストであり、タスクのパラメーターとして使用できます。Item types are named lists of items that can be used as parameters for tasks. タスクは項目値を使用して、ビルド処理のステップを実行します。The tasks use the item values to perform the steps of the build process.

項目名はそれぞれが属するアイテムの種類によって指定されるため、「項目」と「項目値」という用語は同義です。Because items are named by the item type to which they belong, the terms "item" and "item value" can be used interchangeably.

このトピックの内容In this topic

プロジェクト ファイルに項目を作成するCreating Items in a Project File

プロジェクト ファイル内で、ItemGroup 要素の子要素として項目を宣言します。You declare items in the project file as child elements of an ItemGroup element. 子要素の名前は、アイテムの種類です。The name of the child element is the type of the item. 要素の Include 属性は、そのアイテムの種類に組み込まれる項目 (ファイル) を指定します。The Include attribute of the element specifies the items (files) to be included with that item type. たとえば、次の XML では、Compile という名前のアイテムの種類を作成し、2 つのファイルを含めています。For example, the following XML creates an item type that's named Compile, which includes two files.

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

項目 "file2.cs" で項目 "file1.cs" が置き換えられるのではなく、このファイル名がアイテムの種類 Compile の値のリストに付加されます。The item "file2.cs" doesn't replace the item "file1.cs"; instead, the file name is appended to the list of values for the Compile item type. ビルドの評価フェーズでアイテムの種類から項目を削除することはできません。You can't remove an item from an item type during the evaluation phase of a build.

次の XML では、両方のファイルを 1 つの Include 属性で宣言することで、同じアイテムの種類を作成しています。The following XML creates the same item type by declaring both files in one Include attribute. ファイル名はセミコロンで区切られます。Notice that the file names are separated by a semicolon.

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

実行時に項目を作成するCreating Items During Execution

Target 要素の外側にある項目には、ビルドの評価フェーズで値が割り当てられます。Items that are outside Target elements are assigned values during the evaluation phase of a build. その後の実行フェーズで、次のようにして項目を作成または変更できます。During the subsequent execution phase, items can be created or modified in the following ways:

  • どのタスクも項目を生成できます。Any task can emit an item. 項目を生成するには、Task 要素の子要素として、ItemName 属性を持つ Output 要素が必要です。To emit an item, the Task element must have a child Output element that has an ItemName attribute.

  • CreateItem タスクは、項目を生成できます。The CreateItem task can emit an item. この使用法は推奨されていません。This usage is deprecated.

  • .NET Framework 3.5 以降では、項目要素を格納できる ItemGroup 要素を Target 要素に含めることができます。Starting in the .NET Framework 3.5, Target elements may contain ItemGroup elements that may contain item elements.

プロジェクト ファイルの項目を参照するReferencing Items in a Project File

プロジェクト ファイルでアイテムの種類を参照するには、構文 @(ItemType) を使用します。To reference item types throughout the project file, you use the syntax @(ItemType). たとえば、前の例に挙げたアイテムの種類を参照するには、@(Compile) を使用します。For example, you would reference the item type in the previous example by using @(Compile). この構文を使用してアイテムの種類をタスクのパラメーターとして指定すれば、項目をそのタスクに渡すことができます。By using this syntax, you can pass items to tasks by specifying the item type as a parameter of that task. 詳細については、「方法: ビルドするファイルを選択する」を参照してください。For more information, see How to: Select the Files to Build.

既定では、アイテムの種類の項目は、それが展開されるときにセミコロン (;) によって区切られます。By default, the items of an item type are separated by semicolons (;) when it's expanded. 構文 @(ItemType, 'separator') を使用して、既定以外の区切り記号を指定できます。You can use the syntax @(ItemType, 'separator') to specify a separator other than the default. 詳細については、「方法: 項目リストをコンマ区切りで表示する」を参照してください。For more information, see How to: Display an Item List Separated with Commas.

ワイルドカードを使用して項目を指定するUsing Wildcards to Specify Items

**、*、および ?You can use the **, *, and ? をワイルドカード文字として使用して、各ファイルを個別にリストする代わりに、ファイルのグループをビルドの入力として指定できます。wildcard characters to specify a group of files as inputs for a build instead of listing each file separately.

  • ?The ? ワイルドカード文字は単一の文字と一致します。wildcard character matches a single character.

  • * ワイルドカード文字は 0 個以上の文字と一致します。The * wildcard character matches zero or more characters.

  • ** ワイルドカード文字のシーケンスはパスの一部と一致します。The ** wildcard character sequence matches a partial path.

    たとえば、プロジェクト ファイルで次の要素を使用して、プロジェクト ファイルが格納されているディレクトリ内のすべての .cs ファイルを指定できます。For example, you can specify all the .cs files in the directory that contains the project file by using the following element in your project file.

<CSFile Include="*.cs"/>  

次の要素は D: ドライブのすべての .vb ファイルを選択します。The following element selects all .vb files on the D: drive:

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

ワイルドカード文字の詳細については、「方法: ビルドするファイルを選択する」を参照してください。For more information about wildcard characters, see How to: Select the Files to Build.

Exclude 属性を使用するUsing the Exclude Attribute

項目の要素には Exclude 属性を含めることができます。この属性は、アイテムの種類から特定の項目 (ファイル) を除外します。Item elements can contain the Exclude attribute, which excludes specific items (files) from the item type. Exclude 属性は通常、ワイルドカード文字と一緒に使用されます。The Exclude attribute is typically used together with wildcard characters. たとえば、次の XML は、DoNotBuild.cs ファイルを除き、ディレクトリのすべての .cs ファイルをアイテムの種類 CSFile に追加します。For example, the following XML adds every .cs file in the directory to the CSFile item type, except the DoNotBuild.cs file.

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

Exclude 属性は、同一の項目要素内にある Include 属性によって追加された項目のみに作用します。The Exclude attribute affects only the items that are added by the Include attribute in the item element that contains them both. 次の例では、Form1.cs ファイルは前の項目要素で追加されているため、除外されません。The following example wouldn't exclude the file Form1.cs, which was added in the preceding item element.

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

詳細については、「方法: ビルドからファイルを除外する」を参照してください。For more information, see How to: Exclude Files from the Build.

項目メタデータItem Metadata

項目には、Include および Exclude 属性の情報に加えて、メタデータを含めることができます。Items may contain metadata in addition to the information in the Include and Exclude attributes. このメタデータは、項目に関する詳細情報を必要とするタスクで使用できます。あるいは、タスクとターゲットをバッチ処理するために使用できます。This metadata can be used by tasks that require more information about the items or to batch tasks and targets. 詳細については、「MSBuild バッチ」を参照してください。For more information, see Batching.

メタデータは、項目の要素の子要素としてプロジェクト ファイルで宣言されているキーと値のペアのコレクションです。Metadata is a collection of key-value pairs that are declared in the project file as child elements of an item element. 子要素の名前はメタデータの名前であり、子要素の値はメタデータの値です。The name of the child element is the name of the metadata, and the value of the child element is the value of the metadata.

メタデータは、それが含まれる項目要素に関連付けられています。The metadata is associated with the item element that contains it. たとえば、次の XML は、値 Fr を持つ Culture メタデータを、アイテムの種類 CSFile の "one.cs" と "two.cs" の両方の項目に追加します。For example, the following XML adds Culture metadata that has the value Fr to both the "one.cs" and the "two.cs" items of the CSFile item type.

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

項目には 0 以上のメタデータ値を指定できます。An item can have zero or more metadata values. メタデータの値は、いつでも変更できます。You can change metadata values at any time. メタデータを空の値に設定すると、実質的にはビルドからメタデータが削除されます。If you set metadata to an empty value, you effectively remove it from the build.

プロジェクト ファイルで項目メタデータを参照するReferencing Item Metadata in a Project File

プロジェクト ファイルで項目のメタデータを参照するには、%(ItemMetadataName) という構文を使用します。You can reference item metadata throughout the project file by using the syntax %(ItemMetadataName). あいまいさが存在する場合は、アイテムの種類の名前を使用して参照を修飾できます。If ambiguity exists, you can qualify a reference by using the name of the item type. たとえば、%(ItemType.ItemMetaDataName) と指定できます。次の例では、Display メタデータを使用して Message タスクをバッチ処理します。For example, you can specify %(ItemType.ItemMetaDataName).The following example uses the Display metadata to batch the Message task. バッチ処理のために項目のメタデータを使用する方法の詳細については、「タスクのバッチの項目メタデータ」を参照してください。For more information about how to use item metadata for batching, see Item Metadata in Task Batching.

<Project xmlns="http://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>  

既知の項目メタデータWell-known Item Metadata

アイテムの種類に追加した項目には、既知のメタデータが割り当てられます。When an item is added to an item type, that item is assigned some well-known metadata. たとえば、すべての項目には既知のメタデータ %(Filename) があり、その値は項目のファイル名です。For example, all items have the well-known metadata %(Filename), whose value is the file name of the item. 詳細については、「既知の項目メタデータ」を参照してください。For more information, see Well-known Item Metadata.

メタデータを使用してアイテムの種類を変換するTransforming Item Types By Using Metadata

メタデータを使用して、項目リストを新しい項目リストに変換できます。You can transform item lists into new item lists by using metadata. たとえば、式 @(CppFiles -> '%(Filename).obj') を使用すると、.cpp ファイルを表す項目を持つアイテムの種類 CppFiles を、.obj ファイルの対応するリストに変換できます。For example, you can transform an item type CppFiles that has items that represent .cpp files into a corresponding list of .obj files by using the expression @(CppFiles -> '%(Filename).obj').

次のコードでは CultureResource というアイテムの種類を作成し、Culture メタデータを持つすべての EmbeddedResource 項目のコピーをそこに含めます。The following code creates a CultureResource item type that contains copies of all EmbeddedResource items with Culture metadata. Culture メタデータの値は、新しいメタデータ CultureResource.TargetDirectory の値になります。The Culture metadata value becomes the value of the new metadata CultureResource.TargetDirectory.

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

詳細については、「MSBuild 変換」を参照してください。For more information, see Transforms.

項目定義Item Definitions

.NET Framework 3.5 以降、ItemDefinitionGroup 要素を使用して、既定のメタデータをアイテムの種類に追加できるようになりました。Starting in the .NET Framework 3.5, you can add default metadata to any item type by using the ItemDefinitionGroup element. 既知のメタデータと同様に、既定のメタデータも、指定するアイテムの種類に含まれるすべての項目に関連付けられます。Like well-known metadata, the default metadata is associated with all items of the item type that you specify. 既定のメタデータは、項目定義で明示的にオーバーライドできます。You can explicitly override default metadata in an item definition. たとえば、次の XML は Compile の項目 "one.cs" および "three.cs" に、"Monday" という値を持つメタデータ BuildDay を指定します。For example, the following XML gives the Compile items "one.cs" and "three.cs" the metadata BuildDay with the value "Monday". コードは項目 "two.cs" に、値 "Tuesday" を持つメタデータ BuildDay を指定します。The code gives the item "two.cs" the metadata BuildDay with the value "Tuesday".

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

詳細については、「項目定義」を参照してください。For more information, see Item Definitions.

Target の ItemGroup の項目の属性Attributes for Items in an ItemGroup of a Target

.NET Framework 3.5 以降では、項目要素を格納できる ItemGroup 要素を Target 要素に含めることができます。Starting in the .NET Framework 3.5, Target elements may contain ItemGroup elements that may contain item elements. このセクションの属性は、Target にある ItemGroup の項目に指定されている場合に有効です。The attributes in this section are valid when they are specified for an item in an ItemGroup that's in a Target.

Remove 属性Remove Attribute

ターゲットの ItemGroup の項目には Remove 属性を含めることができます。この属性は、アイテムの種類から特定の項目 (ファイル) を削除します。Items in an ItemGroup of a target may contain the Remove attribute, which removes specific items (files) from the item type. この属性は、.NET Framework 3.5 で導入されました。This attribute was introduced in the .NET Framework 3.5.

次の例では、アイテムの種類 Compile からすべての .config ファイルを削除します。The following example removes every .config file from the Compile item type.

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

KeepMetadata 属性KeepMetadata Attribute

ターゲット内に項目が生成される場合、項目要素に KeepMetadata 属性を含めることができます。If an item is generated within a target, the item element can contain the KeepMetadata attribute. この属性が指定される場合、セミコロン区切りの名前リストで指定されているメタデータのみがソース項目からターゲット項目に転送されます。If this attribute is specified, only the metadata that is specified in the semicolon-delimited list of names will be transferred from the source item to the target item. この属性に空の値を指定することは、値を指定しないことと同じです。An empty value for this attribute is equivalent to not specifying it. KeepMetadata 属性は、.NET Framework 4.5 で導入されました。The KeepMetadata attribute was introduced in the .NET Framework 4.5.

次の例は、KeepMetadata 属性を使用する方法を示しています。The following example illustrates how to use the KeepMetadata attribute.

<Project xmlns="http://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 Attribute

ターゲット内に項目が生成される場合、項目要素に RemoveMetadata 属性を含めることができます。If an item is generated within a target, the item element can contain the RemoveMetadata attribute. この属性が指定される場合、名前がセミコロン区切りの名前リストに含まれているメタデータを除いて、すべてのメタデータがソース項目からターゲット項目に転送されます。If this attribute is specified, all metadata is transferred from the source item to the target item except metadata whose names are contained in the semicolon-delimited list of names. この属性に空の値を指定することは、値を指定しないことと同じです。An empty value for this attribute is equivalent to not specifying it. RemoveMetadata 属性は、.NET Framework 4.5 で導入されました。The RemoveMetadata attribute was introduced in the .NET Framework 4.5.

次の例は、RemoveMetadata 属性を使用する方法を示しています。The following example illustrates how to use the RemoveMetadata attribute.

<Project ToolsVersion="4.0" xmlns="http://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 Attribute

ターゲット内に項目が生成される場合、項目要素に KeepDuplicates 属性を含めることができます。If an item is generated within a target, the item element can contain the KeepDuplicates attribute. KeepDuplicates は、項目が既存の項目の完全な複製である場合に、項目をターゲット グループに追加するかどうかを指定する Boolean 属性です。KeepDuplicates is a Boolean attribute that specifies whether an item should be added to the target group if the item is an exact duplicate of an existing item.

ソースとターゲットの項目の Include 値が同じでメタデータが異なる場合、KeepDuplicatesfalse に設定されていても項目は追加されます。If the source and target item have the same Include value but different metadata, the item is added even if KeepDuplicates is set to false. この属性に空の値を指定することは、値を指定しないことと同じです。An empty value for this attribute is equivalent to not specifying it. KeepDuplicates 属性は、.NET Framework 4.5 で導入されました。The KeepDuplicates attribute was introduced in the .NET Framework 4.5.

次の例は、KeepDuplicates 属性を使用する方法を示しています。The following example illustrates how to use the KeepDuplicates attribute.

<Project ToolsVersion="4.0" xmlns="http://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  
-->  

関連項目See Also

MSBuild の概念MSBuild Concepts
MSBuild MSBuild
方法: ビルドするファイルを選択する How to: Select the Files to Build
方法: ビルドからファイルを除外する How to: Exclude Files from the Build
方法: 項目リストをコンマ区切りで表示する How to: Display an Item List Separated with Commas
項目定義 Item Definitions
バッチ Batching
Item 要素 (MSBuild)Item Element (MSBuild)