Verwenden der Überprüfungen für C++ Core Guidelines

Die C++-Kernrichtlinien sind eine tragbare Reihe von Richtlinien, Regeln und bewährten Methoden zum Codieren in C++, die von C++-Experten und -Designern erstellt wurden. Visual Studio unterstützt derzeit eine Teilmenge dieser Regeln als Teil der Codeanalysetools für C++. Die Kernrichtlinienprüfer werden standardmäßig in Visual Studio 2017 und Visual Studio 2019 installiert. Sie sind als NuGet-Paket für Visual Studio 2015 verfügbar.

Das C++-Kernrichtlinienprojekt

Die von Bjarne Stroustrup und anderen erstellten C++-Kernrichtlinien sind ein Leitfaden zur sicheren und effektiven Verwendung moderner C++-Richtlinien. Die Richtlinien betonen die Sicherheit statischer Typen und die Ressourcensicherheit. Sie identifizieren Möglichkeiten, die am häufigsten fehleranfälligen Teile der Sprache zu beseitigen oder zu minimieren. Sie schlagen auch vor, wie Sie Ihren Code einfacher, zuverlässiger machen und eine bessere Leistung erzielen können. Diese Richtlinien werden von der Standard C++-Foundation Standard beibehalten. Weitere Informationen finden Sie in der Dokumentation, in den C++-Kernrichtlinien, und greifen Sie auf die C++ Core Guidelines-Dokumentations-Projektdateien auf GitHub zu.

Aktivieren der C++-Kernüberprüfungsrichtlinien in der Codeanalyse

Eine Teilmenge der C++-Kernüberprüfungsregeln ist im Microsoft Native Recommended-Regelsatz enthalten. Es handelt sich um das Regelet, das standardmäßig ausgeführt wird, wenn die Microsoft-Codeanalyse aktiviert ist.

So aktivieren Sie die Codeanalyse für Ihr Projekt:

1. Öffnen Sie das Dialogfeld "Eigenschaftenseiten " für Ihr Projekt.

2. Wählen Sie die Codeanalyse-Eigenschaftenseite der Konfigurationseigenschaften>aus.

3. Legen Sie die Eigenschaften "Codeanalyse aktivieren" für "Build " und "Microsoft Code Analysis " fest.

Sie können auch alle unterstützten C++-Kernüberprüfungsregeln ausführen oder ihre eigene Teilmenge zum Ausführen auswählen:

So aktivieren Sie weitere Kernüberprüfungsregeln

1. Öffnen Sie das Dialogfeld "Eigenschaftenseiten " für Ihr Projekt.

2. Wählen Sie die Microsoft-Eigenschaftenseite für die Codeanalyse> der Konfigurationseigenschaften>aus.

3. Öffnen Sie die Dropdownliste "Aktive Regeln", und wählen Sie "Mehrere Regelsätze auswählen" aus.

4. Wählen Sie im Dialogfeld "Regelsätze hinzufügen oder entfernen" aus, welche Regelsätze sie einbeziehen möchten.

Beispiele

Nachfolgend finden Sie ein Beispiel für einige der Probleme, die die C++-Kernüberprüfungsregeln finden können:

// CoreCheckExample.cpp
// Add CppCoreCheck package and enable code analysis in build for warnings.

int main()
{
    int arr[10];           // warning C26494
    int* p = arr;          // warning C26485

    [[gsl::suppress(bounds.1)]] // This attribute suppresses Bounds rule #1
    {
        int* q = p + 1;    // warning C26481 (suppressed)
        p = q++;           // warning C26481 (suppressed)
    }

    return 0;
}

In diesem Beispiel werden einige der Warnungen veranschaulicht, die von den C++-Kernüberprüfungsregeln gefunden werden können:

• C26494 ist Regeltyp.5: Initialisieren Sie immer ein Objekt.

• C26485 ist regelgebunden.3: Kein Array-zu-Zeiger-Verfall.

• C26481 ist "Rule Bounds.1": Verwenden Sie keine Zeigerarithmetik. Verwenden Sie stattdessen span.

Installieren und aktivieren Sie die C++ Core Check-Codeanalyseregeln, und kompilieren Sie dann diesen Code. Die Codeanalyse gibt die ersten beiden Warnungen aus und unterdrückt den dritten. Hier sehen Sie die Buildausgabe aus dem Beispielcode in Visual Studio 2015:

1>------ Build started: Project: CoreCheckExample, Configuration: Debug Win32 ------
1>  CoreCheckExample.cpp
1>  CoreCheckExample.vcxproj -> C:\Users\username\documents\visual studio 2015\Projects\CoreCheckExample\Debug\CoreCheckExample.exe
1>  CoreCheckExample.vcxproj -> C:\Users\username\documents\visual studio 2015\Projects\CoreCheckExample\Debug\CoreCheckExample.pdb (Full PDB)
c:\users\username\documents\visual studio 2015\projects\corecheckexample\corecheckexample\corecheckexample.cpp(6): warning C26494: Variable 'arr' is uninitialized. Always initialize an object. (type.5: http://go.microsoft.com/fwlink/p/?LinkID=620421)
c:\users\username\documents\visual studio 2015\projects\corecheckexample\corecheckexample\corecheckexample.cpp(7): warning C26485: Expression 'arr': No array to pointer decay. (bounds.3: http://go.microsoft.com/fwlink/p/?LinkID=620415)
========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

Die C++-Kernrichtlinien sind vorhanden, um Ihnen dabei zu helfen, besseren und sichereren Code zu schreiben. Möglicherweise finden Sie jedoch eine Instanz, in der eine Regel oder ein Profil nicht angewendet werden sollte. Es ist einfach, sie direkt im Code zu unterdrücken. Sie können das [[gsl::suppress]] Attribut verwenden, um die C++-Kernüberprüfung daran zu hindern, verletzungen einer Regel im folgenden Codeblock zu erkennen und zu melden. Sie können einzelne Anweisungen markieren, um bestimmte Regeln zu unterdrücken. Sie können sogar das gesamte Begrenzungsprofil unterdrücken, indem Sie schreiben [[gsl::suppress(bounds)]] , ohne eine bestimmte Regelnummer einzugeben.

Unterstützte Regelsätze

Da der C++ Core Guidelines Checker neue Regeln hinzugefügt werden, kann die Anzahl der Warnungen, die für bereits vorhandenen Code erstellt werden, erhöht werden. Sie können vordefinierte Regelsätze verwenden, um zu filtern, welche Arten von Regeln aktiviert werden sollen. Referenzartikel für die meisten Regeln finden Sie unter Visual Studio C++ Core Check Reference.

• Arithmetische Regeln: Regeln zum Erkennen von arithmetischen Überlaufvorgängen, signierten nicht signierten Vorgängen und Bitmanipulation.^15.6

• Bounds Rules: Erzwingen des Begrenzungsprofils der C++-Kernrichtlinien.^15.3

• Klassenregeln: Einige Regeln, die sich auf die ordnungsgemäße Verwendung spezieller Memberfunktionen und virtueller Spezifikationen konzentrieren. Sie sind eine Teilmenge der Prüfungen, die für Klassen und Klassenhierarchien empfohlen werden.^15.5

• Parallelitätsregeln: Eine einzelne Regel, die ungültige Guard-Objektdeklarationen abfangen. Weitere Informationen finden Sie in den Richtlinien zur Parallelität.^15.5

• Const Rules: Erzwingen sie konstbezogene Prüfungen aus den C++-Kernrichtlinien.^15.3

• Deklarationsregeln: Einige Regeln aus den Schnittstellenrichtlinien , die sich darauf konzentrieren, wie globale Variablen deklariert werden.^15.5

• Enumerationsregeln: Diese Regeln erzwingen enumerationsbezogene Prüfungen aus den C++-Kernrichtlinien.^16.3

• Experimentelle Regeln Diese sind experimentelle C++-Core Check-Regeln , die nützlich, aber nicht für den täglichen Gebrauch geeignet sind. Probieren Sie sie aus, und geben Sie Feedback.^16.0

• Funktionsregeln: Zwei Überprüfungen, die bei der Einführung des noexcept Bezeichners helfen. Sie sind Teil der Richtlinien für klares Funktionsdesign und -implementierung.^15.5

• GSL-Regeln: Diese Regeln erzwingen Prüfungen im Zusammenhang mit der Richtlinienunterstützungsbibliothek aus den C++-Kernrichtlinien.^15.7

• Lebensdauerregeln: Diese Regeln erzwingen das Lebensdauerprofil der C++-Kernrichtlinien.^15.7

• Regeln für Besitzerzeiger: Erzwingen von Ressourcenverwaltungsprüfungen im Zusammenhang mit Besitzer<T> aus den C++-Kernrichtlinien.^15.3

• Regeln für unformatierte Zeiger: Erzwingen von Ressourcenverwaltungsprüfungen im Zusammenhang mit unformatierten Zeigern aus den C++-Kernrichtlinien.^15.3

• Regeln für gemeinsame Zeiger: Es ist Teil der Erzwingung von Ressourcenverwaltungsrichtlinien .^15.5 Wir haben einige Regeln hinzugefügt, die spezifisch dafür sind, wie freigegebene Zeiger in Funktionen übergeben oder lokal verwendet werden.

• STL-Regeln: Diese Regeln erzwingen Prüfungen im Zusammenhang mit der C++-Standardbibliothek (STL) aus den C++-Kernrichtlinien.^15.7

• Stilregeln: Eine einfache, aber wichtige Prüfung, die die Verwendung von Goto verbietet.^15.5 Es ist der erste Schritt, um Ihren Codierungsstil und die Verwendung von Ausdrücken und Anweisungen in C++ zu verbessern.

• Typregeln: Erzwingen sie das Typprofil der C++-Kernrichtlinien.^15.3

• Eindeutige Zeigerregeln: Erzwingen von Ressourcenverwaltungsprüfungen im Zusammenhang mit Typen mit eindeutiger Zeigersemantik aus den C++-Kernrichtlinien.^15.3

• C++ Core Check Rules: Dieser Regelsatz enthält alle derzeit implementierten Prüfungen aus den C++-Kernrichtlinien, mit Ausnahme der experimentellen Regeln.

^15.3 Diese Regeln wurden zuerst in Visual Studio 2017, Version 15.3, angezeigt.
^15.5 Diese Regeln wurden zuerst in Visual Studio 2017, Version 15.5, angezeigt.
^15.6 Diese Regeln wurden zuerst in Visual Studio 2017, Version 15.6, angezeigt.
^15.7 Diese Regeln wurden zuerst in Visual Studio 2017, Version 15.7, angezeigt.
^16.0 Diese Regeln wurden zuerst in Visual Studio 2019, Version 16.0, angezeigt.
^16.3 Diese Regeln wurden zuerst in Visual Studio 2019, Version 16.3, angezeigt.

Sie können festlegen, dass Warnungen nur auf eine oder einige der Gruppen beschränkt werden sollen. Die Regelsätze "Native Minimum " und "Native Recommended " umfassen C++-Kernüberprüfungsregeln und andere PREfast-Prüfungen.

Öffnen Sie das Dialogfeld "Projekteigenschaften ", um die verfügbaren Regelsätze anzuzeigen. Wählen Sie im Dialogfeld Eigenschaftenseiten die Microsoft-Eigenschaftenanalyseseite> für Konfigurationseigenschaften>aus. Öffnen Sie dann das Dropdown im Kombinationsfeld "Aktive Regeln ", um die verfügbaren Regelsätze anzuzeigen. Um eine benutzerdefinierte Kombination von Regelsätzen zu erstellen, wählen Sie "Mehrere Regelsätze auswählen" aus. Im Dialogfeld "Regelsätze hinzufügen oder entfernen" werden die Regeln aufgelistet, aus der Sie auswählen können. Weitere Informationen zur Verwendung von Regelsätzen in Visual Studio finden Sie unter Verwenden von Regelsätzen zum Angeben der auszuführenden C++-Regeln.

Makros

Die C++ Core Guidelines Checker enthält eine Headerdatei, die Makros definiert, die es einfacher machen, ganze Kategorien von Warnungen im Code zu unterdrücken:

ALL_CPPCORECHECK_WARNINGS
CPPCORECHECK_TYPE_WARNINGS
CPPCORECHECK_RAW_POINTER_WARNINGS
CPPCORECHECK_CONST_WARNINGS
CPPCORECHECK_OWNER_POINTER_WARNINGS
CPPCORECHECK_UNIQUE_POINTER_WARNINGS
CPPCORECHECK_BOUNDS_WARNINGS

Diese Makros entsprechen den Regelsätzen und erweitern sie in eine durch Leerzeichen getrennte Liste von Warnnummern. Mithilfe der entsprechenden Pragma-Konstrukte können Sie den effektiven Satz von Regeln konfigurieren, die für ein Projekt oder einen Codeabschnitt interessant sind. Im folgenden Beispiel warnt die Codeanalyse nur bei fehlenden Konstantenmodifizierern:

#include <CppCoreCheck\Warnings.h>
#pragma warning(disable: ALL_CPPCORECHECK_WARNINGS)
#pragma warning(default: CPPCORECHECK_CONST_WARNINGS)

Attribute

Der Microsoft C++-Compiler unterstützt das [[gsl::suppress]] Attribut nur eingeschränkt. Sie kann verwendet werden, um Warnungen bei Ausdrücken und Blockanweisungen innerhalb von Funktionen zu unterdrücken.

// Suppress only warnings from the 'r.11' rule in expression.
[[gsl::suppress(r.11)]] new int;

// Suppress all warnings from the 'r' rule group (resource management) in block.
[[gsl::suppress(r)]]
{
    new int;
}

// Suppress only one specific warning number.
// For declarations, you might need to use the surrounding block.
// Macros are not expanded inside of attributes.
// Use plain numbers instead of macros from the warnings.h.
[[gsl::suppress(26400)]]
{
    int *p = new int;
}

Unterdrücken der Analyse mithilfe von Befehlszeilenoptionen

Statt #pragmas können Sie Befehlszeilenoptionen auf der Eigenschaftenseite der Datei verwenden, um Warnungen für ein Projekt oder eine einzelne Datei zu unterdrücken. So deaktivieren Sie beispielsweise die Warnung C26400 für eine Datei:

1. Klicken Sie mit der rechten Maustaste auf die Datei in Projektmappen-Explorer, und wählen Sie "Eigenschaften" aus.

2. Wählen Sie im Dialogfeld Eigenschaftenseiten die Eigenschaftenseite "Konfigurationseigenschaften>C/C++>" aus.

3. Fügen Sie im Bearbeitungsfeld "Zusätzliche Optionen " hinzu /wd26400.

Sie können die Befehlszeilenoption verwenden, um vorübergehend alle Codeanalyse für eine Datei zu deaktivieren, indem Sie angeben /analyze-. Die Warnung D9025 überschreibt "/analyze" mit "/analyze-", die Sie daran erinnert, die Codeanalyse später erneut zu aktivieren.

Aktivieren der C++ Core Guidelines Checker für bestimmte Projektdateien

Manchmal ist es hilfreich, eine fokussierte Codeanalyse durchzuführen und weiterhin die Visual Studio-IDE zu verwenden. Probieren Sie das folgende Beispielszenario für große Projekte aus. Sie kann Die Erstellungszeit sparen und das Filtern von Ergebnissen vereinfachen:

1. Legen Sie in der Befehlsshell die esp.extension Umgebungsvariable fest.

2. Um diese Variable zu erben, öffnen Sie Visual Studio über die Befehlsshell.

3. Laden Sie Ihr Projekt, und öffnen Sie die zugehörigen Eigenschaften.

4. Aktivieren Sie die Codeanalyse, wählen Sie die entsprechenden Regelsätze aus, aktivieren Sie aber keine Codeanalyseerweiterungen.

5. Wechseln Sie zu der Datei, die Sie mit der C++-Kernrichtlinienprüfung analysieren möchten, und öffnen Sie die zugehörigen Eigenschaften.

6. Wählen Sie Konfigurationseigenschaften>C/C++>-Befehlszeilenoptionen> aus, und fügen Sie sie hinzu./analyze:plugin EspXEngine.dll

7. Deaktivieren Sie die Verwendung von vorkompilierten Headern (Konfigurationseigenschaften>C/C++>- vorkompilierte Header). Dies ist erforderlich, da das Erweiterungsmodul möglicherweise versucht, seine internen Informationen aus dem vorkompilierten Header (PCH) zu lesen. Wenn der PCH mit den Standardprojektoptionen kompiliert wurde, ist er nicht kompatibel.

8. Erstellen Sie das Projekt neu. Die allgemeinen PREFast-Prüfungen sollten für alle Dateien ausgeführt werden. Da die C++-Kernrichtlinienprüfung standardmäßig nicht aktiviert ist, sollte sie nur für die Datei ausgeführt werden, die für die Verwendung konfiguriert ist.

So wird's gemacht: Verwenden der C++-Core Guidelines Checker außerhalb von Visual Studio

Sie können die C++-Kernrichtlinien-Prüfungen in automatisierten Builds verwenden.

MSBuild

Die Native Code Analysis Checker (PREfast) ist in DIE MSBuild-Umgebung durch benutzerdefinierte Zieldateien integriert. Sie können Projekteigenschaften verwenden, um sie zu aktivieren, und die C++ Core Guidelines Checker (die auf PREfast basiert) hinzufügen:

  <PropertyGroup>
    <EnableCppCoreCheck>true</EnableCppCoreCheck>
    <CodeAnalysisRuleSet>CppCoreCheckRules.ruleset</CodeAnalysisRuleSet>
    <RunCodeAnalysis>true</RunCodeAnalysis>
  </PropertyGroup>

Stellen Sie sicher, dass Sie diese Eigenschaften vor dem Import der Microsoft.Cpp.targets Datei hinzufügen. Sie können bestimmte Regelsätze auswählen oder einen benutzerdefinierten Regelsatz erstellen. Oder verwenden Sie den Standardregelsatz, der andere PREfast-Prüfungen enthält.

Sie können die C++-Kernprüfung nur für angegebene Dateien ausführen. Verwenden Sie den gleichen Ansatz wie zuvor beschrieben, verwenden Sie jedoch MSBuild-Dateien. Die Umgebungsvariablen können mithilfe des BuildMacro Elements festgelegt werden:

<ItemGroup>
    <BuildMacro Include="Esp_Extensions">
      <EnvironmentVariable>true</EnvironmentVariable>
      <Value>CppCoreCheck.dll</Value>
    </BuildMacro>
</ItemGroup>

Wenn Sie die Projektdatei nicht ändern möchten, können Sie Eigenschaften an die Befehlszeile übergeben:

msbuild /p:EnableCppCoreCheck=true /p:RunCodeAnalysis=true /p:CodeAnalysisRuleSet=CppCoreCheckRules.ruleset ...

Nicht-MSBuild-Projekte

Wenn Sie ein Buildsystem verwenden, das nicht auf MSBuild angewiesen ist, können Sie die Prüfung weiterhin ausführen. Um es zu verwenden, müssen Sie sich mit einigen Internen der Codeanalysemodulkonfiguration vertraut machen. Wir garantieren keine Unterstützung für diese Internen in zukünftigen Versionen von Visual Studio.

Für die Codeanalyse sind einige Umgebungsvariablen und Compiler-Befehlszeilenoptionen erforderlich. Es wird empfohlen, die Eingabeaufforderungsumgebung der nativen Tools zu verwenden, damit Sie nicht nach bestimmten Pfaden für den Compiler suchen müssen, Verzeichnisse usw. enthalten.

• Umgebungsvariablen

  • set esp.extensions=cppcorecheck.dll Dadurch wird das Modul angewiesen, das C++-Kernrichtlinienmodul zu laden.
  • Da Visual Studio 2019 das Festlegen der esp.annotationbuildlevel Umgebungsvariable nicht mehr empfohlen wird, da die Einstellung zu falsch positiven Ergebnissen führen kann. Wenn unerwartete Ergebnisse angezeigt werden, entfernen Sie diese Variable aus Ihrer Umgebung.
  • set caexcludepath=%include% Es wird dringend empfohlen, Warnungen zu deaktivieren, die in Standardheadern ausgelöst werden. Sie können hier weitere Pfade hinzufügen, z. B. den Pfad zu den allgemeinen Headern in Ihrem Projekt.

• Befehlszeilenoptionen

  • /analyze Ermöglicht die Codeanalyse (erwägen Sie auch die Verwendung /analyze:only und /analyze:quiet).
  • /analyze:plugin EspXEngine.dll Mit dieser Option wird das Modul für Codeanalyseerweiterungen in das PREfast geladen. Dieses Modul lädt wiederum die C++ Core Guidelines Checker.

Verwenden der Richtliniensupportbibliothek

Die Richtlinienunterstützungsbibliothek (Guidelines Support Library, GSL) soll Ihnen dabei helfen, die Kernrichtlinien zu befolgen. Die GSL enthält Definitionen, mit denen Sie fehleranfällige Konstrukte durch sicherere Alternativen ersetzen können. Sie können beispielsweise ein T*, length Parameterpaar durch den span<T> Typ ersetzen. Das GSL-Projekt ist auf GitHub unter https://github.com/Microsoft/GSL. Die Bibliothek ist Open Source, sodass Sie die Quellen anzeigen, Kommentare erstellen oder mitwirken können. Sie können auch den vcpkg-Paket-Manager verwenden, um die Bibliothek lokal herunterzuladen und zu installieren.

Siehe auch

• Visual Studio C++ Core Check Reference