Definisi item
MSBuild 2.0 memungkinkan deklarasi statis item dalam file proyek dengan menggunakan elemen ItemGroup. Namun, metadata hanya dapat ditambahkan pada tingkat item, bahkan jika metadata identik untuk semua item. Mulai dari MSBuild 3.5, elemen proyek bernama ItemDefinitionGroup mengatasi batasan ini. ItemDefinitionGroup memungkinkan Anda menentukan sekumpulan definisi item, yang menambahkan nilai metadata default ke semua item dalam jenis item bernama.
Elemen ItemDefinitionGroup muncul segera setelah elemen Project pada file proyek. Definisi item menyediakan fungsionalitas berikut:
Anda dapat menentukan metadata default global untuk item di luar target. Artinya, metadata yang sama berlaku untuk semua item dari jenis yang ditentukan.
Jenis item dapat memiliki beberapa definisi. Ketika spesifikasi metadata tambahan ditambahkan ke jenis, spesifikasi terakhir lebih diutamakan. (Metadata mengikuti urutan impor yang sama dengan properti berikut.)
Metadata bisa menjadi aditif. Misalnya, nilai CDefines diakumulasi secara kondisional, tergantung pada properti yang sedang ditetapkan. Contohnya,
MT;STD_CALL;DEBUG;UNICODE.Metadata dapat dihapus.
Kondisi dapat digunakan untuk mengontrol penyertaan metadata.
Nilai default metadata item
Metadata item yang ditentukan dalam ItemDefinitionGroup hanyalah deklarasi dari metadata default. Metadata tidak berlaku kecuali Anda menentukan Item yang menggunakan ItemGroup untuk memuat nilai metadata.
Catatan
Dalam banyak contoh pada topik ini, elemen ItemDefinitionGroup ditampilkan tetapi definisi ItemGroup yang sesuai dihilangkan untuk kejelasan.
Metadata yang secara eksplisit didefinisikan dalam ItemGroup lebih diutamakan daripada metadata di ItemDefinitionGroup. Metadata di ItemDefinitionGroup hanya diterapkan untuk metadata yang tidak terdefinisi dalam ItemGroup. Contohnya:
<ItemDefinitionGroup>
<i>
<m>m1</m>
<n>n1</n>
</i>
</ItemDefinitionGroup>
<ItemGroup>
<i Include="a">
<o>o1</o>
<n>n2</n>
</i>
</ItemGroup>
Dalam contoh ini, metadata default "m" diterapkan ke Item "i" karena metadata "m" tidak secara eksplisit didefinisikan oleh Item "i". Namun, metadata default "n" tidak diterapkan ke Item "i" karena metadata "n" sudah ditentukan oleh Item "i".
Catatan
Nama Elemen dan Parameter XML peka huruf besar/kecil. Metadata item dan nama Item/Properti tidak peka huruf besar/kecil. Oleh karena itu, item ItemDefinitionGroup yang memiliki nama yang hanya berbeda menurut huruf besar/kecil harus diperlakukan sebagai ItemGroup yang sama.
Sumber nilai
Nilai untuk metadata yang didefinisikan dalam ItemDefinitionGroup dapat berasal dari berbagai sumber, sebagai berikut:
Properti PropertyGroup
Item dari ItemDefinitionGroup
Transformasi item pada Item ItemDefinitionGroup
Variabel lingkungan
Properti global (dari baris perintah MSBuild.exe)
Properti yang dipesan
Metadata terkenal pada Item dari ItemDefinitionGroup
Bagian CDATA <![ CDATA[apa pun di sini tidak diurai]]>
Catatan
Metadata item dari ItemGroup tidak berguna dalam deklarasi metadata ItemDefinitionGroup karena elemen ItemDefinitionGroup diproses sebelum elemen ItemGroup.
Definisi aditif dan beberapa
Saat Anda menambahkan definisi atau menggunakan beberapa ItemDefinitionGroups, ingat hal berikut:
Spesifikasi metadata tambahan ditambahkan ke jenis.
Spesifikasi terakhir lebih diutamakan.
Ketika Anda memiliki beberapa ItemDefinitionGroups, setiap spesifikasi berikutnya menambahkan metadatanya ke definisi sebelumnya. Contohnya:
<ItemDefinitionGroup>
<i>
<m>m1</m>
<n>n1</n>
</i>
</ItemDefinitionGroup>
<ItemDefinitionGroup>
<i>
<o>o1</o>
</i>
</ItemDefinitionGroup>
Dalam contoh ini, metadata "o" ditambahkan ke "m" dan "n".
Selain itu, nilai metadata yang ditentukan sebelumnya juga dapat ditambahkan. Contohnya:
<ItemDefinitionGroup>
<i>
<m>m1</m>
</i>
</ItemDefinitionGroup>
<ItemDefinitionGroup>
<i>
<m>%(m);m2</m>
</i>
</ItemDefinitionGroup>
Dalam contoh ini, nilai yang ditentukan sebelumnya untuk metadata "m" (m1) ditambahkan ke nilai baru (m2), sehingga nilai akhir adalah "m1;m2".
Catatan
Ini juga dapat terjadi di ItemDefinitionGroup yang sama.
Saat Anda mengambil alih metadata yang ditentukan sebelumnya, spesifikasi terakhir lebih diutamakan. Dalam contoh berikut, nilai akhir metadata "m" berubah dari "m1" ke "m1a".
<ItemDefinitionGroup>
<i>
<m>m1</m>
</i>
</ItemDefinitionGroup>
<ItemDefinitionGroup>
<i>
<m>m1a</m>
</i>
</ItemDefinitionGroup>
Menggunakan kondisi dalam ItemDefinitionGroup
Anda dapat menggunakan kondisi dalam ItemDefinitionGroup untuk mengontrol penyertaan metadata. Contohnya:
<ItemDefinitionGroup Condition="'$(Configuration)'=='Debug'">
<i>
<m>m1</m>
</i>
</ItemDefinitionGroup>
Dalam hal ini, metadata default "m1" pada item "i" hanya disertakan jika nilai properti "Konfigurasi" adalah "Debug".
Catatan
Hanya referensi metadata lokal yang didukung dalam kondisi.
Referensi ke metadata yang ditentukan dalam ItemDefinitionGroup sebelumnya bersifat lokal untuk item, bukan grup definisi. Artinya, cakupan referensi adalah spesifik item. Contohnya:
<ItemDefinitionGroup>
<test>
<yes>1</yes>
</test>
<i>
<m>m0</m>
<m Condition="'%(test.yes)'=='1'">m1</m>
</i>
</ItemDefinitionGroup>
Dalam contoh di atas, item "i" mereferensikan item "test" dalam Kondisinya. Kondisi ini tidak akan pernah benar karena MSBuild menginterpretasikan referensi ke metadata item lain dalam ItemDefinitionGroup sebagai string kosong. Oleh karena itu, "m" akan diatur ke "m0."
<ItemDefinitionGroup>
<i>
<m>m0</m>
<yes>1</yes>
<m Condition="'%(i.yes)'=='1'">m1</m>
</i>
</ItemDefinitionGroup>
Dalam contoh di atas, "m" akan diatur ke nilai "m1" sebagai item Referensi kondisi "nilai metadata i" untuk item "ya."
Mengambil alih dan menghapus metadata
Metadata yang ditentukan dalam elemen ItemDefinitionGroup dapat diambil alih dalam elemen ItemDefinitionGroup yang lebih baru dengan mengatur nilai metadata ke nilai lain. Anda juga dapat menghapus item metadata secara efektif dengan mengaturnya ke nilai kosong. Contohnya:
<ItemDefinitionGroup>
<i>
<m>m1</m>
</i>
</ItemDefinitionGroup>
<ItemDefinitionGroup>
<i>
<m></m>
</i>
</ItemDefinitionGroup>
Item "i" masih berisi metadata "m", tetapi nilainya sekarang kosong.
Cakupan metadata
ItemDefinitionGroups memiliki cakupan global pada properti yang ditentukan dan global di mana pun properti tersebut ditentukan. Definisi metadata default dalam ItemDefinitionGroup dapat dirujuk sendiri. Misalnya, berikut ini menggunakan referensi metadata sederhana:
<ItemDefinitionGroup>
<i>
<m>m1</m>
<m>%(m);m2</m>
</i>
</ItemDefinitionGroup>
Referensi metadata yang memenuhi syarat juga dapat digunakan:
<ItemDefinitionGroup>
<i>
<m>m1</m>
<m>%(i.m);m2</m>
</i>
</ItemDefinitionGroup>
Namun, berikut ini tidak valid:
<ItemDefinitionGroup>
<i>
<m>m1</m>
<m>@(x)</m>
</i>
</ItemDefinitionGroup>
Dimulai di MSBuild 3.5, ItemGroups juga dapat dirujuk sendiri. Contohnya:
<ItemGroup>
<item Include="a">
<m>m1</m>
<m>%(m);m2</m>
</item>
</ItemGroup>