Verwenden von Regelsätzen zum Festlegen von C++-Regeln für die Ausführung

In Visual Studio können Sie einen benutzerdefinierten Regelsatz erstellen und ändern, um bestimmte Projektanforderungen zu erfüllen, die mit der Codeanalyse verknüpft sind. Die Standardregelsätze werden in %VSINSTALLDIR%\Team Tools\Static Analysis Tools\Rule Sets.

Visual Studio 2017, Version 15.7 und höher: Sie können benutzerdefinierte Regelsätze mithilfe eines beliebigen Text-Editors erstellen und in Befehlszeilenbuilds anwenden, unabhängig davon, welches Buildsystem Sie verwenden. Weitere Informationen finden Sie unter /analyze:ruleset.

Zum Erstellen eines benutzerdefinierten C++-Regelsatzes in Visual Studio muss ein C/C++-Projekt in der Visual Studio-IDE geöffnet sein. Anschließend öffnen Sie einen Standardregelsatz im Regelsatz-Editor und fügen dann bestimmte Regeln hinzu oder entfernen diese, und ändern Sie optional die Aktion, die auftritt, wenn die Codeanalyse feststellt, dass eine Regel verletzt wurde.

Zum Erstellen eines neuen benutzerdefinierten Regelsatzes speichern Sie diesen unter einem neuen Dateinamen. Der benutzerdefinierte Regelsatz wird dem Projekt automatisch zugewiesen.

So erstellen Sie eine benutzerdefinierte Regel aus einem einzelnen vorhandenen Regelsatz

1. Öffnen Sie in Projektmappen-Explorer das Kontextmenü für das Projekt, und wählen Sie dann "Eigenschaften" aus.

2. Wählen Sie im Dialogfeld Eigenschaftenseiten die Microsoft-Eigenschaftenanalyseseite> für Konfigurationseigenschaften>aus.

3. Führen Sie in der Dropdownliste "Aktive Regeln " eine der folgenden Aktionen aus:

   • Wählen Sie den Regelsatz aus, den Sie anpassen möchten.

     - oder -

   • Wählen Sie <"Durchsuchen" aus,> um einen vorhandenen Regelsatz anzugeben, der nicht in der Liste enthalten ist.

4. Wählen Sie " Öffnen" aus, um die Regeln im Regelsatz-Editor anzuzeigen.

So ändern Sie einen Regelsatz im Regelsatz-Editor

• Um den Anzeigenamen des Regelsatzes zu ändern, wählen Sie im Menü "Ansicht" die Option "Eigenschaftenfenster" aus. Geben Sie im Feld Name den gewünschten Anzeigenamen ein. Der Anzeigename kann sich vom Dateinamen unterscheiden.

• Wenn Sie einem benutzerdefinierten Regelsatz alle Regeln der Gruppe hinzufügen möchten, aktivieren Sie das Kontrollkästchen für die Gruppe. Wenn Sie alle Regeln der Gruppe entfernen möchten, deaktivieren Sie das Kontrollkästchen.

• Wenn Sie dem benutzerdefinierten Regelsatz eine bestimmte Regel hinzufügen möchten, aktivieren Sie das Kontrollkästchen für die Regel. Wenn Sie die Regel aus dem Regelsatz entfernen möchten, deaktivieren Sie das zugehörige Kontrollkästchen.

• Wenn Sie die Aktion ändern möchten, die ausgeführt wird, wenn eine Regel in einer Codeanalyse verletzt wird, wählen Sie das Feld "Aktion " für die Regel aus, und wählen Sie dann einen der folgenden Werte aus:

  Warnung – generiert eine Warnung.

  Fehler – generiert einen Fehler.

  Informationen – generiert eine Nachricht.

  Keine – deaktiviert die Regel. Diese Aktion ist mit der Aktion identisch, die beim Entfernen der Regel aus dem Regelsatz ausgeführt wird.

So gruppieren, filtern oder ändert Sie Felder auf der Symbolleiste des Regelsatz-Editors

• Um die Regeln in allen Gruppen zu erweitern, wählen Sie "Alle erweitern" aus.

• Um die Regeln in allen Gruppen zu reduzieren, wählen Sie "Alle reduzieren" aus.

• Um das Feld zu ändern, nach dem Regeln gruppiert werden, wählen Sie das Feld aus der Liste " Gruppieren nach " aus. Um die Gruppierung der Regeln aufzuheben, wählen Sie <"Keine"> aus.

• Um Felder in Regelspalten hinzuzufügen oder zu entfernen, wählen Sie "Spaltenoptionen" aus.

• Wenn Sie Regeln ausblenden möchten, die nicht für die aktuelle Lösung gelten, wählen Sie " Regeln ausblenden", die nicht für die aktuelle Lösung gelten.

• Wenn Sie zwischen dem Ein- und Ausblenden von Regeln wechseln möchten, die der Fehleraktion zugewiesen sind, wählen Sie " Regeln anzeigen" aus, die Codeanalysefehler generieren können.

• Wenn Sie zwischen dem Ein- und Ausblenden von Regeln wechseln möchten, die der Warnungsaktion zugewiesen sind, wählen Sie " Regeln anzeigen" aus, die Codeanalysewarnungen generieren können.

• Um zwischen dem Ein- und Ausblenden von Regeln zu wechseln, denen die Aktion "Keine" zugewiesen ist, wählen Sie " Regeln anzeigen" aus, die nicht aktiviert sind.

• Wenn Sie microsoft-Standardregelsätze zum aktuellen Regelsatz hinzufügen oder entfernen möchten, wählen Sie "Untergeordnete Regelsätze hinzufügen oder entfernen" aus.

So erstellen Sie einen Regelsatz in einem Text-Editor

Sie können einen benutzerdefinierten Regelsatz in einem Text-Editor erstellen, an einem beliebigen Ort mit einer .ruleset Erweiterung speichern und mit der /analyze:ruleset Compileroption anwenden.

Das folgende Beispiel zeigt eine einfache Regelsatzdatei, die Sie als Ausgangspunkt verwenden können:

<?xml version="1.0" encoding="utf-8"?>
<RuleSet Name="New Rule Set" Description="New rules to apply." ToolsVersion="10.0">
  <Rules AnalyzerId="Microsoft.Analyzers.NativeCodeAnalysis" RuleNamespace="Microsoft.Rules.Native">
    <Rule Id="C6001" Action="Warning" />
    <Rule Id="C26494" Action="Warning" />
  </Rules>
</RuleSet>

Ruleset-Schema

Das folgende Regelsatzschema beschreibt das XML-Schema einer Regelsatzdatei. Das Regelsatzschema wird gespeichert in %VSINSTALLDIR%\Team Tools\Static Analysis Tools\Schemas\RuleSet.xsd. Sie können es verwenden, um Ihre eigenen Regelets programmgesteuert zu erstellen oder zu überprüfen, ob Ihre benutzerdefinierten Regelsätze dem richtigen Format entsprechen. Weitere Informationen finden Sie unter How to: Create an XML document based on an XSD schema.

<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:annotation>
    <xs:documentation xml:lang="en">
            Visual Studio Code Analysis Rule Set Schema Definition Language.
            Copyright (c) Microsoft Corporation. All rights reserved.
        </xs:documentation>
  </xs:annotation>

  <!-- Every time this file changes, be sure to change the Validate method for the corresponding object in the code -->

  <xs:element name="RuleSet" type="TRuleSet">
  </xs:element>

  <xs:complexType name="TLocalization">
    <xs:all>
      <xs:element name="Name" type="TName" minOccurs="0" maxOccurs="1" />
      <xs:element name="Description" type="TDescription" minOccurs="0" maxOccurs="1" />
    </xs:all>
    <xs:attribute name="ResourceAssembly" type="TNonEmptyString" use="required" />
    <xs:attribute name="ResourceBaseName" type="TNonEmptyString" use="required" />
  </xs:complexType>

  <xs:complexType name="TRuleHintPaths">
    <xs:sequence>
      <xs:element name="Path" type="TNonEmptyString" minOccurs="0" maxOccurs="unbounded" />
    </xs:sequence>
  </xs:complexType>
  
  <xs:complexType name="TName">
    <xs:attribute name="Resource" type="TNonEmptyString" use="required" />
  </xs:complexType>

  <xs:complexType name="TDescription">
    <xs:attribute name="Resource" type="TNonEmptyString" use="required" />
  </xs:complexType>

  <xs:complexType name="TInclude">
    <xs:attribute name="Path" type="TNonEmptyString" use="required" />
    <xs:attribute name="Action" type="TIncludeAction" use="required" />
  </xs:complexType>

  <xs:complexType name="TIncludeAll">
    <xs:attribute name="Action" type="TIncludeAllAction" use="required" />
  </xs:complexType>

  <xs:complexType name="TRule">
    <xs:attribute name="Id" type="TNonEmptyString" use="required" />
    <xs:attribute name="Action" type="TRuleAction" use="required" />
  </xs:complexType>

  <xs:complexType name="TRules">
    <xs:sequence>
      <xs:element name="Rule" type="TRule" minOccurs="0" maxOccurs="unbounded" />
    </xs:sequence>
    <xs:attribute name="AnalyzerId" type="TNonEmptyString" use="required" />
    <xs:attribute name="RuleNamespace" type="TNonEmptyString" use="required" />
  </xs:complexType>

  <xs:complexType name="TRuleSet">
    <xs:sequence minOccurs="0" maxOccurs="1">
      <xs:element name="Localization" type="TLocalization" minOccurs="0" maxOccurs="1" />
      <xs:element name="RuleHintPaths" type="TRuleHintPaths" minOccurs="0" maxOccurs="1" />
      <xs:element name="IncludeAll" type="TIncludeAll" minOccurs="0" maxOccurs="1" />
      <xs:choice minOccurs="0" maxOccurs="unbounded">
        <xs:element name="Include" type="TInclude" minOccurs="0" maxOccurs="unbounded" />
        <xs:element name="Rules" type="TRules" minOccurs="0" maxOccurs="unbounded">
          <xs:unique name="UniqueRuleName">
            <xs:selector xpath="Rule" />
            <xs:field xpath="@Id" />
          </xs:unique>
        </xs:element>
      </xs:choice>
    </xs:sequence>
    <xs:attribute name="Name" type="TNonEmptyString" use="required" />
    <xs:attribute name="Description" type="xs:string" use="optional" />
    <xs:attribute name="ToolsVersion" type="TNonEmptyString" use="required" />
  </xs:complexType>

  <xs:simpleType name="TRuleAction">
    <xs:restriction base="xs:string">
      <xs:enumeration value="Error"/>
      <xs:enumeration value="Warning"/>
      <xs:enumeration value="Info"/>
      <xs:enumeration value="Hidden"/>
      <xs:enumeration value="None"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="TIncludeAction">
    <xs:restriction base="xs:string">
      <xs:enumeration value="Error"/>
      <xs:enumeration value="Warning"/>
      <xs:enumeration value="Info"/>
      <xs:enumeration value="Hidden"/>
      <xs:enumeration value="None"/>
      <xs:enumeration value="Default"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="TIncludeAllAction">
    <xs:restriction base="xs:string">
      <xs:enumeration value="Error"/>
      <xs:enumeration value="Warning"/>
      <xs:enumeration value="Info"/>
      <xs:enumeration value="Hidden"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="TNonEmptyString">
    <xs:restriction base="xs:string">
      <xs:minLength value="1" />
    </xs:restriction>
  </xs:simpleType>
  
</xs:schema>

Schemaelementdetails:

Schema-Element	Beschreibung
TLocalization	Lokalisierungsinformationen einschließlich Name der Regelsatzdatei, Beschreibung der Regelsatzdatei, Name der Ressourcenassembly, die die lokalisierte Ressource enthält, und Basisname der lokalisierten Ressource
TRuleHintPaths	Dateipfade, die als Hinweise zum Suchen nach Regelsatzdateien verwendet werden
TName	Name der aktuellen Regelsatzdatei
TDescription	Beschreibung der aktuellen Regelsatzdatei
TInclude	Pfad zu einem enthaltenen Regelsatz mit Regelaktion
TIncludeAll	Regelaktion für alle Regeln
TRule	Regel-ID mit Regelaktion
TRules	Auflistung einer oder mehrerer Regeln
TRuleSet	Ruleset-Dateiformat, bestehend aus Lokalisierungsinformationen, Regelhinweispfaden, enthalten alle Informationen, Informationen, Regelinformationen, Name, Beschreibung und Tools Versionsinformationen
TRuleAction	Aufzählung, die eine Regelaktion beschreibt, z. B. ein Fehler, eine Warnung, Informationen, ausgeblendet oder keine
TIncludeAction	Aufzählung, die eine Regelaktion beschreibt, z. B. ein Fehler, eine Warnung, Informationen, ausgeblendet, keine oder Standard
TIncludeAllAction	Aufzählung, die eine Regelaktion beschreibt, z. B. ein Fehler, eine Warnung, Informationen oder ausgeblendete

Ein Beispiel für ein Regelet finden Sie unter "So erstellen Sie einen Regelsatz in einem Text-Editor oder eines der in %VSINSTALLDIR%\Team Tools\Static Analysis Tools\Rule Sets.