XML-Regeldateien für Eigenschaftenseiten

Die Projekteigenschaftenseiten in der IDE werden von XML-Dateien im Standardregelnordner konfiguriert. Die XML-Dateien beschreiben die Namen der Regeln, der Kategorien und der einzelnen Eigenschaften, deren Datentyp, Standardwerte und deren Anzeige. Wenn Sie eine Eigenschaft in der IDE festlegen, wird der neue Wert in der Projektdatei gespeichert.

Der Pfad zum Standardregelnordner hängt vom Gebietsschema und der verwendeten Version von Visual Studio ab. Bei der Developer-Eingabeaufforderung in Visual Studio 2019 oder einer höheren Version ist der Regelordner %VSINSTALLDIR%MSBuild\Microsoft\VC\<version>\<locale>\ mit v160 als Wert für <version> in Visual Studio 2019. <locale> ist eine LCID, z. B. 1033 für Englisch. In Visual Studio 2017 ist der Regelordner %VSINSTALLDIR%Common7\IDE\VC\VCTargets\<locale>\. Bei der Developer-Eingabeaufforderung in Visual Studio 2015 oder einer früheren Version ist der Regelordner %ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\<version>\<locale>\. Für jede installierte Edition von Visual Studio und jede Sprache gibt es einen eigenen Pfad. Beispielsweise könnte der Standardpfad für den Regelordner für Visual Studio 2019 Community Edition in englischer Sprache C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\MSBuild\Microsoft\VC\v160\1033\ sein.

Sie müssen nur die internen Funktionsweisen dieser Dateien und der Visual Studio-IDE in einigen Szenarien verstehen:

• Sie möchten eine benutzerdefinierte Eigenschaftenseite erstellen oder
• Sie möchten Ihre Projekteigenschaften anpassen, ohne die Visual Studio-IDE zu verwenden.

Inhalt von Regeldateien

Als Erstes öffnen wir die Eigenschaftenseiten für ein Projekt. Klicken Sie in Projektmappen-Explorer mit der rechten Maustaste auf den Projektknoten, und wählen Sie "Eigenschaften" aus:

Jeder Knoten unter Konfigurationseigenschaften wird als Regel bezeichnet. Eine Regel stellt manchmal ein einzelnes Tool wie den Compiler dar. Im Allgemeinen bezieht sich der Begriff auf etwas, das Eigenschaften enthält, die ausgeführt werden und die möglicherweise eine Ausgabe erzeugen. Jede Regel wird aus einer XML-Datei im Standardregelnordner aufgefüllt. Die hier gezeigte C/C++-Regel wird z. B. durch cl.xmlausgefüllt.

Jede Regel verfügt über eine Reihe von Eigenschaften, die in Kategorien unterteilt sind. Jeder Unterknoten unter einer Regel stellt eine Kategorie dar. Beispielsweise enthält der Optimierungsknoten unter C/C++ alle optimierungsbezogenen Eigenschaften des Compilertools. Die Eigenschaften und deren Werte werden im rechten Bereich in einem Rasterformat gerendert.

Sie können in Editor oder einem beliebigen XML-Editor öffnen cl.xml . Es wird ein Stammknoten mit dem Namen angezeigt Rule. Es definiert die gleiche Liste von Eigenschaften, die in der Benutzeroberfläche angezeigt werden, zusammen mit zusätzlichen Metadaten.

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

Es gibt eine XML-Datei für jeden Knoten unter "Konfigurationseigenschaften " auf der Benutzeroberfläche der Eigenschaftenseiten. Sie können regeln in der Benutzeroberfläche hinzufügen oder entfernen: Dazu werden Speicherorte in die entsprechenden XML-Dateien im Projekt eingeschlossen oder entfernt. So enthält dies beispielsweise Microsoft.CppBuild.targets (eine Ebene höher als der Ordner "1033") Folgendes cl.xml:

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

Wenn Sie alle Daten entfernen cl.xml , verfügen Sie über dieses grundlegende Framework:

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

Im nächsten Abschnitt werden die einzelnen Hauptelemente und einige der Metadaten beschrieben, die Sie anfügen können.

Regelattribute

Ein <Rule> Element ist der Stammknoten in der XML-Datei. Es kann viele Attribute haben:

<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: Das Name-Attribut ist eine ID für die Rule. Es muss zwischen allen XML-Dateien der Eigenschaftenseite für ein Projekt eindeutig sein.

• PageTemplate: Der Wert dieses Attributs wird von der Benutzeroberfläche verwendet, um aus einer Sammlung von UI-Vorlagen auszuwählen. Die Vorlage „tool“ rendert die Eigenschaften in einem Standardrasterformat. Weitere integrierte Werte für dieses Attribut sind „debugger“ und „generic“. Betrachten Sie die Knoten „Debuggen“ und „Allgemein“, um zu sehen, welches Format sich für die Benutzeroberfläche ergibt, wenn Sie diese Werte festlegen. Die Benutzeroberfläche für die Seitenvorlage "Debugger" verwendet ein Dropdownfeld, um zwischen den Eigenschaften verschiedener Debugger zu wechseln. Die Vorlage "generic" zeigt unterschiedliche Eigenschaftenkategorien auf einer Seite an, im Gegensatz zu mehreren Unterknoten der Kategorie unter dem Rule Knoten. Dieses Attribut ist nur ein Vorschlag für die Benutzeroberfläche. Die XML-Datei ist so konzipiert, dass sie unabhängig von der Benutzeroberfläche ist. Eine andere Benutzeroberfläche verwendet dieses Attribut möglicherweise für andere Zwecke.

• SwitchPrefix: Das Präfix, das in der Befehlszeile für die Schalter verwendet wird. Ein Wert von "/" würde zu Schaltern führen, die wie /ZI, /nologo, , /W3usw. aussehen.

• Order: Ein Vorschlag für einen potenziellen UI-Client an der relativen Position dieses Rule Clients im Vergleich zu allen anderen Regeln im System.

• xmlns: Ein XML-Standardelement. Drei Namespaces werden aufgeführt. Diese Attribute entsprechen den Namespaces für die XML-Deserialisierungsklassen, das XML-Schema und den Systemnamespace.

• DisplayName: Der Name, der auf der Benutzeroberfläche der Eigenschaftenseite für den Rule Knoten angezeigt wird. Dieser Wert wird lokalisiert. Wir haben aufgrund interner Lokalisierungstoolanforderungen als untergeordnetes Element Rule anstelle eines Attributs (wie Name oder SwitchPrefix) erstelltDisplayName. Aus XML-Sicht sind beide gleich. Sie können deshalb ein Attribut daraus erstellen, um die Übersichtlichkeit zu verbessern, oder keine Änderung vornehmen.

• DataSource: Diese wichtige Eigenschaft weist dem Projektsystem den Speicherort zum Lesen und Schreiben des Eigenschaftswerts und deren Gruppierung (weiter unten erläutert) an. Für cl.xml, sind die folgenden Werte:

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

  • Persistence="ProjectFile" teilt dem Projektsystem mit, dass alle Eigenschaften für die Rule Projektdatei oder die Eigenschaftenblattdatei geschrieben werden sollen (je nachdem, welcher Knoten zum Spawen der Eigenschaftenseiten verwendet wurde). Der andere mögliche Wert ist "UserFile", der den Wert in die .user Datei schreibt.

  • ItemType="ClCompile" gibt an, dass die Eigenschaften als ItemDefinition-Metadaten oder als Elementmetadaten (nur, wenn die Eigenschaftenseiten aus einem Dateiknoten im Projektmappen-Explorer erzeugt wurden) dieses Elementtyps gespeichert werden. Wenn dieses Feld nicht festgelegt ist, wird die Eigenschaft als allgemeine Eigenschaft in einer PropertyGroup geschrieben.

  • Label="" gibt an, dass die Bezeichnung des übergeordneten Elements „ItemDefinitionGroup“ leer ist (jedes MSBuild-Element kann eine Bezeichnung besitzen), wenn die Eigenschaften als ItemDefinition-Metadaten geschrieben werden. Visual Studio 2017 und höher verwendet Gruppen mit Bezeichnung, um in der VCXPROJ-Projektdatei zu navigieren. Die Gruppen, die die meisten Rule Eigenschaften enthalten, weisen eine leere Zeichenfolge als Bezeichnung auf.

  • HasConfigurationCondition="true" weist das Projektsystem an, eine Konfigurationsbedingung an den Wert anzufügen, damit dieser nur für die aktuelle Projektkonfiguration wirksam ist. Die Konfiguration kann an die übergeordnete Gruppe oder an den Wert angefügt werden. Öffnen Sie beispielsweise die Eigenschaftenseiten vom Projektknoten, und legen Sie den Wert der Eigenschaft "Warnungen als Fehler behandeln" unter Konfigurationseigenschaften > C/C++ allgemein auf "Ja" fest. Der folgende Wert wird in die Projektdatei geschrieben. Beachten Sie die Konfigurationsbedingung, die an das übergeordnete Element „ItemDefinitionGroup“ angefügt ist.

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

    Wenn dieser Wert auf der Eigenschaftenseite für eine bestimmte Datei festgelegt wird, z stdafx.cpp. B. , sollte der Eigenschaftswert unter dem stdafx.cpp Element in der Projektdatei geschrieben werden, wie hier gezeigt. Beachten Sie, wie die Konfigurationsbedingung direkt an die Metadaten selbst angefügt wird:

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

  Ein weiteres Attribut, das DataSource hier nicht aufgeführt ist, ist PersistedName. Sie können dieses Attribut verwenden, um eine Eigenschaft in der Projektdatei mit einem anderen Namen darzustellen. Dieses Attribut ist standardmäßig auf die Eigenschaft Namefestgelegt.

  Eine einzelne Eigenschaft kann das DataSource übergeordnete RuleElement überschreiben. In diesem Fall unterscheidet sich der Speicherort für den Wert dieser Eigenschaft von anderen Eigenschaften in der Rule.

• Es gibt weitere Attribute eines Rule, einschließlich Description und SupportsFileBatching, die hier nicht angezeigt werden. Der vollständige Satz von Attributen, die für ein Rule oder für ein anderes Element gelten, können durch Durchsuchen der Dokumentation für diese Typen abgerufen werden. Alternativ können Sie die öffentlichen Eigenschaften von Typen im Microsoft.Build.Framework.XamlTypes-Namespace der Microsoft.Build.Framework.dll-Assembly überprüfen.

• DisplayName, PageTemplateund Order sind UI-bezogene Eigenschaften, die in diesem ansonsten benutzeroberflächenunabhängigen Datenmodell vorhanden sind. Diese Eigenschaften werden meistens von allen Benutzeroberflächen verwendet, die zum Anzeigen von Eigenschaftenseiten verwendet werden. DisplayName und Description sind zwei Eigenschaften, die für fast alle Elemente in der XML-Datei vorhanden sind. Und diese beiden Eigenschaften sind die einzigen, die lokalisiert werden.

Kategorieelemente

A Rule kann mehrere Category Elemente aufweisen. Die Reihenfolge, in der die Kategorien in der XML-Datei aufgeführt werden, ist ein Vorschlag für die Benutzeroberfläche, die Kategorien in derselben Reihenfolge anzuzeigen. Beispielsweise entspricht die Reihenfolge der Kategorien unter dem C/C++-Knoten, den Sie in der Benutzeroberfläche sehen, der Reihenfolge in cl.xml. Eine Beispielkategorie sieht folgendermaßen aus:

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

Dieser Codeausschnitt zeigt die Name zuvor beschriebenen Attribute und DisplayName Attribute. Es gibt erneut andere Attribute Category , die im Beispiel nicht angezeigt werden können. Sie können sich über diese Informationen informieren, indem Sie die Dokumentation lesen oder die Assemblys mithilfe ildasm.exeder Assemblys untersuchen.

Eigenschaftselemente

Der Großteil der Regeldatei besteht aus Property Elementen. Sie enthalten die Liste aller Eigenschaften in einem Rule. Jede Eigenschaft kann eine der fünf möglichen Typen sein, die im Grundlegenden Framework gezeigt werden: BoolProperty, , , EnumProperty, IntProperty, StringPropertyund StringListProperty. Möglicherweise haben Sie nur einige dieser Typen in Ihrer Datei. Eine Eigenschaft verfügt über eine Reihe von Attributen, mit denen sie detailliert beschrieben werden können. Dies StringProperty wird hier beschrieben. Der Rest ist ähnlich.

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

Die meisten Attribute im Codeausschnitt wurden zuvor bereits beschrieben. Die neuen sind Subtype, Categoryund Switch.

• Subtype ist ein Attribut nur für StringProperty und StringListProperty Elemente verfügbar. Es gibt kontextbezogene Informationen. Der Wert file gibt beispielsweise an, dass die Eigenschaft einen Dateipfad darstellt. Visual Studio verwendet solche kontextbezogenen Informationen, um die Bearbeitung zu verbessern. Beispielsweise kann es ein Windows Explorer-Fenster bereitstellen, mit dem der Benutzer die Datei visuell als Editor der Eigenschaft auswählen kann.

• Category: Die Kategorie, unter der diese Eigenschaft fällt. Suchen Sie diese Eigenschaft in der Kategorie Ausgabedateien auf der Benutzeroberfläche.

• Switch: Wenn eine Regel ein Tool wie das Compilertool darstellt, werden die meisten Rule Eigenschaften als Schalter zur ausführbaren Datei des Tools zur Buildzeit übergeben. Der Wert dieses Attributs gibt an, welches Switchliteral verwendet werden soll. Das <StringProperty> Beispiel gibt an, dass der Schalter sein Fosoll. In Kombination mit dem SwitchPrefix Attribut für das übergeordnete RuleElement wird diese Eigenschaft an die ausführbare Datei übergeben als /Fo"Debug\". Sie ist in der Befehlszeile für C/C++ in der Eigenschaftenseiten-UI sichtbar.

  Folgende weitere Eigenschaftenattribute sind vorhanden:

• Visible: Wenn Ihre Eigenschaft nicht auf den Eigenschaftenseiten angezeigt werden soll, sie aber zur Erstellungszeit verfügbar sein soll, legen Sie dieses Attribut auf false.

• ReadOnly: Wenn Sie eine schreibgeschützte Ansicht des Werts dieser Eigenschaft auf den Eigenschaftenseiten bereitstellen möchten, legen Sie dieses Attribut auf true.

• IncludeInCommandLine: Zur Erstellungszeit benötigt ein Tool möglicherweise einige seiner Eigenschaften nicht. Legen Sie dieses Attribut fest, um zu false verhindern, dass eine bestimmte Eigenschaft übergeben wird.