File aturan XML Halaman Properti
Halaman properti proyek dalam IDE dikonfigurasi oleh file XML di folder aturan default. File XML menjelaskan nama aturan, kategori, dan properti individual, jenis datanya, nilai default, dan cara menampilkannya. Saat Anda mengatur properti di IDE, nilai baru disimpan dalam file proyek.
Jalur ke folder aturan default bergantung pada lokal dan versi Visual Studio yang digunakan. Di prompt perintah Visual Studio 2015 atau pengembang yang lebih lama, folder aturannya adalah %ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\<version>\<locale>
. Nilainya <version>
ada v140
di Visual Studio 2015. <locale>
adalah LCID, misalnya, 1033
untuk bahasa Inggris. Anda akan menggunakan jalur yang berbeda untuk setiap edisi Visual Studio yang diinstal, dan untuk setiap bahasa. Misalnya, jalur folder aturan default untuk edisi Komunitas Visual Studio 2015 dalam bahasa Inggris bisa berupa C:\Program Files (x86)\MSBuild\Microsoft.Cpp\v4.0\v140\1033\
.
Jalur ke folder aturan default bergantung pada lokal dan versi Visual Studio yang digunakan. Di prompt perintah pengembang Visual Studio 2017, folder aturannya adalah %VSINSTALLDIR%Common7\IDE\VC\VCTargets\<locale>\
. <locale>
adalah LCID, misalnya, 1033
untuk bahasa Inggris. Dalam perintah Visual Studio 2015 atau pengembang yang lebih lama, folder aturan adalah %ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\<version>\<locale>\
, di mana <version>
nilainya berada v140
di Visual Studio 2015. Anda akan menggunakan jalur yang berbeda untuk setiap edisi Visual Studio yang diinstal, dan untuk setiap bahasa. Misalnya, jalur folder aturan default untuk Visual Studio 2017 edisi Komunitas dalam bahasa Inggris bisa berupa C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\Common7\IDE\VC\VCTargets\1033\
.
Jalur ke folder aturan default bergantung pada lokal dan versi Visual Studio yang digunakan. Dalam perintah Visual Studio 2019 atau yang lebih baru, folder aturan adalah %VSINSTALLDIR%MSBuild\Microsoft\VC\<version>\<locale>\
, di mana <version>
nilainya berada v160
di Visual Studio 2019. <locale>
adalah LCID, misalnya, 1033
untuk bahasa Inggris. Di Visual Studio 2017, folder aturan adalah %VSINSTALLDIR%Common7\IDE\VC\VCTargets\<locale>\
. Di prompt perintah Visual Studio 2015 atau pengembang yang lebih lama, folder aturannya adalah %ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\<version>\<locale>\
. Anda akan menggunakan jalur yang berbeda untuk setiap edisi Visual Studio yang diinstal, dan untuk setiap bahasa. Misalnya, jalur folder aturan default untuk Visual Studio 2019 edisi Komunitas dalam bahasa Inggris bisa berupa C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\MSBuild\Microsoft\VC\v160\1033\
.
Anda hanya perlu memahami pekerjaan internal file-file ini dan IDE Visual Studio dalam beberapa skenario:
- Anda ingin membuat halaman properti kustom, atau
- Anda ingin menyesuaikan properti proyek tanpa menggunakan IDE Visual Studio.
Konten file aturan
Pertama, mari kita buka halaman properti untuk proyek. Klik kanan pada simpul proyek di Penjelajah Solusi dan pilih Properti:
Setiap simpul di bawah Properti Konfigurasi disebut aturan. Aturan terkadang mewakili satu alat seperti pengkompilasi. Secara umum, istilah ini mengacu pada sesuatu yang memiliki properti, yang mengeksekusi dan yang dapat menghasilkan beberapa output. Setiap aturan diisi dari file XML di folder aturan default. Misalnya, aturan C/C++ yang ditampilkan di sini diisi oleh cl.xml
.
Setiap aturan memiliki sekumpulan properti, yang diatur ke dalam kategori. Setiap sub-simpul di bawah aturan mewakili kategori. Misalnya, simpul Pengoptimalan di bawah C/C++ berisi semua properti terkait pengoptimalan alat pengkompilasi. Properti dan nilainya dirender dalam format kisi di panel kanan.
Anda dapat membuka cl.xml
di notepad atau editor XML apa pun. Anda akan melihat simpul akar yang disebut Rule
. Ini mendefinisikan daftar properti yang sama yang ditampilkan di UI, bersama dengan metadata tambahan.
<?xml version="1.0" encoding="utf-8"?>
<!--Copyright, Microsoft Corporation, All rights reserved.-->
<Rule Name="CL" PageTemplate="tool" DisplayName="C/C++" SwitchPrefix="/" Order="10" xmlns="http://schemas.microsoft.com/build/2009/properties" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:sys="clr-namespace:System;assembly=mscorlib">
<Rule.Categories>
<Category Name="General" DisplayName="General" />
<Category Name="Optimization" DisplayName="Optimization" />
<Category Name="Preprocessor" DisplayName="Preprocessor" />
<Category Name="Code Generation" DisplayName="Code Generation" />
<Category Name="Language" DisplayName="Language" />
<Category Name="Precompiled Headers" DisplayName="Precompiled Headers" />
<Category Name="Output Files" DisplayName="Output Files" />
<Category Name="Browse Information" DisplayName="Browse Information" />
<Category Name="Advanced" DisplayName="Advanced" />
<Category Name="All Options" DisplayName="All Options" Subtype="Search" />
<Category Name="Command Line" DisplayName="Command Line" Subtype="CommandLine" />
</Rule.Categories>
<!-- . . . -->
</Rule>
Ada satu file XML untuk setiap simpul di bawah Properti Konfigurasi di UI halaman properti. Anda dapat menambahkan atau menghapus aturan di UI: aturan dilakukan dengan menyertakan atau menghapus lokasi ke file XML yang sesuai dalam proyek. Misalnya, ini adalah bagaimana Microsoft.CppBuild.targets
(ditemukan satu tingkat lebih tinggi dari folder 1033) meliputi cl.xml
:
<PropertyPageSchema Condition="'$(ConfigurationType)' != 'Utility'" Include="$(VCTargetsPath)$(LangID)\cl.xml"/>
Jika Anda menghapus cl.xml
semua data, Anda memiliki kerangka kerja dasar ini:
<?xml version="1.0" encoding="utf-8"?>
<Rule>
<Rule.DataSource />
<Rule.Categories>
<Category />
<!-- . . . -->
</Rule.Categories>
<BoolProperty />
<EnumProperty />
<IntProperty />
<StringProperty />
<StringListProperty />
</Rule>
Bagian berikutnya menjelaskan setiap elemen utama dan beberapa metadata yang dapat Anda lampirkan.
Atribut aturan
Elemen <Rule>
adalah simpul akar dalam file XML. Ini dapat memiliki banyak atribut:
<Rule Name="CL" PageTemplate="tool" SwitchPrefix="/" Order="10"
xmlns="http://schemas.microsoft.com/build/2009/properties"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:sys="clr-namespace:System;assembly=mscorlib">
<Rule.DisplayName>
<sys:String>C/C++</sys:String>
</Rule.DisplayName>
Name
: Atribut Name adalah ID untukRule
. Ini harus unik di antara semua file XML halaman properti untuk proyek.PageTemplate
: Nilai atribut ini digunakan oleh UI untuk memilih dari kumpulan templat UI. Templat "alat" merender properti dalam format kisi standar. Nilai bawaan lainnya untuk atribut ini adalah "debugger" dan "generik". Lihat node Debugging dan node Umum, masing-masing, untuk melihat format UI yang dihasilkan dari menentukan nilai-nilai ini. UI untuk templat halaman "debugger" menggunakan kotak drop-down untuk beralih di antara properti debugger yang berbeda. Templat "generik" menampilkan kategori properti yang berbeda semuanya dalam satu halaman, dibandingkan dengan memiliki beberapa sub-node kategori di bawah simpulRule
. Atribut ini hanyalah saran untuk UI. File XML dirancang agar independen UI. UI yang berbeda mungkin menggunakan atribut ini untuk tujuan yang berbeda.SwitchPrefix
: Awalan yang digunakan dalam baris perintah untuk sakelar. Nilai"/"
akan menghasilkan sakelar yang terlihat seperti/ZI
, ,/nologo
/W3
, dan sebagainya.Order
: Saran kepada calon klien UI pada lokasi relatif iniRule
dibandingkan dengan semua aturan lain dalam sistem.xmlns
: Elemen XML standar. Anda dapat melihat tiga namespace yang tercantum. Atribut ini sesuai dengan namespace layanan untuk kelas deserialisasi XML, skema XML, dan namespace sistem, masing-masing.DisplayName
: Nama yang ditampilkan pada UI halaman properti untuk simpulRule
. Nilai ini dilokalkan. Kami membuatDisplayName
sebagai elemen turunanRule
daripada sebagai atribut (sepertiName
atauSwitchPrefix
) karena persyaratan alat pelokalan internal. Dari perspektif XML, keduanya setara. Jadi, Anda hanya dapat menjadikannya atribut untuk mengurangi kekacauan atau membiarkannya apa adanya.DataSource
: Properti penting ini memberi tahu sistem proyek lokasi untuk membaca dan menulis nilai properti, dan pengelompokannya (dijelaskan nanti). Untukcl.xml
, nilai-nilai ini adalah:<DataSource Persistence="ProjectFile" ItemType="ClCompile" Label="" HasConfigurationCondition="true" />
Persistence="ProjectFile"
memberi tahu sistem proyek bahwa semua properti untukRule
harus ditulis ke file proyek atau file lembar properti (tergantung pada simpul mana yang digunakan untuk menelurkan halaman properti). Nilai lain yang mungkin adalah"UserFile"
, yang akan menulis nilai ke.user
file.ItemType="ClCompile"
mengatakan bahwa properti akan disimpan sebagai metadata ItemDefinition atau metadata item (yang terakhir hanya jika halaman properti dihasilkan dari node file di penjelajah solusi) dari jenis item ini. Jika bidang ini tidak diatur, maka properti ditulis sebagai properti umum dalam PropertyGroup.Label=""
menunjukkan bahwa ketika properti ditulis sebagaiItemDefinition
metadata, label ItemDefinitionGroup induk akan kosong (setiap elemen MSBuild dapat memiliki Label). Visual Studio 2017 dan yang lebih baru menggunakan grup berlabel untuk menavigasi file proyek .vcxproj. Grup yang berisi sebagian besarRule
properti memiliki string kosong sebagai label.HasConfigurationCondition="true"
memberi tahu sistem proyek untuk membubuhkan kondisi konfigurasi ke nilai sehingga hanya berlaku untuk konfigurasi proyek saat ini (kondisi dapat ditempat ke grup induk atau nilai itu sendiri). Misalnya, buka halaman properti dari simpul proyek dan tetapkan nilai properti Perlakukan Peringatan Sebagai Kesalahan di bawah Properti > Konfigurasi C/C++ Umum ke "Ya". Nilai berikut ditulis ke file proyek. Perhatikan kondisi konfigurasi yang dilampirkan ke ItemDefinitionGroup induk.<ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'"> <ClCompile> <TreatWarningAsError>true</TreatWarningAsError> </ClCompile> </ItemDefinitionGroup>
Jika nilai ini diatur di halaman properti untuk file tertentu, seperti
stdafx.cpp
, maka nilai properti harus ditulis di bawahstdafx.cpp
item dalam file proyek seperti yang ditunjukkan Di Sini. Perhatikan bagaimana kondisi konfigurasi langsung dilampirkan ke metadata itu sendiri:<ItemGroup> <ClCompile Include="stdafx.cpp"> <TreatWarningAsError Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">true</TreatWarningAsError> </ClCompile> </ItemGroup>
Atribut lain yang
DataSource
tidak tercantum di sini adalahPersistedName
. Anda dapat menggunakan atribut ini untuk mewakili properti dalam file proyek menggunakan nama yang berbeda. Secara default, atribut ini diatur ke propertiName
.Properti individu dapat mengambil
DataSource
alih induknyaRule
. Dalam hal ini, lokasi untuk nilai properti tersebut akan berbeda dari properti lain diRule
.Ada atribut lain dari
Rule
, termasukDescription
danSupportsFileBatching
, yang tidak ditampilkan di sini. Set lengkap atribut yang berlaku untuk atauRule
pada elemen lain dapat diperoleh dengan menelusuri dokumentasi untuk jenis ini. Secara bergantian, Anda dapat memeriksa properti publik pada jenis diMicrosoft.Build.Framework.XamlTypes
namespace layanan diMicrosoft.Build.Framework.dll
rakitan.DisplayName
, ,PageTemplate
danOrder
adalah properti terkait UI yang ada dalam model data independen UI ini. Properti ini hampir dipastikan digunakan oleh UI apa pun yang digunakan untuk menampilkan halaman properti.DisplayName
danDescription
adalah dua properti yang ada di hampir semua elemen dalam file XML. Dan, kedua properti ini adalah satu-satunya yang dilokalkan.
Elemen kategori
Dapat Rule
memiliki beberapa Category
elemen. Urutan di mana kategori tercantum dalam file XML adalah saran kepada UI untuk menampilkan kategori dalam urutan yang sama. Misalnya, urutan kategori di bawah simpul C/C++ yang Anda lihat di UI sama dengan urutan di cl.xml
. Kategori sampel terlihat seperti ini:
<Category Name="Optimization">
<Category.DisplayName>
<sys:String>Optimization</sys:String>
</Category.DisplayName>
</Category>
Cuplikan ini menunjukkan Name
atribut dan DisplayName
yang telah dijelaskan sebelumnya. Sekali lagi, ada atribut lain yang Category
dapat dimiliki yang tidak ditampilkan dalam contoh. Anda dapat mempelajarinya dengan membaca dokumentasi atau dengan memeriksa rakitan menggunakan ildasm.exe
.
Elemen properti
Sebagian besar file aturan terdiri dari Property
elemen. Mereka berisi daftar semua properti dalam Rule
. Setiap properti dapat menjadi salah satu dari lima jenis yang mungkin ditampilkan dalam kerangka kerja dasar: BoolProperty
, , EnumProperty
, StringProperty
IntProperty
, dan StringListProperty
. Anda mungkin hanya memiliki beberapa jenis tersebut dalam file Anda. Properti memiliki sejumlah atribut yang memungkinkannya dijelaskan secara rinci. Dijelaskan StringProperty
di sini. Sisanya mirip.
<StringProperty Subtype="file" Name="ObjectFileName" Category="Output Files" Switch="Fo">
<StringProperty.DisplayName>
<sys:String>Object File Name</sys:String>
</StringProperty.DisplayName>
<StringProperty.Description>
<sys:String>Specifies a name to override the default object file name; can be file or directory name.(/Fo[name])</sys:String>
</StringProperty.Description>
</StringProperty>
Sebagian besar atribut dalam cuplikan telah dijelaskan sebelumnya. Yang baru adalah Subtype
, , Category
dan Switch
.
Subtype
adalah atribut yang hanya tersedia untukStringProperty
elemen danStringListProperty
. Ini memberikan informasi kontekstual. Misalnya, nilaifile
menunjukkan bahwa properti mewakili jalur file. Visual Studio menggunakan informasi kontekstual tersebut untuk meningkatkan pengalaman pengeditan. Misalnya, ini dapat menyediakan jendela Windows Explorer yang memungkinkan pengguna untuk memilih file secara visual sebagai editor properti.Category
: Kategori tempat properti ini berada. Cobalah untuk menemukan properti ini di bawah kategori File Output di UI.Switch
: Ketika aturan mewakili alat seperti alat pengkompilasi, sebagian besarRule
properti diteruskan sebagai sakelar ke alat yang dapat dieksekusi pada waktu build. Nilai atribut ini menunjukkan sakelar mana yang akan digunakan secara harfiah. Contoh<StringProperty>
menentukan bahwa sakelarnya harusFo
. Dikombinasikan denganSwitchPrefix
atribut pada indukRule
, properti ini diteruskan ke executable sebagai/Fo"Debug\"
. Ini terlihat di baris perintah untuk C/C++ di UI halaman properti.Atribut properti lainnya meliputi:
Visible
: Jika Anda tidak ingin properti Anda muncul di halaman properti, tetapi ingin properti tersedia pada waktu build, atur atribut ini kefalse
.ReadOnly
: Jika Anda ingin memberikan tampilan baca-saja dari nilai properti ini di halaman properti, atur atribut ini ketrue
.IncludeInCommandLine
: Pada waktu build, alat mungkin tidak memerlukan beberapa propertinya. Atur atribut ini kefalse
untuk mencegah properti tertentu diteruskan.
Saran dan Komentar
https://aka.ms/ContentUserFeedback.
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat:Kirim dan lihat umpan balik untuk