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. 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 untuk Rule. 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 simpul Rule . 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 ini Rule 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 simpul Rule . Nilai ini dilokalkan. Kami membuat DisplayName sebagai elemen turunan Rule daripada sebagai atribut (seperti Name atau SwitchPrefix) 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). Untuk cl.xml, nilai-nilai ini adalah:

  <DataSource Persistence="ProjectFile" ItemType="ClCompile" Label="" HasConfigurationCondition="true" />
  

  • Persistence="ProjectFile" memberi tahu sistem proyek bahwa semua properti untuk Rule 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 sebagai ItemDefinition 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 besar Rule 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 bawah stdafx.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 adalah PersistedName. Anda dapat menggunakan atribut ini untuk mewakili properti dalam file proyek menggunakan nama yang berbeda. Secara default, atribut ini diatur ke properti Name.

  Properti individu dapat mengambil DataSource alih induknya Rule. Dalam hal ini, lokasi untuk nilai properti tersebut akan berbeda dari properti lain di Rule.

• Ada atribut lain dari Rule, termasuk Description dan SupportsFileBatching, yang tidak ditampilkan di sini. Set lengkap atribut yang berlaku untuk atau Rule pada elemen lain dapat diperoleh dengan menelusuri dokumentasi untuk jenis ini. Secara bergantian, Anda dapat memeriksa properti publik pada jenis di Microsoft.Build.Framework.XamlTypes namespace layanan di Microsoft.Build.Framework.dll rakitan.

• DisplayName, , PageTemplatedan Order 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 dan Description 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, StringPropertyIntProperty, 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, , Categorydan Switch.

• Subtype adalah atribut yang hanya tersedia untuk StringProperty elemen dan StringListProperty . Ini memberikan informasi kontekstual. Misalnya, nilai file 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 besar Rule 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 harus Fo. Dikombinasikan dengan SwitchPrefix atribut pada induk Rule, 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 ke false.

• ReadOnly: Jika Anda ingin memberikan tampilan baca-saja dari nilai properti ini di halaman properti, atur atribut ini ke true.

• IncludeInCommandLine: Pada waktu build, alat mungkin tidak memerlukan beberapa propertinya. Atur atribut ini ke false untuk mencegah properti tertentu diteruskan.