Properti MSBuild

  • Artikel

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 PATHdi 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 berisi PropertyGroup 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 GlobalOverrideValueglobal :

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>

Konten terkait