Properti MSBuild

Properti adalah pasangan nilai nama yang dapat digunakan untuk mengonfigurasi build. Properti berguna untuk meneruskan nilai ke tugas, mengevaluasi kondisi, dan menyimpan nilai yang akan dirujuk 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 ASCII atau garis bawah (_); karakter berikutnya yang valid termasuk karakter alfanumerik (huruf atau digit ASCII), garis bawah, dan tanda hubung (-).

Di seluruh file proyek, properti dirujuk dengan menggunakan sintaks $(<PropertyName>). Misalnya, properti dalam contoh sebelumnya dirujuk dengan menggunakan $(BuildDir).

Nilai properti dapat diubah dengan mendefinisikan ulang properti. Properti BuildDir dapat diberikan 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 terbatas

MSBuild menggunakan beberapa nama properti secara khusus untuk menyimpan informasi tentang file proyek dan biner MSBuild. Properti ini dirujuk dengan menggunakan notasi $, sama seperti properti lainnya. Misalnya, $(MSBuildProjectFile) mengembalikan nama file lengkap file proyek, termasuk ekstensi nama file.

Untuk informasi selengkapnya, lihat Cara: Mereferensikan nama atau lokasi file proyek dan MSBuild properti khusus dan terkenal.

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 dipesan. Misalnya, untuk menggunakan PATH variabel lingkungan dalam 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.

Setiap proyek MSBuild memiliki blok lingkungan terisolasi: hanya melihat baca dan tulis ke bloknya sendiri. MSBuild hanya membaca variabel lingkungan saat menginisialisasi kumpulan properti, sebelum file proyek dievaluasi atau dibuat. Setelah itu, properti lingkungan statis, yaitu, setiap alat yang ditelurkan dimulai dengan nama dan nilai yang sama.

Untuk mendapatkan nilai variabel lingkungan saat ini dari dalam alat yang ditelurkan, gunakan fungsi Properti System.Environment.GetEnvironmentVariable. Namun, metode yang disukai adalah menggunakan parameter EnvironmentVariablestugas . Properti lingkungan yang diatur dalam array string ini dapat diteruskan ke alat yang ditelurkan tanpa memengaruhi variabel lingkungan sistem.

Petunjuk / Saran

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 sintaks berikut, di mana Hive adalah sarang registri (misalnya, HKEY_LOCAL_MACHINE), MyKey adalah nama kunci, MySubKey adalah nama subkunjuk, dan Value merupakan nilai subkunia.

$(registry:Hive\MyKey\MySubKey@Value)

Untuk mendapatkan nilai subkey 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 MSBuild versi .NET SDK (dotnet build), properti registri tidak didukung.

Membuat properti selama eksekusi

Properti yang diposisikan di luar Target elemen adalah nilai yang ditetapkan selama fase evaluasi build. Selama fase eksekusi berikutnya, properti dapat dibuat atau dimodifikasi sebagai berikut:

Properti dapat dipancarkan oleh tugas apa pun. Untuk memancarkan properti, elemen Tugas harus memiliki elemen Output anak yang memiliki PropertyName atribut .
Properti dapat dipancarkan oleh tugas CreateProperty . Penggunaan ini tidak digunakan lagi.
Target elemen mungkin berisi PropertyGroup elemen yang mungkin berisi deklarasi properti.

Properti global

MSBuild memungkinkan Anda mengatur properti pada baris perintah dengan menggunakan sakelar -property (atau -p). Nilai properti global ini mengambil alih nilai properti yang diatur dalam file proyek. Ini termasuk properti lingkungan, tetapi tidak termasuk properti yang dipesan, yang tidak dapat diubah.

Contoh berikut mengatur properti global Configuration ke DEBUG.

msbuild.exe MyProj.proj -p:Configuration=DEBUG

Properti global juga dapat diatur atau dimodifikasi untuk proyek turunan dalam build multi-proyek dengan menggunakan Properties atribut tugas MSBuild. Properti global juga diteruskan ke proyek turunan kecuali RemoveProperties atribut 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 adalah 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.props -->
<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): ImportOverrideValue

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 ekspresi reguler, 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.

Simpan XML di properti

Properti dapat berisi XML arbitrer, yang dapat membantu meneruskan nilai ke tugas atau menampilkan informasi pengelogan. Contoh berikut menunjukkan ConfigTemplate properti , yang memiliki nilai yang berisi XML dan referensi properti lainnya. MSBuild mengganti referensi properti dengan menggunakan nilai properti masing-masing. Nilai properti ditetapkan dalam urutan kemunculannya. Oleh karena itu, dalam contoh ini, $(MySupportedVersion), $(MyRequiredVersion), dan $(MySafeMode) seharusnya sudah ditentukan.

<PropertyGroup>
    <ConfigTemplate>
        <Configuration>
            <Startup>
                <SupportedRuntime
                    ImageVersion="$(MySupportedVersion)"
                    Version="$(MySupportedVersion)"/>
                <RequiredRuntime
                    ImageVersion="$(MyRequiredVersion)"
                    Version="$(MyRequiredVersion)"
                    SafeMode="$(MySafeMode)"/>
            </Startup>
        </Configuration>
    </ConfigTemplate>
</PropertyGroup>

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-12-12