XML-Regeldateien für Eigenschaftenseiten

Die Projekteigenschaftenseiten in der IDE werden durch XML-Dateien im Standardregelordner konfiguriert. Die XML-Dateien beschreiben die Namen der Regeln, die Kategorien und die 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 Standardregelordner 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 in einigen Szenarien die interne Funktionsweise dieser Dateien und der Visual Studio-IDE 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

Öffnen Sie zunächst 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 Über Eigenschaften verfügt, das ausgeführt wird und eine Ausgabe erzeugen kann. Jede Regel wird aus einer XML-Datei im Standardregelordner aufgefüllt. Die hier gezeigte C/C++-Regel wird beispielsweise mit cl.xmlaufgefüllt.

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

Sie können im Editor oder in einem beliebigen XML-Editor öffnen cl.xml . Es wird ein Stammknoten namens angezeigt Rule. Es definiert die gleiche Liste der Eigenschaften, die auf 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 auf der Benutzeroberfläche hinzufügen oder entfernen. Dies erfolgt durch Einfügen oder Entfernen von Speicherorten zu entsprechenden XML-Dateien im Projekt. Es ist z. B., wie Microsoft.CppBuild.targets (gefunden eine Ebene höher als der Ordner 1033) enthält 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 metadaten beschrieben, die Sie anfügen können.

Regelattribute

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

<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 .Rule Sie muss für alle 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 Benutzeroberflächenvorlagen 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 "generische" Vorlage zeigt verschiedene Eigenschaftenkategorien auf einer Seite an, anstatt mehrere Kategorieunterknoten unter dem Rule Knoten zu haben. Dieses Attribut ist nur ein Vorschlag für die Benutzeroberfläche. Die XML-Datei ist so konzipiert, dass sie von der Benutzeroberfläche unabhängig 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 Switches verwendet wird. Ein Wert von "/" würde zu Schaltern führen, die wie /ZI, /nologo, /W3usw. aussehen.

• Order: Ein Vorschlag für einen potenziellen Benutzeroberflächenclient an der relativen Position dieser Rule 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 bzw. 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 Lokalisierungstoolsanforderungen ein untergeordnetes Element von erstellt DisplayName und nicht als Attribut (zName. B. oder SwitchPrefix).Rule Aus XML-Sicht sind beide gleichwertig. Sie können deshalb ein Attribut daraus erstellen, um die Übersichtlichkeit zu verbessern, oder keine Änderung vornehmen.

• DataSource: Diese wichtige Eigenschaft teilt dem Projektsystem den Speicherort mit, den Eigenschaftswert und dessen Gruppierung zu lesen und zu schreiben (später erläutert). Für cl.xmlsind dies folgende Werte:

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

  • Persistence="ProjectFile" teilt dem Projektsystem mit, dass alle Eigenschaften für die Rule in die Projektdatei oder die Eigenschaftenblattdatei geschrieben werden sollen (je nachdem, welcher Knoten zum Erstellen 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 gemeinsame 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, verfügen über eine leere Zeichenfolge als Bezeichnung.

  • 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 außerhalb des Projektknotens, 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 ist, z stdafx.cpp. B. , sollte der Eigenschaftswert wie hier gezeigt unter das stdafx.cpp Element in der Projektdatei geschrieben werden. 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 von, 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. Standardmäßig ist dieses Attribut auf den der -Eigenschaft Namefestgelegt.

  Eine einzelne Eigenschaft kann die DataSource ihrer übergeordneten Ruleüberschreiben. In diesem Fall unterscheidet sich der Speicherort für den Wert dieser Eigenschaft von anderen Eigenschaften im Rule.

• Es gibt andere Attribute von Rule, einschließlich Description und SupportsFileBatching, die hier nicht angezeigt werden. Der vollständige Satz von Attributen, die für ein Rule oder ein anderes Element gelten, kann abgerufen werden, indem Sie die Dokumentation zu diesen Typen durchsuchen. 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 sind.

Category-Elemente

Ein Rule kann über mehrere Category Elemente verfügen. 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 auf 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 Attribute und DisplayName , die zuvor beschrieben wurden. Auch hier gibt es andere Attribute, die im Category Beispiel nicht angezeigt werden. Sie können sich darüber informieren, indem Sie die Dokumentation lesen oder die Assemblys mithilfe von ildasm.exeuntersuchen.

Eigenschaftenelemente

Die Regeldatei besteht größtenteils Property aus Elementen. Sie enthalten die Liste aller Eigenschaften in einem Rule. Jede Eigenschaft kann einer der fünf möglichen Typen sein, die im Basisframework angezeigt 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 ausführlich beschrieben werden kann. Die 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, das nur für StringProperty - und StringListProperty -Elemente verfügbar ist. Sie enthält kontextbezogene Informationen. Der Wert file gibt beispielsweise an, dass die -Eigenschaft einen Dateipfad darstellt. Visual Studio verwendet solche kontextbezogenen Informationen, um die Bearbeitungserfahrung zu verbessern. Für instance kann ein Windows-Explorer-Fenster bereitgestellt werden, in dem der Benutzer die Datei visuell als Editor der Eigenschaft auswählen kann.

• Category: Die Kategorie, unter die 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 zur Buildzeit als Wechsel an die ausführbare Tool-Datei übergeben. Der Wert dieses Attributs gibt an, welches Switchliteral verwendet werden soll. Im <StringProperty> Beispiel wird angegeben, dass der Switch sein Fosoll. In Kombination mit dem SwitchPrefix -Attribut auf dem übergeordneten Rulewird diese Eigenschaft als /Fo"Debug\"an die ausführbare Datei übergeben. Sie wird in der Befehlszeile für C/C++ auf der Benutzeroberfläche der Eigenschaftenseite angezeigt.

  Folgende weitere Eigenschaftenattribute sind vorhanden:

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

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

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