MSBuild 項目はビルド システムへの入力であり、通常はファイルを表します (ファイルは Include 属性で指定されます)。 項目は、要素名に基づいて項目の種類にグループ化されます。 項目の種類は、タスクのパラメーターとして使用できる項目の名前付きリストです。 タスクでは、項目の値を使用してビルド プロセスの手順を実行します。
アイテムは属するアイテムの種類によって名前が付けられるため、"item" と "item value" という用語を同じ意味で使用できます。
プロジェクト ファイルに項目を作成する
プロジェクト ファイル内の項目は 、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>
Include属性は、.targets ファイルなどのインポートされたファイル内にある場合でも、$(MSBuildProjectPath)プロジェクト ファイルのフォルダーを基準にして解釈されるパスです。
実行中にアイテムを作成する
ターゲット要素の外部にある項目には、ビルドの評価フェーズ中に値が割り当てられます。 後続の実行フェーズでは、次の方法で項目を作成または変更できます。
どのタスクでも項目を出力できます。 項目を出力するには、Task 要素に、
ItemName属性を持つ子 Output 要素が必要です。CreateItem タスクは項目を出力できます。 この使用は非推奨です。
Target要素には、項目要素を含む ItemGroup 要素を含めることができます。
プロジェクト ファイル内の参照項目
プロジェクト ファイル全体で項目の種類を参照するには、構文 @(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属性は、両方を含む item 要素のInclude属性によって追加された項目にのみ影響します。 次の例では、前の item 要素に追加されたファイル Form1.csは除外されません。
<Compile Include="*.cs" />
<Compile Include="*.res" Exclude="Form1.cs">
詳細については、「 方法: ビルドからファイルを除外する」を参照してください。
項目のメタデータ
項目には、 Include および Exclude 属性の情報に加えてメタデータが含まれる場合があります。 このメタデータは、アイテムに関する詳細情報を必要とするタスクや、タスクとターゲットをバッチ処理するタスクで使用できます。 詳細については、「バッチ処理 を参照してください。
メタデータは、項目要素の子要素としてプロジェクト ファイルで宣言されているキーと値のペアのコレクションです。 子要素の名前はメタデータの名前であり、子要素の値はメタデータの値です。
メタデータは、メタデータを含む項目要素に関連付けられます。 たとえば、次の 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>
<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)があり、その値はアイテムのファイル名 (拡張子なし) です。 詳細については、「 既知の項目メタデータ」を参照してください。
メタデータを使用して項目の種類を変換する
メタデータを使用して、項目リストを新しい項目リストに変換できます。 たとえば、式@(CppFiles -> '%(Filename).obj')を使用して、.cpp ファイルを表す項目を含む項目の種類CppFilesを、対応する.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 項目の関数 と 変換に関する説明を参照してください。
項目の定義
ItemDefinitionGroup 要素を使用して、任意の項目の種類に既定のメタデータを追加できます。 既知のメタデータと同様に、既定のメタデータは、指定した項目の種類のすべての項目に関連付けられます。 項目定義の既定のメタデータを明示的にオーバーライドできます。 たとえば、次の XML では、Compile項目がone.csされ、メタデータBuildDay値が "Monday" でthree.csされます。 このコードは、メタデータ 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 内のアイテムの属性
Target 要素には、項目要素を含む ItemGroup 要素を含めることができます。 このセクションの属性は、Target内のItemGroup内の項目に対して属性が指定されている場合に有効です。
属性の削除
Remove属性は、アイテムの種類から特定のアイテム (ファイル) を削除します。 この属性は、.NET Framework 3.5 で導入されました (ターゲット内のみ)。 MSBuild 15.0 以降では、内部ターゲットと外部ターゲットの両方がサポートされています。
次の例では、Compile項目の種類からすべての.config ファイルを削除します。
<Target>
<ItemGroup>
<Compile Remove="*.config"/>
</ItemGroup>
</Target>
MatchOnMetadata 属性
MatchOnMetadata属性は、他の項目 (Remove="@(Compile);@(Content)" など) を参照するRemove属性にのみ適用され、項目値に基づいて一致するのではなく、指定したメタデータ名の値に基づいて項目を照合するようにRemove操作に指示します。
B Remove="@(A)" MatchOnMetadata="M"の照合ルール: メタデータMを持つBからすべてのアイテムを削除します。メタデータ値 VMのメタデータ値は、VのメタデータMを持つAの項目と一致します。
<Project>
<ItemGroup>
<A Include='a1' M1='1' M2='a' M3="e"/>
<A Include='b1' M1='2' M2='x' M3="f"/>
<A Include='c1' M1='3' M2='y' M3="g"/>
<A Include='d1' M1='4' M2='b' M3="h"/>
<B Include='a2' M1='x' m2='c' M3="m"/>
<B Include='b2' M1='2' m2='x' M3="n"/>
<B Include='c2' M1='2' m2='x' M3="o"/>
<B Include='d2' M1='3' m2='y' M3="p"/>
<B Include='e2' M1='3' m2='Y' M3="p"/>
<B Include='f2' M1='4' M3="r"/>
<B Include='g2' M3="s"/>
<B Remove='@(A)' MatchOnMetadata='M1;M2'/>
</ItemGroup>
<Target Name="PrintEvaluation">
<Message Text="%(B.Identity) M1='%(B.M1)' M2='%(B.M2)' M3='%(B.M3)'" />
</Target>
</Project>
この例では、項目の値 b2、 c2、および d2 は、次の理由で項目 B から削除されます。
-
b2M1=2BAからのb1との試合からc2M2=x -
d2M1=3のAからのc1に対するBマッチからM2=y
Message タスクは、次のように出力します。
a2 M1='x' M2='c' M3='m'
e2 M1='3' M2='Y' M3='p'
f2 M1='4' M2='' M3='r'
g2 M1='' M2='' M3='s'
MSBuild からのMatchOnMetadataの使用例:
<_TransitiveItemsToCopyToOutputDirectory Remove="@(_ThisProjectItemsToCopyToOutputDirectory)" MatchOnMetadata="TargetPath" MatchOnMetadataOptions="PathLike" />
この行は、同じTargetPathメタデータ値を持つ_TransitiveItemsToCopyToOutputDirectoryから項目を削除します。_ThisProjectItemsToCopyToOutputDirectory
MatchOnMetadataOptions 属性
項目間でメタデータ値を照合するために MatchOnMetadata で使用される文字列照合戦略を指定します (メタデータ名は常に大文字と小文字が区別されません)。 使用可能な値は、 CaseSensitive、 CaseInsensitive、または PathLikeです。 既定値は CaseSensitive です。
PathLike は、スラッシュの向きの正規化、末尾のスラッシュの無視、 . と ..の排除、現在のディレクトリに対するすべての相対パスの絶対パスの作成などの値にパス対応正規化を適用します。
KeepMetadata 属性
ターゲット内で項目が生成された場合、item 要素には KeepMetadata 属性を含めることができます。 この属性を指定すると、セミコロンで区切られた名前の一覧で指定されたメタデータのみが、ソースアイテムからターゲットアイテムに転送されます。 この属性の空の値は、指定しないのと同じです。
KeepMetadata属性は.NET Framework 4.5 で導入されました。
次の例は、 KeepMetadata 属性の使用方法を示しています。
<Project>
<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 属性
ターゲット内で項目が生成された場合、item 要素には RemoveMetadata 属性を含めることができます。 この属性を指定すると、名前のセミコロン区切りリストに名前が含まれているメタデータを除き、すべてのメタデータがソース項目からターゲット項目に転送されます。 この属性の空の値は、指定しないのと同じです。
RemoveMetadata属性は.NET Framework 4.5 で導入されました。
次の例は、 RemoveMetadata 属性の使用方法を示しています。
<Project>
<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:
-->
項目に対するその他の操作については、 MSBuild 項目関数を参照してください。
KeepDuplicates 属性
ターゲット内で項目が生成された場合、item 要素には KeepDuplicates 属性を含めることができます。
KeepDuplicates は Boolean 属性で、項目が既存の項目と完全に重複している場合に、対象グループに項目を追加するかどうかを指定します。
ソースアイテムとターゲットアイテムが同じ Include 値を持ち、メタデータが異なる場合、 KeepDuplicates が falseに設定されている場合でも項目が追加されます。 この属性の空の値は、指定しないのと同じです。
KeepDuplicates属性は.NET Framework 4.5 で導入されました。
次の例は、 KeepDuplicates 属性の使用方法を示しています。
<Project>
<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
-->
KeepDuplicates属性は項目の値に加えて項目のメタデータを考慮するため、メタデータで何が起こっているかを把握することが重要です。 たとえば、 メタデータ項目関数を使用する場合の重複の検出を参照してください。
ターゲットの外部にある ItemGroup 内のアイテムのメタデータを更新する
ターゲットの外部にある項目は、 Update 属性を使用して既存のメタデータを更新できます。 この属性は、ターゲットの項目 では使用できません 。
<Project>
<PropertyGroup>
<MetadataToUpdate>pencil</MetadataToUpdate>
</PropertyGroup>
<ItemGroup>
<Item1 Include="stapler">
<Size>medium</Size>
<Color>black</Color>
<Material>plastic</Material>
</Item1>
<Item1 Include="pencil">
<Size>small</Size>
<Color>yellow</Color>
<Material>wood</Material>
</Item1>
<Item1 Include="eraser">
<Color>red</Color>
</Item1>
<Item1 Include="notebook">
<Size>large</Size>
<Color>white</Color>
<Material>paper</Material>
</Item1>
<Item2 Include="notebook">
<Size>SMALL</Size>
<Color>YELLOW</Color>
</Item2>
<!-- Metadata can be expressed either as attributes or as elements -->
<Item1 Update="$(MetadataToUpdate);stapler;er*r;@(Item2)" Price="10" Material="">
<Color>RED</Color>
</Item1>
</ItemGroup>
<Target Name="MyTarget">
<Message Text="Item1: %(Item1.Identity)
Size: %(Item1.Size)
Color: %(Item1.Color)
Material: %(Item1.Material)
Price: %(Item1.Price)" />
</Target>
</Project>
<!--
Item1: stapler
Size: medium
Color: RED
Material:
Price: 10
Item1: pencil
Size: small
Color: RED
Material:
Price: 10
Item1: eraser
Size:
Color: RED
Material:
Price: 10
Item1: notebook
Size: large
Color: RED
Material:
Price: 10
-->
MSBuild バージョン 16.6 以降では、 Update 属性は、2 つ以上の項目からのメタデータのインポートを容易にするために、修飾されたメタデータ参照をサポートしています。
<Project>
<ItemGroup>
<Item1 Include="stapler">
<Size>medium</Size>
<Color>black</Color>
<Material>plastic</Material>
</Item1>
<Item1 Include="pencil">
<Size>small</Size>
<Color>yellow</Color>
<Material>wood</Material>
</Item1>
<Item1 Include="eraser">
<Size>small</Size>
<Color>red</Color>
<Material>gum</Material>
</Item1>
<Item1 Include="notebook">
<Size>large</Size>
<Color>white</Color>
<Material>paper</Material>
</Item1>
<Item2 Include="pencil">
<Size>MEDIUM</Size>
<Color>RED</Color>
<Material>PLASTIC</Material>
<Price>10</Price>
</Item2>
<Item3 Include="notebook">
<Size>SMALL</Size>
<Color>BLUE</Color>
<Price>20</Price>
</Item3>
<!-- Metadata can be expressed either as attributes or as elements -->
<Item1 Update="@(Item2);er*r;@(Item3)" Size="%(Size)" Color="%(Item2.Color)" Price="%(Item3.Price)" Model="2020">
<Material Condition="'%(Item2.Material)' != ''">Premium %(Item2.Material)</Material>
</Item1>
</ItemGroup>
<Target Name="MyTarget">
<Message Text="Item1: %(Item1.Identity)
Size: %(Item1.Size)
Color: %(Item1.Color)
Material: %(Item1.Material)
Price: %(Item1.Price)
Model: %(Item1.Model)" />
</Target>
</Project>
<!--
Item1: stapler
Size: medium
Color: black
Material: plastic
Price:
Model:
Item1: pencil
Size: small
Color: RED
Material: Premium PLASTIC
Price:
Model: 2020
Item1: eraser
Size: small
Color:
Material: gum
Price:
Model: 2020
Item1: notebook
Size: large
Color:
Material: paper
Price: 20
Model: 2020
-->
備考：
- 修飾されていないメタデータ (
%(MetadataName)) は、更新されるアイテムの種類にバインドされます (上記の例Item1)。 修飾されたメタデータ (%(Item2.Color)) は、Update 式からキャプチャされた一致する項目の種類のセット内でバインドされます。 - 1 つのアイテムが複数の参照先アイテム内と複数の参照先アイテムの間で複数回一致する場合:
- 参照される各アイテムの種類の最後の出現箇所がキャプチャされます (したがって、項目の種類ごとに 1 つのキャプチャされた項目)。
- これは、ターゲットでのタスク 項目のバッチ処理の動作と一致します。
- %() 参照を配置できる場所:
- メタデータ
- メタデータの条件
- メタデータ名の照合では、大文字と小文字が区別されません。
ターゲットの ItemGroup 内のアイテムのメタデータの更新
メタデータは、 Updateよりも表現力の低い構文によって、ターゲット内でも変更できます。
<Project>
<ItemGroup>
<Item1 Include="stapler">
<Size>medium</Size>
<Color>black</Color>
<Material>plastic</Material>
</Item1>
<Item1 Include="pencil">
<Size>small</Size>
<Color>yellow</Color>
<Material>wood</Material>
</Item1>
<Item1 Include="eraser">
<Size>small</Size>
<Color>red</Color>
<Material>gum</Material>
</Item1>
<Item1 Include="notebook">
<Size>large</Size>
<Color>white</Color>
<Material>paper</Material>
</Item1>
<Item2 Include="pencil">
<Size>MEDIUM</Size>
<Color>RED</Color>
<Material>PLASTIC</Material>
<Price>10</Price>
</Item2>
<Item2 Include="ruler">
<Color>GREEN</Color>
</Item2>
</ItemGroup>
<Target Name="MyTarget">
<ItemGroup>
<!-- Metadata can be expressed either as attributes or as elements -->
<Item1 Size="GIGANTIC" Color="%(Item2.Color)">
<Material Condition="'%(Item2.Material)' != ''">Premium %(Item2.Material)</Material>
</Item1>
</ItemGroup>
<Message Text="Item1: %(Item1.Identity)
Size: %(Item1.Size)
Color: %(Item1.Color)
Material: %(Item1.Material)
Price: %(Item1.Price)
Model: %(Item1.Model)" />
</Target>
</Project>
<!--
Item1: stapler
Size: GIGANTIC
Color: GREEN
Material: Premium PLASTIC
Price:
Model:
Item1: pencil
Size: GIGANTIC
Color: GREEN
Material: Premium PLASTIC
Price:
Model:
Item1: eraser
Size: GIGANTIC
Color: GREEN
Material: Premium PLASTIC
Price:
Model:
Item1: notebook
Size: GIGANTIC
Color: GREEN
Material: Premium PLASTIC
Price:
Model:
-->