Properti MSBuild
Properti adalah pasangan nama-nilai yang dapat digunakan untuk mengonfigurasi build. Properti berguna untuk meneruskan nilai ke tugas, mengevaluasi kondisi, dan menyimpan nilai yang akan direferensikan di seluruh file proyek.
Menentukan dan mereferensikan properti dalam file proyek
Properti dideklarasikan dengan membuat elemen yang memiliki nama properti sebagai turunan dari elemen PropertyGroup. Misalnya, XML berikut membuat properti bernama BuildDir
yang memiliki nilai Build
.
<PropertyGroup>
<BuildDir>Build</BuildDir>
</PropertyGroup>
Nama properti yang valid dimulai dengan huruf besar atau huruf kecil atau garis bawah (_
); karakter berikutnya yang valid mencakup karakter alfanumerik (huruf atau digit), garis bawah, dan tanda hubung (-
).
Di seluruh file proyek, properti direferensikan dengan menggunakan sintaks $(<PropertyName>)
. Misalnya, properti dalam contoh sebelumnya direferensikan dengan menggunakan $(BuildDir)
.
Nilai properti dapat diubah dengan mendefinisikan ulang properti. Properti BuildDir
dapat diberi nilai baru dengan menggunakan XML ini:
<PropertyGroup>
<BuildDir>Alternate</BuildDir>
</PropertyGroup>
Properti dievaluasi dalam urutan muncul dalam file proyek. Nilai baru untuk BuildDir
harus dideklarasikan setelah nilai lama ditetapkan.
Properti yang dipesan
MSBuild mencadangkan beberapa nama properti untuk menyimpan informasi tentang file proyek dan biner MSBuild. Properti ini direferensikan dengan menggunakan notasi $, sama seperti properti lainnya. Misalnya, $(MSBuildProjectFile) mengembalikan nama file lengkap dari file proyek, termasuk ekstensi nama file.
Untuk informasi selengkapnya, lihat Cara: Mereferensikan nama atau lokasi file proyek dan Properti MSBuild yang dicadangkan dan dikenal.
Properti internal MSBuild
Properti yang ditentukan dalam file impor standar yang dimulai dengan garis bawah (_) bersifat privat ke MSBuild dan tidak boleh dibaca, diatur ulang, atau ditimpa dalam kode pengguna.
Properti lingkungan
Anda dapat mereferensikan variabel lingkungan dalam file proyek sama seperti Anda mereferensikan properti yang dicadangkan. Misalnya, untuk menggunakan variabel lingkungan PATH
di file proyek Anda, gunakan $(Path). Jika proyek berisi definisi properti yang memiliki nama yang sama dengan properti lingkungan, properti dalam proyek akan mengambil alih nilai variabel lingkungan.
Tiap proyek MSBuild memiliki blok lingkungan yang terisolasi: hanya melihat, membaca, dan menulis ke bloknya sendiri. MSBuild hanya membaca variabel lingkungan saat menginisialisasi pengumpulan properti, sebelum file proyek dievaluasi atau dibuat. Setelah itu, properti lingkungan bersifat statis, yaitu, tiap alat yang dimunculkan dimulai dengan nama dan nilai yang sama.
Untuk mendapatkan nilai variabel lingkungan saat ini dari dalam alat yang dimunculkan, gunakan fungsi Properti System.Environment.GetEnvironmentVariable. Akan tetapi, metode yang disukai adalah menggunakan parameter tugas EnvironmentVariables. Properti lingkungan yang diatur dalam larik string ini dapat diteruskan ke alat yang dimunculkan tanpa memengaruhi variabel lingkungan sistem.
Tip
Tidak semua variabel lingkungan dibaca untuk menjadi properti awal. Variabel lingkungan apa pun yang namanya bukan nama properti MSBuild yang valid, seperti "386", diabaikan.
Untuk informasi selengkapnya, lihat Cara: Menggunakan variabel lingkungan dalam build.
Properti registri
Anda dapat membaca nilai registri sistem dengan menggunakan sintaksis berikut, di mana Hive
adalah sarang registri (misalnya, HKEY_LOCAL_MACHINE), MyKey
adalah nama kunci, MySubKey
adalah nama subkunci, dan Value
merupakan nilai dari subkunci.
$(registry:Hive\MyKey\MySubKey@Value)
Untuk mendapatkan nilai subkuncci default, hilangkan Value
.
$(registry:Hive\MyKey\MySubKey)
Nilai registri ini dapat digunakan untuk menginisialisasi properti build. Misalnya, untuk membuat properti build yang mewakili beranda browser web Visual Studio, gunakan kode ini:
<PropertyGroup>
<VisualStudioWebBrowserHomePage>
$(registry:HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\14.0\WebBrowser@HomePage)
</VisualStudioWebBrowserHomePage>
<PropertyGroup>
Peringatan
Dalam versi .NET SDK MSBuild (dotnet build
), properti registri tidak didukung.
Membuat properti selama eksekusi
Properti yang berada di luar elemen Target
diberi nilai selama fase evaluasi build. Selama fase eksekusi berikutnya, properti dapat dibuat atau diubah sebagai berikut:
Properti dapat dikeluarkan oleh tugas apa pun. Untuk mengeluarkan item, elemen Tugas harus memiliki elemen Output turunan yang memiliki atribut
PropertyName
.Properti dapat dikeluarkan oleh tugas CreateProperty. Penggunaan ini tidak digunakan lagi.
Target
elemen dapat berisiPropertyGroup
elemen yang mungkin berisi deklarasi properti.
Properti global
MSBuild memungkinkan Anda mengatur properti pada baris perintah dengan menggunakan tombol -property (atau -p). Nilai properti global ini mengambil alih nilai properti yang diatur dalam file proyek. Ini mencakup properti lingkungan, tetapi tidak mencakup properti yang dicadangkan, yang tidak dapat diubah.
Contoh berikut mengatur properti Configuration
global menjadi DEBUG
.
msbuild.exe MyProj.proj -p:Configuration=DEBUG
Properti global juga dapat diatur atau diubah untuk proyek turunan dalam build multi-proyek dengan menggunakan atribut Properties
pada tugas MSBuild. Properti global juga diteruskan ke proyek turunan kecuali RemoveProperties
atribut RemoveProperties
pada tugas MSBuild digunakan untuk menentukan daftar properti yang tidak akan diteruskan. Untuk informasi selengkapnya, lihat Tugas MSBuild.
Properti lokal
Properti lokal dapat diatur ulang dalam proyek. Properti global tidak dapat. Saat properti lokal diatur dari baris perintah dengan -p
opsi , pengaturan dalam file proyek lebih diutamakan daripada baris perintah.
Anda menentukan properti lokal dengan menggunakan TreatAsLocalProperty
atribut dalam tag proyek.
Kode berikut menentukan bahwa dua properti bersifat lokal:
<Project Sdk="Microsoft.Net.Sdk" TreatAsLocalProperty="Prop1;Prop2">
Properti lokal tidak diteruskan ke proyek turunan dalam build multi-proyek. Jika Anda memberikan nilai pada baris perintah dengan -p
opsi , proyek turunan diberikan nilai properti global alih-alih nilai lokal yang diubah dalam proyek induk, tetapi proyek turunan (atau salah satu impornya) juga dapat mengubahnya dengan milik mereka sendiri TreatAsLocalProperty
.
Contoh dengan properti lokal
Contoh kode berikut menunjukkan efek dari TreatAsLocalProperty
:
<!-- test1.proj -->
<Project TreatAsLocalProperty="TreatedAsLocalProp">
<PropertyGroup>
<TreatedAsLocalProp>LocalOverrideValue</TreatedAsLocalProp>
</PropertyGroup>
<Target Name="Go">
<MSBuild Projects="$(MSBuildThisFileDirectory)\test2.proj" Targets="Go2" Properties="Inner=true" />
</Target>
<Target Name="Go2" BeforeTargets="Go">
<Warning Text="TreatedAsLocalProp($(MSBuildThisFileName)): $(TreatedAsLocalProp)" />
</Target>
</Project>
<!-- test2.proj -->
<Project TreatAsLocalProperty="TreatedAsLocalProp">
<Target Name="Go2">
<Warning Text="TreatedAsLocalProp($(MSBuildThisFileName)): $(TreatedAsLocalProp)" />
</Target>
</Project>
Misalkan Anda membangun baris perintah test1.proj , dan memberikan TreatedAsLocalProperty
nilai GlobalOverrideValue
global :
dotnet msbuild .\test1.proj -p:TreatedAsLocalProp=GlobalOverrideValue
Outputnya sebagai berikut:
test1.proj(11,9): warning : TreatedAsLocalProp(test): LocalOverrideValue
test2.proj(3,9): warning : TreatedAsLocalProp(test2): GlobalOverrideValue
Proyek turunan mewarisi nilai global, tetapi proyek induk menggunakan properti yang ditetapkan secara lokal.
Properti dan impor lokal
Ketika TreatAsLocalProperty
atribut digunakan pada proyek yang diimpor, pesanan penting saat mempertimbangkan nilai mana yang diperoleh properti.
Contoh kode berikut menunjukkan efek pada TreatAsLocalProperty
proyek yang diimpor:
<!-- importer.proj -->
<Project>
<PropertyGroup>
<TreatedAsLocalProp>FirstOverrideValue</TreatedAsLocalProp>
</PropertyGroup>
<Import Project="import.props" />
<PropertyGroup>
<TreatedAsLocalProp Condition=" '$(TrySecondOverride)' == 'true' ">SecondOverrideValue</TreatedAsLocalProp>
</PropertyGroup>
<Target Name="Go">
<Warning Text="TreatedAsLocalProp($(MSBuildThisFileName)): $(TreatedAsLocalProp)" />
</Target>
</Project>
<!-- import.proj -->
<Project TreatAsLocalProperty="TreatedAsLocalProp">
<PropertyGroup>
<TreatedAsLocalProp>ImportOverrideValue</TreatedAsLocalProp>
</PropertyGroup>
<!-- Here, TreatedAsLocalProp has the value "ImportOverrideValue"-->
</Project>
Misalkan Anda membangun importer.proj
dan menetapkan nilai global untuk TreatedAsLocalProp
sebagai berikut:
dotnet msbuild .\importer.proj -p:TreatedAsLocalProp=GlobalOverrideValue
Outputnya adalah:
importer.proj(9,9): warning : TreatedAsLocalProp(importer.proj): GlobalOverrideValue
Sekarang misalkan Anda membangun dengan properti TrySecondOverride
untuk true
:
dotnet msbuild .\importer.proj -p:TreatedAsLocalProp=GlobalOverrideValue -p:TrySecondOverride=true
Outputnya adalah:
importer.proj(13,9): warning : TreatedAsLocalProp(importer.proj): SecondOverrideValue
Contoh menunjukkan bahwa properti diperlakukan sebagai lokal setelah proyek yang diimpor tempat TreatAsLocalProperty
atribut digunakan, bukan hanya dalam file yang diimpor. Nilai properti dipengaruhi oleh nilai penggantian global, tetapi hanya sebelum proyek yang diimpor tempat TreatAsLocalProperty
digunakan.
Untuk informasi selengkapnya, lihat Elemen proyek (MSBuild) dan Cara: Membangun file sumber yang sama dengan opsi yang berbeda.
Fungsi properti
Mulai dari .NET Framework versi 4, Anda dapat menggunakan fungsi properti untuk mengevaluasi skrip MSBuild Anda. Anda dapat membaca waktu sistem, membandingkan string, mencocokkan regex, dan melakukan banyak tindakan lain dalam skrip build Anda tanpa menggunakan tugas MSBuild.
Anda dapat menggunakan metode string (instans) untuk beroperasi pada nilai properti apa pun, dan Anda dapat memanggil metode statis dari banyak kelas sistem. Misalnya, Anda dapat mengatur properti build ke tanggal hari ini sebagai berikut.
<Today>$([System.DateTime]::Now.ToString("yyyy.MM.dd"))</Today>
Untuk informasi selengkapnya, dan daftar fungsi properti, lihat Fungsi properti.
Menyimpan XML di properti
Properti dapat berisi XML arbitrer, yang dapat membantu meneruskan nilai ke tugas atau menampilkan informasi pengelogan. Contoh berikut menunjukkan properti ConfigTemplate
, yang memiliki nilai yang berisi XML dan referensi properti lainnya. MSBuild menggantikan referensi properti dengan menggunakan nilai properti masing-masing. Nilai properti ditetapkan dalam urutan kemunculannya. Oleh karena itu, pada contoh ini, $(MySupportedVersion)
, $(MyRequiredVersion)
, dan $(MySafeMode)
seharusnya telah ditentukan.
<PropertyGroup>
<ConfigTemplate>
<Configuration>
<Startup>
<SupportedRuntime
ImageVersion="$(MySupportedVersion)"
Version="$(MySupportedVersion)"/>
<RequiredRuntime
ImageVersion="$(MyRequiredVersion)"
Version="$(MyRequiredVersion)"
SafeMode="$(MySafeMode)"/>
</Startup>
</Configuration>
</ConfigTemplate>
</PropertyGroup>