Item MSBuild
Item MSBuild adalah input ke dalam sistem build, dan biasanya mewakili file (file ditentukan dalam Include
atribut ). Item dikelompokkan ke dalam jenis item berdasarkan nama elemennya. Jenis item diberi nama daftar item yang dapat digunakan sebagai parameter untuk tugas. Tugas menggunakan nilai item untuk melakukan langkah-langkah proses build.
Karena item dinamai oleh jenis item tempat item tersebut berada, istilah "item" dan "nilai item" dapat digunakan secara bergantian.
Membuat item dalam file proyek
Anda mendeklarasikan item dalam file proyek sebagai elemen turunan dari elemen ItemGroup. Nama item yang valid dimulai dengan huruf besar atau huruf kecil atau garis bawah (_
); karakter berikutnya yang valid termasuk karakter alfanumerik (huruf atau digit), garis bawah, dan tanda hubung (-
). Nama elemen turunan adalah jenis item. Atribut Include
elemen menentukan item (file) yang akan disertakan dengan jenis item tersebut. Misalnya, kode berikut membuat jenis item bernama Compile
, yang mencakup dua file.
<ItemGroup>
<Compile Include = "file1.cs"/>
<Compile Include = "file2.cs"/>
</ItemGroup>
File item2.cs tidak menggantikan item file1.cs; sebagai gantinya, nama file ditambahkan ke daftar nilai untuk Compile
jenis item.
XML berikut membuat jenis item yang sama dengan mendeklarasikan kedua file dalam satu Include
atribut. Perhatikan bahwa nama file dipisahkan oleh titik koma.
<ItemGroup>
<Compile Include = "file1.cs;file2.cs"/>
</ItemGroup>
Atribut Include
adalah jalur yang ditafsirkan relatif terhadap folder file proyek, $(MSBuildProjectPath)
, bahkan jika item berada dalam file yang diimpor seperti .targets
file.
Membuat item selama eksekusi
Item yang berada di luar elemen Target diberi nilai selama fase evaluasi build. Selama fase eksekusi berikutnya, item dapat dibuat atau dimodifikasi dengan cara berikut:
Tugas apa pun dapat memancarkan item. Untuk memancarkan item, elemen Tugas harus memiliki elemen Output turunan yang memiliki
ItemName
atribut.Tugas CreateItem dapat memancarkan item. Penggunaan ini tidak digunakan lagi.
Target
elemen mungkin berisi elemen ItemGroup yang mungkin berisi elemen item.
Membuat item dalam file proyek
Untuk mereferensikan jenis item di seluruh file proyek, Anda menggunakan sintaks @(ItemType)
. Misalnya, Anda akan mereferensikan jenis item dalam contoh sebelumnya dengan menggunakan @(Compile)
. Dengan menggunakan sintaks ini, Anda dapat meneruskan item ke tugas dengan menentukan jenis item sebagai parameter tugas tersebut. Untuk informasi selengkapnya, lihat Cara: Memilih file yang akan dibuat.
Secara default, item jenis item dipisahkan oleh titik koma (;) ketika diperluas. Anda dapat menggunakan sintaks @(ItemType, 'separator')
untuk menentukan pemisah selain default. Untuk informasi selengkapnya, lihat Cara: Menampilkan daftar item yang dipisahkan dengan koma.
Gunakan kartubebas untuk menentukan item
Anda dapat menggunakan **
, *
, dan ?
karakter kartubebas untuk menentukan sekelompok file sebagai input untuk build alih-alih mencantumkan setiap file secara terpisah.
- Karakter
?
kartubebas cocok dengan satu karakter. - Karakter
*
kartubebas cocok dengan nol karakter atau lebih. **
Urutan karakter kartubebas cocok dengan jalur parsial.
Misalnya, Anda dapat menentukan semua .cs
file di direktori yang berisi file proyek dengan menggunakan elemen berikut dalam file proyek Anda.
<CSFile Include="*.cs"/>
Elemen berikut memilih semua .vb
file pada D:
drive:
<VBFile Include="D:/**/*.vb"/>
Jika Anda ingin menyertakan literal *
atau ?
karakter dalam item tanpa ekspansi kartubebas, Anda harus menghindari karakter kartubebas.
Untuk informasi selengkapnya tentang karakter kartubebas, lihat Cara: Memilih file yang akan dibuat.
Menggunakan atribut Kecualikan
Elemen item dapat berisi Exclude
atribut, yang mengecualikan item tertentu (file) dari jenis item. Atribut Exclude
ini biasanya digunakan bersama dengan karakter kartubebas. Misalnya, XML berikut menambahkan setiap file .cs di direktori ke CSFile
jenis item, kecuali file DoNotBuild.cs .
<ItemGroup>
<CSFile Include="*.cs" Exclude="DoNotBuild.cs"/>
</ItemGroup>
Atribut Exclude
hanya memengaruhi item yang ditambahkan oleh Include
atribut dalam elemen item yang berisi keduanya. Contoh berikut tidak akan mengecualikan file Form1.cs, yang ditambahkan dalam elemen item sebelumnya.
<Compile Include="*.cs" />
<Compile Include="*.res" Exclude="Form1.cs">
Untuk informasi selengkapnya, lihat Cara: Mengecualikan file dari build.
Metadata item
Item mungkin berisi metadata selain informasi dalam Include
atribut dan Exclude
. Metadata ini dapat digunakan oleh tugas yang memerlukan informasi lebih lanjut tentang item atau untuk batch tugas dan target. Untuk informasi selengkapnya, lihat Batching.
Metadata adalah kumpulan pasangan kunci-nilai yang dideklarasikan dalam file proyek sebagai elemen trunan dari elemen item. Nama elemen turunan adalah nama metadata, dan nilai elemen anak adalah nilai metadata.
Metadata dikaitkan dengan elemen item yang berisinya. Misalnya, XML berikut menambahkan Culture
metadata yang memiliki nilai Fr
ke one.cs dan item two.cs dari CSFile
jenis item.
<ItemGroup>
<CSFile Include="one.cs;two.cs">
<Culture>Fr</Culture>
</CSFile>
</ItemGroup>
Item dapat memiliki nilai metadata nol atau lebih. Anda dapat mengubah nilai metadata kapan pun. Jika Anda mengatur metadata ke nilai kosong, Anda secara efektif menghapusnya dari build.
Metadata item referensi dalam file proyek
Anda dapat mereferensikan metadata item di seluruh file proyek dengan menggunakan sintaks %(ItemMetadataName)
. Jika ada ambiguitas, Anda dapat memenuhi syarat referensi dengan menggunakan nama jenis item. Misalnya, Anda dapat menentukan %(ItemType.ItemMetaDataName)
. Contoh berikut menggunakan Display
metadata untuk membuat Message
batch tugas. Untuk informasi selengkapnya tentang cara menggunakan metadata item untuk batching, lihat Metadata item dalam batching tugas.
<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>
Metadata item terkenal MSBuild
Saat item ditambahkan ke jenis item, item tersebut diberi beberapa metadata terkenal. Misalnya, semua item memiliki metadata %(Filename)
terkenal , yang nilainya adalah nama file item (tanpa ekstensi). Untuk informasi selengkapnya, lihat Metadata item terkenal.
Mengubah jenis item dengan menggunakan metadata
Anda dapat mengubah daftar item menjadi daftar item baru dengan menggunakan metadata. Misalnya, Anda dapat mengubah jenis CppFiles
item yang memiliki item yang mewakili .cpp
file menjadi daftar .obj
file yang sesuai dengan menggunakan ekspresi @(CppFiles -> '%(Filename).obj')
.
Kode berikut membuat CultureResource
tipe item yang berisi salinan semua EmbeddedResource
item dengan Culture
metadata. Nilai Culture
metadata menjadi nilai metadata baru CultureResource.TargetDirectory
.
<Target Name="ProcessCultureResources">
<ItemGroup>
<CultureResource Include="@(EmbeddedResource)"
Condition="'%(EmbeddedResource.Culture)' != ''">
<TargetDirectory>%(EmbeddedResource.Culture) </TargetDirectory>
</CultureResource>
</ItemGroup>
</Target>
Untuk operasi lainnya pada item, lihat Fungsi item MSBuild dan Transformasi.
Definisi item
Anda dapat menambahkan metadata default ke jenis item apa pun dengan menggunakan elemen ItemDefinitionGroup. Seperti metadata terkenal, metadata default dikaitkan dengan semua item jenis item yang Anda tentukan. Anda dapat secara eksplisit mengambil alih metadata default dalam definisi item. Misalnya, XML berikut memberikan Compile
item one.cs dan three.cs metadata BuildDay
dengan nilai "Senin". Kode memberikan item two.cs metadata BuildDay
dengan nilai "Selasa".
<ItemDefinitionGroup>
<Compile>
<BuildDay>Monday</BuildDay>
</Compile>
</ItemDefinitionGroup>
<ItemGroup>
<Compile Include="one.cs;three.cs" />
<Compile Include="two.cs">
<BuildDay>Tuesday</BuildDay>
</Compile>
</ItemGroup>
Untuk informasi selengkapnya, lihat Definisi citra.
Atribut untuk item dalam ItemGroup dari Target
Target
elemen mungkin berisi elemen ItemGroup yang mungkin berisi elemen item. Atribut di bagian ini valid saat ditentukan untuk item dalam ItemGroup
yang ada di Target
.
Hapus atribut
Atribut Remove
menghapus item tertentu (file) dari jenis item. Atribut ini diperkenalkan dalam .NET Framework 3.5 (hanya di dalam target). Target di dalam dan luar didukung mulai dari MSBuild 15.0.
Contoh berikut menghapus setiap .config
file dari Compile
jenis item.
<Target>
<ItemGroup>
<Compile Remove="*.config"/>
</ItemGroup>
</Target>
MatchOnMetadata attribute
Atribut MatchOnMetadata
hanya berlaku untuk Remove
atribut yang mereferensikan item lain (misalnya, Remove="@(Compile);@(Content)"
) dan menginstruksikan Remove
operasi untuk mencocokkan item berdasarkan nilai nama metadata yang ditentukan, alih-alih mencocokkan berdasarkan nilai item.
Aturan pencocokan untuk B Remove="@(A)" MatchOnMetadata="M"
: hapus semua item dari B
yang memiliki metadata M
, yang nilai V
metadatanya untuk M
mencocokkan item apa pun dari A
dengan metadata M
nilai V
.
<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>
Dalam contoh, nilai b2
item , c2
, dan d2
dihapus dari item B
karena:
b2
danc2
dariB
kecocokan terhadapb1
dariA
padaM1=2
danM2=x
d2
dariB
kecocokan terhadapc1
dariA
aktifM1=3
danM2=y
Tugas menghasilkan Message
yang berikut:
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'
Contoh penggunaan MatchOnMetadata
dari MSBuild:
<_TransitiveItemsToCopyToOutputDirectory Remove="@(_ThisProjectItemsToCopyToOutputDirectory)" MatchOnMetadata="TargetPath" MatchOnMetadataOptions="PathLike" />
Baris ini menghapus item dari _TransitiveItemsToCopyToOutputDirectory
yang memiliki nilai metadata yang sama TargetPath
dari item di _ThisProjectItemsToCopyToOutputDirectory
Atribut MatchOnMetadataOptions
Menentukan strategi pencocokan string yang digunakan oleh untuk mencocokkan MatchOnMetadata
nilai metadata antar item (nama metadata selalu tidak peka huruf besar/kecil yang cocok). Kemungkinan nilainya adalah CaseSensitive
, CaseInsensitive
, atau PathLike
. Nilai defaultnya adalah CaseSensitive
.
PathLike
menerapkan normalisasi sadar jalur ke nilai seperti menormalkan orientasi garis miring, mengabaikan garis miring berikutnya, menghilangkan .
dan ..
, dan membuat semua jalur relatif absolut terhadap direktori saat ini.
KeepMetadata attribute
Jika item dihasilkan dalam target, elemen item dapat berisi KeepMetadata
atribut. Jika atribut ini ditentukan, hanya metadata yang ditentukan dalam daftar nama yang dibatasi titik koma yang akan ditransfer dari item sumber ke item target. Nilai kosong untuk atribut ini setara dengan tidak menentukannya. Atribut KeepMetadata
diperkenalkan dalam .NET Framework 4.5.
Contoh berikut menggambarkan cara menggunakan KeepMetadata
atribut.
<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:
-->
Atribut RemoveMetadata
Jika item dihasilkan dalam target, elemen item dapat berisi RemoveMetadata
atribut. Jika atribut ini ditentukan, semua metadata ditransfer dari item sumber ke item target kecuali metadata yang namanya terkandung dalam daftar nama yang dibatasi titik koma. Nilai kosong untuk atribut ini setara dengan tidak menentukannya. Atribut RemoveMetadata
diperkenalkan dalam .NET Framework 4.5.
Contoh berikut menggambarkan cara menggunakan RemoveMetadata
atribut.
<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:
-->
Untuk operasi lainnya pada item, lihat Fungsi item MSBuild.
Atribut KeepDuplicates
Jika item dihasilkan dalam target, elemen item dapat berisi KeepDuplicates
atribut. KeepDuplicates
adalah Boolean
atribut yang menentukan apakah item harus ditambahkan ke grup target jika item tersebut merupakan duplikat yang tepat dari item yang ada.
Jika item sumber dan target memiliki nilai Include
yang sama tetapi metadata yang berbeda, item ditambahkan meskipun KeepDuplicates
diatur ke false
. Nilai kosong untuk atribut ini setara dengan tidak menentukannya. Atribut KeepDuplicates
diperkenalkan dalam .NET Framework 4.5.
Contoh berikut menggambarkan cara menggunakan KeepDuplicates
atribut.
<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
-->
KeepDuplicates
Karena atribut mempertimbangkan metadata item selain nilai item, penting untuk mengetahui apa yang terjadi dengan metadata. Misalnya, lihat Mendeteksi duplikat saat menggunakan fungsi item Metadata.
Memperbarui metadata pada item dalam ItemGroup di luar Target
Item di luar target dapat memperbarui metadata yang ada melalui Update
atribut. Atribut ini tidak tersedia untuk item di bawah target.
<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
-->
Di MSBuild versi 16.6 dan yang lebih baru, Update
atribut mendukung referensi metadata yang memenuhi syarat untuk memfasilitasi impor metadata dari dua item atau lebih.
<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
-->
Keterangan:
- Metadata yang tidak memenuhi syarat (
%(MetadataName)
) mengikat ke jenis item yang sedang diperbarui (Item1
dalam contoh di atas). Metadata yang memenuhi syarat (%(Item2.Color)
) mengikat di dalam kumpulan jenis item yang cocok yang diambil dari ekspresi Perbarui. - Jika item cocok beberapa kali di dalam dan di antara beberapa item yang dirujuk:
- Kemunculan terakhir dari setiap jenis item yang direferensikan akan diambil (sehingga satu item yang diambil per jenis item).
- Ini cocok dengan perilaku batching item tugas di bawah target.
- Di mana seseorang dapat menempatkan %() referensi:
- Metadata
- Kondisi metadata
- Pencocokan nama metadata tidak peka huruf besar/kecil.
Memperbarui metadata pada item dalam ItemGroup di luar Target
Metadata juga dapat dimodifikasi di dalam target, dengan sintaks yang kurang ekspresif daripada 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:
-->