屬性頁 XML 規則檔

IDE 中的專案屬性頁是由預設規則資料夾中的 XML 檔案所設定。 XML 檔案描述規則的名稱、類別和個別屬性、其資料類型、預設值，以及如何顯示它們。 當您在 IDE 中設定屬性時，新的值會儲存在專案檔中。

預設規則資料夾的路徑取決於使用中的地區設定和 Visual Studio 版本。 在 Visual Studio 2019 或更新版本的開發人員命令提示字元中，rules 資料夾是 %VSINSTALLDIR%MSBuild\Microsoft\VC\<version>\<locale>\ ，其中 <version> 值位於 v160 Visual Studio 2019 中。 <locale>例如， 1033 是英文的 LCID。 在 Visual Studio 2017 中，rules 資料夾是 %VSINSTALLDIR%Common7\IDE\VC\VCTargets\<locale>\ 。 在 Visual Studio 2015 或更早版本的開發人員命令提示字元中，rules 資料夾是 %ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\<version>\<locale>\ 。 您將針對已安裝的每個 Visual Studio 版本，以及每個語言使用不同的路徑。 例如，Visual Studio 2019 Community Edition 的預設規則資料夾路徑可以是 C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\MSBuild\Microsoft\VC\v160\1033\ 。

在幾個案例中，您只需要瞭解這些檔案和 Visual Studio IDE 的內部運作：

• 您想要建立自訂屬性頁，或
• 您想要自訂專案屬性，而不需使用 Visual Studio IDE。

規則檔案的內容

首先，讓我們開啟專案的屬性頁。 以滑鼠右鍵按一下方案總管 中的 專案節點，然後選擇 [ 屬性 ]：

[組態屬性] 底下的 每個節點稱為規則 。 規則有時代表單一工具，例如編譯器。 一般而言，詞彙是指具有屬性、執行且可能會產生某些輸出的內容。 每個規則都會從預設規則資料夾中的 XML 檔案填入。 例如，此處顯示的 C/C++ 規則會填入 cl.xml 。

每個規則都有一組屬性，這些屬性會組織成 類別 。 規則下的每個子節點都代表類別。 例如， C/C++ 底下的 [優化 ] 節點包含編譯器工具的所有優化相關屬性。 屬性及其值會以右窗格的格線格式呈現。

您可以在記事本或任何 XML 編輯器中開啟 cl.xml 。 您會看到名為 Rule 的根節點。 它會定義 UI 中顯示的相同屬性清單，以及其他中繼資料。

<?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>

屬性頁 UI 中的 [組態屬性 ] 下 ，每個節點都有一個 XML 檔案。 您可以在 UI 中新增或移除規則：它可藉由包含或移除專案中對應 XML 檔案的位置來完成。 例如，它是如何 Microsoft.CppBuild.targets （找到高於 1033 資料夾的一個層級）包含 cl.xml ：

<PropertyPageSchema Condition="'$(ConfigurationType)' != 'Utility'" Include="$(VCTargetsPath)$(LangID)\cl.xml"/>

如果您移除 cl.xml 所有資料，您就會有下列基本架構：

<?xml version="1.0" encoding="utf-8"?>
<Rule>
  <Rule.DataSource />
  <Rule.Categories>
    <Category />
    <!-- . . . -->
  </Rule.Categories>
  <BoolProperty />
  <EnumProperty />
  <IntProperty />
  <StringProperty />
  <StringListProperty />
</Rule>

下一節說明每個主要元素，以及您可以附加的一些中繼資料。

規則屬性

元素 <Rule> 是 XML 檔案中的根節點。 它可以有許多屬性：

<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：Name 屬性是 的 Rule 識別碼。 在專案的所有屬性頁 XML 檔案中，它必須是唯一的。

• PageTemplate：UI 會使用這個屬性的值，從 UI 範本的集合中選擇。 "tool" 範本會以標準方格格式呈現屬性。 此屬性的其他內建值還包括 "debugger" 和 "generic"。 請分別參閱 [偵錯] 節點和 [一般] 節點，以了解透過指定這些值所產生的 UI 格式。 「偵錯工具」頁面範本的 UI 會使用下拉式方塊來切換不同偵錯工具的屬性。 「泛型」範本會在一個頁面中顯示不同的屬性類別，而不是在節點下 Rule 有多個類別子節點。 這個屬性只是 UI 的建議。 XML 檔案是設計成與 UI 無關。 不同 UI 可能會基於不同目的使用此屬性。

• SwitchPrefix：參數命令列中使用的前置詞。 的值 "/" 會導致參數看起來像 /ZI 、 /nologo 、 /W3 等。

• Order：與系統中所有其他規則相比，針對這個 Rule 相對位置上潛在 UI 用戶端的建議。

• xmlns：標準 XML 專案。 您可以看到列出三個命名空間。 這些屬性分別對應至 XML 還原序列化類別、XML 架構和系統命名空間的命名空間。

• DisplayName：節點屬性頁 UI Rule 上顯示的名稱。 此值會當地語系化。 我們建立為 的 Rule 子專案，而不是因為內部當地語系化工具需求而建立 DisplayName 為屬性（例如 Name 或 SwitchPrefix ）。 從 XML 的觀點來看，兩者都是相等的。 因此，您可以直接將它設為屬性來減少雜亂，或讓它保持原狀。

• DataSource：這個重要的屬性會告訴專案系統要讀取和寫入屬性值的位置，以及其分組方式（稍後說明）。 針對 cl.xml ，這些值為：

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

  • Persistence="ProjectFile" 告知專案系統，應該將 的所有屬性 Rule 寫入專案檔或屬性工作表檔案（視使用哪一個節點來繁衍屬性頁而定）。 另一個可能的值是 "UserFile" ，它會將值寫入檔案 .user 。

  • ItemType="ClCompile"，指出屬性將儲存為此項目類型的 ItemDefinition 中繼資料或項目中繼資料 (後者僅限於從 [方案總管] 中的檔案節點繁衍屬性頁時)。 如果未設定此欄位，則會將 屬性寫入為 PropertyGroup 中的通用屬性。

  • Label=""，表示當屬性會寫入作為 ItemDefinition 中繼資料時，父 ItemDefinitionGroup 的標籤會是空白 (每個 MSBuild 項目可以有一個 Label)。 Visual Studio 2017 和更新版本會使用已標記的群組來巡覽 .vcxproj 專案檔。 包含大部分 Rule 屬性的群組具有空白字串做為標籤。

  • HasConfigurationCondition="true"，告知專案系統將組態條件附加至值，只有目前的專案組態才會生效 (條件可附加至父群組或值本身)。 例如，開啟專案節點的屬性頁，並將 [組態屬性 > C/C++ 一般 ] 底下的 [警告] 設定為 [錯誤] 的值 設定為 [是]。 下列值會寫入專案檔。 注意附加至父 ItemDefinitionGroup 的組態條件。

    <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">
      <ClCompile>
        <TreatWarningAsError>true</TreatWarningAsError>
      </ClCompile>
    </ItemDefinitionGroup>
    

    如果在特定檔案的屬性頁面中設定這個值，例如 stdafx.cpp ，則屬性值應該寫入專案檔中的專案底下 stdafx.cpp ，如下所示。 請注意設定條件如何直接附加至中繼資料本身：

    <ItemGroup>
      <ClCompile Include="stdafx.cpp">
        <TreatWarningAsError Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">true</TreatWarningAsError>
      </ClCompile>
    </ItemGroup>
    

  這裡未列出的另一個屬性 DataSource 是 PersistedName 。 您可以使用此屬性 (Attribute) 代表專案檔中使用不同名稱的屬性 (Property)。 根據預設，此屬性會設定為 屬性的 Name 。

  個別屬性可以覆寫 DataSource 其父系 Rule 的 。 在此情況下，該屬性值的位置會與 中的其他 Rule 屬性不同。

• 還有其他屬性 Rule ，包括 Description 和 SupportsFileBatching ，此處未顯示。 您可以流覽這些類型的檔，以取得適用于 Rule 或其他任何元素的完整屬性集。 或者，您可以在 Microsoft.Build.Framework.dll 組件的 Microsoft.Build.Framework.XamlTypes 命名空間中，查看這些類型的公用屬性。

• DisplayName、 PageTemplate 和 Order 是存在於這個與 UI 無關之資料模型中的 UI 相關屬性。 這些屬性幾乎一定可供用來顯示屬性頁的 UI 使用。 DisplayName 和 Description 是 XML 檔案中幾乎所有元素上都存在的兩個屬性。 而且，這兩個屬性是唯一當地語系化的屬性。

類別專案

Rule可以有多個 Category 專案。 XML 檔案中列出類別的順序，是 UI 以相同順序顯示類別的建議。 例如，您在 UI 中看到的 C/C++ 節點下類別順序與 中的 cl.xml 順序相同。 範例分類看起來如下：

<Category Name="Optimization">
  <Category.DisplayName>
    <sys:String>Optimization</sys:String>
  </Category.DisplayName>
</Category>

此程式碼片段會顯示 Name 先前所述的 和 DisplayName 屬性。 同樣地，還有其他屬性，a Category 可以有未顯示在範例中。 您可以藉由閱讀檔或使用 來檢查元件 ildasm.exe 來瞭解它們。

屬性元素

大部分的規則檔案是由元素所組成 Property 。 它們包含 中 Rule 所有屬性的清單。 每個屬性都可以是基本架構中顯示的五種可能類型之一： BoolProperty 、、 EnumProperty 、 IntProperty 、 StringProperty 和 StringListProperty 。 您的檔案中可能只有少數類型。 屬性有數個屬性，可讓其詳細描述。 StringProperty這裡將說明 。 其餘部分也類似。

<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>

程式碼片段中的大部分屬性先前都已描述。 新的是 Subtype 、 Category 和 Switch 。

• Subtype 是僅適用于 StringProperty 和 StringListProperty 元素的屬性。 它提供內容資訊。 例如，值 file 表示 屬性代表檔案路徑。 Visual Studio 會使用這類內容資訊來增強編輯體驗。 例如，它可能會提供 Windows 檔案總管視窗，讓使用者以視覺化方式選擇檔案做為屬性的編輯器。

• Category：這個屬性所屬的類別。 請嘗試在 UI 中的 [輸出檔案] 分類下找到此屬性。

• Switch：當規則代表編譯器工具之類的工具時，大部分 Rule 屬性都會在建置時當做參數傳遞至工具可執行檔。 這個屬性的值表示要使用的參數常值。 此 <StringProperty> 範例會指定其參數應該是 Fo 。 結合 SwitchPrefix 父 Rule 系 上的 屬性，這個屬性會以 的形式 /Fo"Debug\" 傳遞至可執行檔。 在屬性頁 UI 中，C/C++ 的命令列中會顯示它。

  其他屬性 (Property) 的屬性 (Attribute) 包括：

• Visible：如果您不想讓屬性出現在屬性頁中，但想要在建置時使用此屬性，請將此屬性設定為 false 。

• ReadOnly：如果您想要在屬性頁中提供此屬性值的唯讀檢視，請將此屬性設定為 true 。

• IncludeInCommandLine：在建置階段，工具可能不需要其部分屬性。 將此屬性設定為 false ，以防止傳遞特定屬性。