MSBuild 項目
項目はビルド システムへの入力であり、通常はファイルを表します。 項目はその要素名に基づいて項目の種類にグループ化されます。 項目の種類は項目の名前付きリストであり、タスクのパラメーターとして使用できます。 タスクは項目値を使用して、ビルド処理のステップを実行します。
項目名はそれぞれが属する項目の種類によって指定されるため、"項目" と "項目値" という用語は同義です。
プロジェクト ファイルでの項目の作成
項目は、プロジェクト ファイル内で 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>
実行時の項目の作成
Target 要素の外側にある項目には、ビルドの評価フェーズで値が割り当てられます。 その後の実行フェーズで項目を作成または変更するには、次のようにします。
項目はどのタスクででも生成できます。 項目を生成するには、Task 要素の子要素として、ItemName 属性を持つ Output 要素を定義する必要があります。
項目は CreateItem タスクによって生成できます。 この使用法は推奨されていません。
.NET Framework 3.5 以降では、項目要素を格納できる ItemGroup 要素を Target 要素に含めることができます。
プロジェクト ファイルでの項目の参照
プロジェクト ファイルで項目の種類を参照するには、@(ItemType) という構文を使用します。 たとえば、前の例に示した項目の種類を参照するには、@(Compile) と記述します。 この構文を使用すると、項目の種類をタスクのパラメーターとして指定して、項目をそのタスクに渡すことができます。 詳細については、「方法: ビルドするファイルを選択する」を参照してください。
既定では、項目の種類に含まれる項目は、展開時にセミコロン (;) で区切られます。 既定以外の区切り記号を指定するには、構文 @(ItemType, 'separator') を使用します。 詳細については、「方法: 項目リストをコンマ区切りで表示する」を参照してください。
ワイルドカードの使用による項目の指定
**、*、および ? の 各ワイルドカードを使用すると、各ファイルを個別にリストする代わりに、ファイルのグループをビルドの入力として指定できます。
? ワイルドカード文字は 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 属性によって追加された項目のみに作用します。 次に例を示します。
<Compile Include="*.cs" />
<Compile Include="*.res" Exclude="Form1.cs">
この例では、Form1.cs ファイルは前の項目要素で追加されているため、除外されません。
詳細については、「方法: ビルドからファイルを除外する」を参照してください。
Remove 属性の使用
.NET Framework 3.5 以降では、項目要素を格納できる ItemGroup 要素を Target 要素に含めることができます。 これらの項目要素には、Remove 属性を含めることができます。この属性は、特定の項目 (ファイル) を項目の種類から削除します。 たとえば、次の XML は、Compile 項目の種類からすべての .config ファイルを削除します。
<Target>
<ItemGroup>
<Compile Remove="*.config"/>
</ItemGroup>
</Target>
アイテム メタデータ
項目には、Include および Exclude 属性から収集した情報に加えて、メタデータが含まれます。 このメタデータは、項目に関する詳細情報を必要とするタスクで使用できるほか、タスクおよびターゲットのバッチ処理にも使用できます。 バッチ処理の詳細については、「MSBuild バッチ」を参照してください。
メタデータとは、プロジェクト ファイル内で項目要素の子要素として宣言された、キーと値のペアのコレクションです。 子要素の名前がメタデータの名前になり、子要素の値がメタデータの値になります。
メタデータは、それを含む項目要素に関連付けられます。 たとえば、次の XML は、CSFile 項目の種類に含まれる "one.cs" と "two.cs" の両方の項目に、Fr を値として持つ Culture メタデータを追加します。
<ItemGroup>
<CSFile Include="one.cs;two.cs">
<Culture>Fr</Culture>
</CSFile>
</ItemGroup>
項目には 0 以上のメタデータ値を指定できます。 メタデータ値はいつでも変更できます。 メタデータを空の値に設定すると、実質的にそのメタデータはビルドから削除されます。
プロジェクト ファイルでのアイテム メタデータの参照
プロジェクト ファイルで項目メタデータを参照するには、%(ItemMetadataName) という構文を使用します。 あいまいさが存在する場合、これは %(ItemType.ItemMetaDataName) のように項目の種類の名前を使用して修飾できます。次の例では、Display メタデータを使用して 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 既知のアイテム メタデータ」を参照してください。
メタデータを使用した項目の種類の変換
メタデータを使用して、既存の項目リストを新しい項目リストに変換できます。 たとえば、.cpp ファイルを表す項目を含む項目の種類 CppFiles を .obj ファイルの対応するリストに変換するには、@(CppFiles -> '%(Filename).obj') という式を使用します。
次のコードは、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 要素を使用して、任意の項目の種類に既定のメタデータを追加できます。 既知のメタデータと同様に、既定のメタデータも、指定された項目の種類に含まれるすべての項目に関連付けられます。 既定のメタデータは、項目定義を使用して明示的にオーバーライドできます。 たとえば、次の XML では、Compile の項目 "one.cs" と "three.cs" のメタデータ BuildDay の値は "Monday" になり、項目 "two.cs" のメタデータ BuildDay の値は "Tuesday" になります。
<ItemDefinitionGroup>
<Compile>
<BuildDay>Monday</BuildDay>
</Compile>
</ItemDefinitionGroup>
<ItemGroup>
<Compile Include="one.cs;three.cs" />
<Compile Include="two.cs">
<BuildDay>Tuesday</BuildDay>
</Compile>
</ItemGroup>
詳細については、「項目定義」を参照してください。