De C++ Core Guidelines-controles gebruiken

De C++ Kernrichtlijnen zijn een draagbare set richtlijnen, regels en aanbevolen procedures voor coderen in C++ die zijn gemaakt door C++-experts en -ontwerpers. Visual Studio ondersteunt momenteel een subset van deze regels als onderdeel van de Microsoft C++ Code Analysis-hulpprogramma's. De belangrijkste richtlijncontroles worden standaard geïnstalleerd in Visual Studio 2017 en Visual Studio 2019. Ze zijn beschikbaar als een NuGet-pakket voor Visual Studio 2015.

Het C++-kernrichtlijnenproject

De C++ Core Guidelines, gemaakt door Bjarne Stroustrup en anderen, zijn een handleiding voor het veilig en effectief gebruiken van moderne C++. De richtlijnen benadrukken statische typeveiligheid en resourceveiligheid. Ze identificeren manieren om de meest foutgevoelige delen van de taal te elimineren of te minimaliseren. Ze stellen ook voor hoe u uw code eenvoudiger, betrouwbaarder en betere prestaties kunt bieden. Deze richtlijnen worden onderhouden door de Standard C++ Foundation. Zie de documentatie, C++ Core Guidelines en open de C++ Core Guidelines-documentatieprojectbestanden op GitHub voor meer informatie.

De C++ Core Check-richtlijnen inschakelen in codeanalyse

Een subset van C++ Core Check-regels is opgenomen in de door Microsoft systeemeigen aanbevolen regelset. Dit is de regelset die standaard wordt uitgevoerd wanneer Microsoft-codeanalyse is ingeschakeld.

Codeanalyse inschakelen voor uw project

1. Open het dialoogvenster Eigenschappenpagina's voor uw project.

2. Selecteer de eigenschappenpagina Configuratie-eigenschappen>Codeanalyse.

3. Stel de eigenschappen Codeanalyse inschakelen voor Bouwen en Microsoft Code-analyse inschakelen .

U kunt er ook voor kiezen om alle ondersteunde C++ Core Check-regels uit te voeren of uw eigen subset te selecteren die u wilt uitvoeren:

Om meer kerncontroleregels in te schakelen

1. Open het dialoogvenster Eigenschappenpagina's voor uw project.

2. Selecteer de Configuratie-eigenschappen>Code-analyse>Microsoft pagina.

3. Open de vervolgkeuzelijst Actieve regels en selecteer Meerdere regelsets kiezen.

4. Kies in het dialoogvenster Regelsets toevoegen of verwijderen welke regelsets u wilt opnemen.

Voorbeelden

Hier volgt een voorbeeld van enkele problemen die de C++ Core Check-regels kunnen vinden:

// 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", justification : "This attribute suppresses Bounds rules #1")]]
    {
        int* q = p + 1;    // warning C26481 (suppressed)
        p = q++;           // warning C26481 (suppressed)
    }

    return 0;
}

In dit voorbeeld ziet u enkele van de waarschuwingen die door de C++ Kerncontroleregels kunnen worden gevonden:

• C26494 is regeltype.5: initialiseer altijd een object.

• C26485 is regelgrens.3: Geen matrix-naar-aanwijzer-verval.

• C26481 is regel Bounds.1: gebruik geen pointer-aritmetiek. Gebruik in plaats daarvan span.

Installeer en schakel de regelsets voor C++ Core Check-codeanalyse in en compileer deze code. Codeanalyse voert de eerste twee waarschuwingen uit en onderdrukt de derde. Hier volgt de build-uitvoer van de voorbeeldcode 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 ==========

De C++-kernrichtlijnen zijn er om u te helpen betere en veiligere code te schrijven. Mogelijk vindt u echter een exemplaar waarop een regel of profiel niet moet worden toegepast. Het is eenvoudig om deze rechtstreeks in de code te onderdrukken. U kunt het [[gsl::suppress]] kenmerk gebruiken om ervoor te zorgen dat C++ Core Check geen schending van een regel in het volgende codeblok detecteert of rapporteert. U kunt afzonderlijke uitspraken markeren om specifieke regels te onderdrukken. U kunt zelfs het volledige profiel voor grenzen onderdrukken door te schrijven [[gsl::suppress("bounds")]] zonder een specifiek regelnummer op te vragen.

Ondersteunde regelsets

Naarmate er nieuwe regels worden toegevoegd aan de C++-kernrichtlijnencontrole, kan het aantal waarschuwingen dat voor bestaande code wordt geproduceerd, toenemen. U kunt vooraf gedefinieerde regelsets gebruiken om te filteren op welke soorten regels u wilt inschakelen. U vindt naslagartikelen voor de meeste regels in Visual Studio C++ Core Check Reference.

• Rekenkundige regels: regels voor het detecteren van rekenkundige overloop, ondertekende, niet-ondertekende bewerkingen en bitbewerkingen. ^15.6

• Regels voor grenzen: Handhaaf het Bounds-profiel van de C++-kernrichtlijnen. ^15.3

• Klasseregels: Enkele regels die gericht zijn op het juiste gebruik van speciale lidfuncties en virtuele specificaties. Ze zijn een subset van de controles die worden aanbevolen voor klassen en klassenhiërarchieën. ^15,5

• Gelijktijdigheidsregels: Een enkele regel die ongeldige bewakingsobjectdeclaraties detecteert. Zie de richtlijnen met betrekking tot gelijktijdigheid voor meer informatie. ^15,5

• Const-regels: const-gerelateerde controles afdwingen uit de C++-basisrichtlijnen. ^15.3

• Declaratieregels: Een aantal regels uit de interfacesrichtlijnen die zich richten op de manier waarop globale variabelen worden gedeclareerd. ^15,5

• Enum-regels: Deze regels dwingen enumgerelateerde controles af uit de C++-kernrichtlijnen. ^16.3

• Experimentele regels Dit zijn experimentele C++-kerncontroleregels die nuttig zijn, maar niet gereed zijn voor dagelijks gebruik. Probeer ze uit en geef feedback. ^16.0

• Functieregels: twee controles die helpen bij de acceptatie van de noexcept aanduiding. Ze maken deel uit van de richtlijnen voor duidelijk functieontwerp en -implementatie. ^15,5

• GSL-regels: Met deze regels worden controles afgedwongen die betrekking hebben op de richtlijnenondersteuningsbibliotheek voor richtlijnen van C++ uit de basisrichtlijnen voor C++. ^15.7

• Levensduurregels: met deze regels wordt het levensduurprofiel van de C++-kernrichtlijnen afgedwongen. ^15.7

• Regels voor de aanwijzer voor eigenaar: controle van resourcebeheer afdwingen die betrekking hebben op eigenaar<T> uit de C++-basisrichtlijnen.^15.3

• Regels voor onbewerkte aanwijzers: Afdwingen van resourcebeheercontroles voor onbewerkte aanwijzers volgens de C++-basisrichtlijnen. 15.3

• Regels voor gedeelde aanwijzer: het maakt deel uit van het afdwingen van richtlijnen voor resourcebeheer . ^15.5 Er zijn enkele regels toegevoegd die specifiek zijn voor hoe gedeelde aanwijzers worden doorgegeven aan functies of lokaal worden gebruikt.

• STL-regels: met deze regels worden controles afgedwongen die betrekking hebben op de C++ Standard Library (STL) uit de C++-basisrichtlijnen. ^15.7

• Stijlregels: Een eenvoudige maar belangrijke controle, waarmee het gebruik van goto wordt verboden. ^15.5 Het is de eerste stap om uw coderingsstijl en het gebruik van expressies en instructies in C++te verbeteren.

• Typeregels: dwing het typeprofiel van de C++-kernrichtlijnen af. ^15.3

• Unieke aanwijzerregels: controle van resourcebeheer afdwingen die betrekking hebben op typen met unieke pointer-semantiek uit de C++-kernrichtlijnen. ^15.3

• C++ Kerncontroleregels: deze regelset bevat alle momenteel geïmplementeerde controles uit de C++-basisrichtlijnen, met uitzondering van de experimentele regels.

^15.3 Deze regels verschenen eerst in Visual Studio 2017 versie 15.3
^15.5 Deze regels verschenen eerst in Visual Studio 2017 versie 15.5
^15.6 Deze regels verschenen eerst in Visual Studio 2017 versie 15.6
^15.7 Deze regels verschenen eerst in Visual Studio 2017 versie 15.7
^16.0 Deze regels verschenen eerst in Visual Studio 2019 versie 16.0
^16.3 Deze regels verschenen eerst in Visual Studio 2019 versie 16.3

U kunt ervoor kiezen om waarschuwingen te beperken tot slechts één of een paar van de groepen. De systeemeigen minimum- en systeemeigen aanbevolen regelsets omvatten C++ Core Check-regels en andere PREfast-controles.

Als u de beschikbare regelsets wilt zien, opent u het dialoogvenster Projecteigenschappen . Selecteer in het dialoogvenster Eigenschappenpagina's de Configuratie-eigenschappen>Code-analyse>Microsoft eigenschappagina. Open vervolgens de vervolgkeuzelijst van Actieve regels om de beschikbare regels weer te geven. Als u een aangepaste combinatie van regelsets wilt maken, selecteert u Meerdere regelsets kiezen. Het dialoogvenster Regelsets toevoegen of verwijderen bevat de regels waaruit u kunt kiezen. Zie Regelsets gebruiken om de C++-regels op te geven die moeten worden uitgevoerd voor meer informatie over het gebruik van regelsets in Visual Studio.

Macro's

De C++ Core Guidelines Checker wordt geleverd met een header-bestand, waarmee macro's worden gedefinieerd die het gemakkelijker maken om volledige categorieën waarschuwingen in code te onderdrukken:

ALL_CPPCORECHECK_WARNINGS
CPPCORECHECK_TYPE_WARNINGS
CPPCORECHECK_RAW_POINTER_WARNINGS
CPPCORECHECK_CONST_WARNINGS
CPPCORECHECK_OWNER_POINTER_WARNINGS
CPPCORECHECK_UNIQUE_POINTER_WARNINGS
CPPCORECHECK_BOUNDS_WARNINGS

Deze macro's komen overeen met de regelsets en worden uitgebreid naar een door spaties gescheiden lijst met waarschuwingsnummers. Met behulp van de juiste pragma-constructies kunt u de effectieve set regels configureren die interessant zijn voor een project of een sectie met code. In het volgende voorbeeld waarschuwt codeanalyse alleen voor ontbrekende constante modifiers:

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

Kenmerken

De Microsoft C++-compiler biedt beperkte ondersteuning voor het [[gsl::suppress]] kenmerk. Het kan worden gebruikt om waarschuwingen voor uitdrukkingen en blokverklaringen in functies te onderdrukken.

// 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;
}

Analyse onderdrukken met opdrachtregelopties

In plaats van #pragmas kunt u opdrachtregelopties op de eigenschappenpagina van het bestand gebruiken om waarschuwingen voor een project of één bestand te onderdrukken. Als u bijvoorbeeld de waarschuwing C26400 voor een bestand wilt uitschakelen:

1. Klik met de rechtermuisknop op het bestand in Solution Explorer en kies Eigenschappen.

2. Selecteer in het dialoogvenster Eigenschappenpagina's de eigenschappenpagina Configuratie-eigenschappen>C/C++>Opdrachtregel.

3. Voeg in het invoervak Aanvullende opties toe /wd26400.

U kunt de opdrachtregeloptie gebruiken om alle codeanalyses voor een bestand tijdelijk uit te schakelen door op te /analyze-geven. U ziet de waarschuwing D9025, waarmee '/analyze' wordt overschreven met '/analyze-', die u eraan herinnert om later codeanalyse opnieuw in te schakelen.

C++ Core Guidelines Checker inschakelen voor specifieke projectbestanden

Soms is het handig om gerichte codeanalyse uit te voeren en nog steeds de Visual Studio IDE te gebruiken. Probeer het volgende voorbeeldscenario voor grote projecten. Het kan buildtijd besparen en het gemakkelijker maken om resultaten te filteren:

1. Stel in de opdrachtshell de esp.extension omgevingsvariabele in.

2. Als u deze variabele wilt overnemen, opent u Visual Studio vanuit de opdrachtshell.

3. Laad uw project en open de eigenschappen.

4. Schakel codeanalyse in, kies de juiste regelsets, maar schakel geen codeanalyse-extensies in.

5. Ga naar het bestand dat u wilt analyseren met C++ Core Guidelines Checker en open de eigenschappen.

6. Kies Configuratie-eigenschappen>C/C++>Opdrachtregel>aanvullende opties en voeg toe /analyze:plugin EspXEngine.dll

7. Schakel het gebruik van vooraf gecompileerde headers uit (Configuratie-eigenschappen>C/C++>Vooraf gecompileerde headers). Dit is nodig omdat de uitbreidingsengine mogelijk probeert de interne informatie van de vooraf gecompileerde header (PCH) te lezen. Als de PCH is gecompileerd met standaardprojectopties, is deze niet compatibel.

8. Bouw het project opnieuw. De algemene PREFast-controles moeten worden uitgevoerd op alle bestanden. Omdat C++ Core Guidelines Checker niet standaard is ingeschakeld, mag deze alleen worden uitgevoerd op het bestand dat is geconfigureerd voor gebruik.

C++ Core Guidelines Checker buiten Visual Studio gebruiken

U kunt de C++ Core Guidelines-controles in geautomatiseerde builds gebruiken.

MSBuild

De systeemeigen code-analysecontrole (PREfast) is geïntegreerd in de MSBuild-omgeving via aangepaste targetbestanden. U kunt projecteigenschappen gebruiken om dit in te schakelen en de C++ Core Guidelines Checker (die is gebaseerd op PREfast) toevoegen:

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

Zorg ervoor dat u deze eigenschappen toevoegt voordat u het Microsoft.Cpp.targets bestand importeert. U kunt specifieke regelsets kiezen of een aangepaste regelset maken. Of gebruik de standaardregelset die andere PREfast-controles bevat.

U kunt de C++ Core Checker alleen uitvoeren op opgegeven bestanden. Gebruik dezelfde methode als eerder beschreven, maar gebruik MSBuild-bestanden. De omgevingsvariabelen kunnen worden ingesteld met behulp van het BuildMacro item:

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

Als u het projectbestand niet wilt wijzigen, kunt u eigenschappen doorgeven op de opdrachtregel:

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

Niet-MSBuild-projecten

Als u een buildsysteem gebruikt dat niet afhankelijk is van MSBuild, kunt u de controle nog steeds uitvoeren. Als u deze wilt gebruiken, moet u vertrouwd raken met enkele interne functies van de configuratie van de codeanalyse-engine. We garanderen geen ondersteuning voor deze interne functies in toekomstige versies van Visual Studio.

Codeanalyse vereist enkele omgevingsvariabelen en opdrachtregelopties voor compileren. U wordt aanbevolen de Native Tools Command Prompt-omgeving te gebruiken, zodat u niet hoeft te zoeken naar specifieke paden voor de compiler en includemappen, enzovoort.

• omgevingsvariabelen

  • set esp.extensions=cppcorecheck.dll Hiermee wordt aan de engine aangegeven dat de C++ Core Guidelines-module moet worden geladen.
  • Sinds Visual Studio 2019 raden we het niet langer aan om de esp.annotationbuildlevel omgevingsvariabele in te stellen, omdat dit fout-positieven kan opleveren. Als u onverwachte resultaten ziet, verwijdert u deze variabele uit uw omgeving.
  • set caexcludepath=%include% Wij raden u ten zeerste aan om waarschuwingen die betrekking hebben op standaardheaders uit te schakelen. U kunt hier meer paden toevoegen, bijvoorbeeld het pad naar de algemene headers in uw project.

• Opdrachtregelopties

  • /analyze Hiermee kunt u codeanalyse inschakelen (overweeg ook het gebruik /analyze:only en /analyze:quiet).
  • /analyze:plugin EspXEngine.dll Met deze optie wordt de engine Codeanalyse-extensies in PREfast geladen. Deze engine laadt op zijn beurt de C++ Core Guidelines Checker.

De ondersteuningsbibliotheek voor richtlijnen gebruiken

De richtlijnondersteuningsbibliotheek (GSL) is ontworpen om u te helpen de kernrichtlijnen te volgen. De GSL bevat definities waarmee u foutgevoelige constructies kunt vervangen door veiligere alternatieven. U kunt bijvoorbeeld een T*, length paar parameters vervangen door het span<T> type. Het GSL-project is beschikbaar op GitHub op https://github.com/Microsoft/GSL. De bibliotheek is opensource, zodat u de bronnen kunt bekijken, opmerkingen kunt maken of kunt bijdragen. U kunt ook vcpkg package manager gebruiken om de bibliotheek lokaal te downloaden en te installeren.

Zie ook

• Visual Studio C++ Core Check naslagreferentie