Usare i controlli delle Linee guida di base di C++

Le linee guida di base di C++ sono un set portabile di linee guida, regole e procedure consigliate per la codifica in C++ creato da esperti e progettisti C++. Visual Studio supporta attualmente un subset di queste regole come parte degli strumenti di analisi del codice per C++. I controlli delle linee guida di base vengono installati per impostazione predefinita in Visual Studio 2017 e Visual Studio 2019. Sono disponibili come pacchetto NuGet per Visual Studio 2015.

Progetto linee guida di base di C++

Creato da Bjarne Stroustrup e altri, le linee guida di base di C++ sono una guida all'uso sicuro ed efficace di C++. Le linee guida evidenziano la sicurezza dei tipi statici e la sicurezza delle risorse. Identificano i modi per eliminare o ridurre al minimo le parti più soggette a errori del linguaggio. Suggeriscono anche come rendere il codice più semplice, più affidabile e ottenere prestazioni migliori. Queste linee guida vengono gestite da Standard C++ Foundation. Per altre informazioni, vedere la documentazione, linee guida di base di C++ e accedere ai file di progetto di progetto della documentazione delle linee guida di base di C++ in GitHub.

Abilitare le linee guida per il controllo di base di C++ nell'analisi del codice

Un sottoinsieme di regole di controllo di base C++ è incluso nel set di regole Consigliato da Microsoft Native. Si tratta del set di regole eseguito per impostazione predefinita quando l'analisi del codice Microsoft è abilitata.

Per abilitare l'analisi del codice nel progetto:

1. Aprire la finestra di dialogo Pagine delle proprietà per il progetto.

2. Selezionare la pagina delle proprietà Analisi codice proprietà>di configurazione.

3. Impostare le proprietà Abilita analisi codice per la compilazione e Abilita analisi codice Microsoft.

È anche possibile scegliere di eseguire tutte le regole C++ Core Check supportate oppure selezionare il proprio subset da eseguire:

Per abilitare altre regole di controllo di base

1. Aprire la finestra di dialogo Pagine delle proprietà per il progetto.

2. Selezionare la pagina delle proprietà Proprietà>di configurazione Analisi>codice Microsoft.

3. Aprire l'elenco a discesa Regole attive e selezionare Scegli più set di regole.

4. Nella finestra di dialogo Aggiungi o Rimuovi set di regole scegliere i set di regole da includere.

Esempi

Ecco un esempio di alcuni dei problemi che le regole di controllo di base di C++ possono trovare:

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

Questo esempio illustra alcuni avvisi che le regole di controllo di base di C++ possono trovare:

• C26494 è la regola Type.5: inizializzare sempre un oggetto.

• C26485 è la regola Bounds.3: nessun decadimento da matrice a puntatore.

• C26481 è la regola Bounds.1: non usare l'aritmetica del puntatore. Utilizzare invece span.

Installare e abilitare i set di regole di analisi del codice C++ Core Check, quindi compilare questo codice. L'analisi del codice restituisce i primi due avvisi e elimina il terzo. Ecco l'output di compilazione del codice di esempio 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 ==========

Le linee guida di base di C++ consentono di scrivere codice migliore e più sicuro. Tuttavia, è possibile trovare un'istanza in cui non deve essere applicata una regola o un profilo. È facile eliminarlo direttamente nel codice. È possibile usare l'attributo [[gsl::suppress]] per impedire a C++ Core Check di rilevare e segnalare eventuali violazioni di una regola nel blocco di codice seguente. È possibile contrassegnare singole istruzioni per eliminare regole specifiche. È anche possibile eliminare l'intero profilo di limiti scrivendo [[gsl::suppress(bounds)]] senza includere un numero di regola specifico.

Set di regole supportati

Man mano che vengono aggiunte nuove regole al controllo delle linee guida di base di C++, il numero di avvisi generati per il codice preesistente potrebbe aumentare. È possibile usare set di regole predefiniti per filtrare i tipi di regole da abilitare. Sono disponibili articoli di riferimento per la maggior parte delle regole in Visual Studio C++ Core Check Reference (Informazioni di riferimento sul controllo di base di Visual Studio C++).

• Regole aritmetiche: regole per rilevare l'overflow aritmetico, le operazioni senza segno e la manipolazione dei bit.^15.6

• Regole dei limiti: applica il profilo limiti delle linee guida di base di C++.^15.3

• Regole di classe: alcune regole che si concentrano sull'uso appropriato di funzioni membro speciali e specifiche virtuali. Sono un subset dei controlli consigliati per le classi e le gerarchie di classi.^15.5

• Regole di concorrenza: una singola regola, che rileva dichiarazioni di oggetti di protezione non valide. Per altre informazioni, vedere linee guida relative alla concorrenza.^15.5

• Regole const: applicare controlli correlati a const dalle linee guida di base di C++.^15.3

• Regole di dichiarazione: un paio di regole delle linee guida delle interfacce che riguardano la modalità di dichiarazione delle variabili globali.^15.5

• Regole di enumerazione: queste regole applicano controlli correlati all'enumerazione dalle linee guida di base di C++.^16.3

• Regole sperimentali Queste sono regole di controllo di base C++ sperimentali utili ma non pronte per l'uso quotidiano. Provali e fornisci feedback.^16.0

• Regole di funzione: due controlli che consentono l'adozione dell'identificatore noexcept . Fanno parte delle linee guida per la progettazione e l'implementazione chiare delle funzioni.^15.5

• Regole GSL: queste regole applicano i controlli correlati alla libreria di supporto linee guida dalle linee guida di base di C++.^15.7

• Regole di durata: queste regole applicano il profilo di durata delle linee guida di base C++.^15.7

• Regole del puntatore proprietario: applicare i controlli di gestione delle risorse correlati al proprietario<T> dalle linee guida di base di C++.^15.3

• Regole del puntatore non elaborato: applicare i controlli di gestione delle risorse correlati ai puntatori non elaborati dalle linee guida di base di C++.^15.3

• Regole del puntatore condiviso: fa parte delle linee guida per la gestione delle risorse.^15.5 Sono state aggiunte alcune regole specifiche per il modo in cui i puntatori condivisi vengono passati nelle funzioni o usati localmente.

• Regole STL: queste regole applicano i controlli correlati alla libreria standard C++ (STL) dalle linee guida di base di C++.^15.7

• Regole di stile: un controllo semplice ma importante, che vieta l'uso di goto.^15.5 È il primo passaggio per migliorare lo stile di codifica e l'uso di espressioni e istruzioni in C++.

• Regole di tipo: applicare il profilo di tipo delle linee guida di base di C++.^15.3

• Regole del puntatore univoco: applicare i controlli di gestione delle risorse correlati ai tipi con semantica del puntatore univoca dalle linee guida di base di C++.^15.3

• Regole di controllo di base C++: questo set di regole contiene tutti i controlli attualmente implementati dalle linee guida di base C++, ad eccezione delle regole sperimentali.

^15.3 Queste regole sono apparse per la prima volta in Visual Studio 2017 versione 15.3
^15.5 Queste regole sono apparse per la prima volta in Visual Studio 2017 versione 15.5
^15.6 Queste regole sono apparse per la prima volta in Visual Studio 2017 versione 15.6
^15.7 Queste regole sono apparse per la prima volta in Visual Studio 2017 versione 15.7
^16.0 Queste regole sono apparse per la prima volta in Visual Studio 2019 versione 16.0
^16.3 Queste regole sono apparse per la prima volta in Visual Studio 2019 versione 16.3

È possibile scegliere di limitare gli avvisi a uno o a pochi gruppi. I set di regole Native Minimum e Native Recommended includono regole C++ Core Check e altri controlli PREfast.

Per visualizzare i set di regole disponibili, aprire la finestra di dialogo Proprietà progetto. Nella finestra di dialogo Pagine delle proprietà selezionare la pagina delle proprietà Proprietà>di configurazione Analisi>codice Microsoft. Aprire quindi l'elenco a discesa nella casella combinata Regole attive per visualizzare i set di regole disponibili. Per creare una combinazione personalizzata di set di regole, selezionare Scegli più set di regole. Nella finestra di dialogo Aggiungi o Rimuovi set di regole sono elencate le regole tra cui è possibile scegliere. Per altre informazioni sull'uso dei set di regole in Visual Studio, vedere Usare i set di regole per specificare le regole C++ da eseguire.

Macro

Il controllo delle linee guida di base di C++ include un file di intestazione, che definisce le macro che semplificano l'eliminazione di intere categorie di avvisi nel codice:

ALL_CPPCORECHECK_WARNINGS
CPPCORECHECK_TYPE_WARNINGS
CPPCORECHECK_RAW_POINTER_WARNINGS
CPPCORECHECK_CONST_WARNINGS
CPPCORECHECK_OWNER_POINTER_WARNINGS
CPPCORECHECK_UNIQUE_POINTER_WARNINGS
CPPCORECHECK_BOUNDS_WARNINGS

Queste macro corrispondono ai set di regole ed espandono in un elenco delimitato da spazi di numeri di avviso. Usando i costrutti pragma appropriati, è possibile configurare il set effettivo di regole interessante per un progetto o una sezione di codice. Nell'esempio seguente l'analisi del codice avvisa solo sui modificatori costanti mancanti:

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

Attributi

Il compilatore Microsoft C++ ha un supporto limitato per l'attributo [[gsl::suppress]] . Può essere usato per eliminare gli avvisi sulle istruzioni di espressione e blocco all'interno delle funzioni.

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

Eliminare l'analisi usando le opzioni della riga di comando

Anziché #pragmas, è possibile usare le opzioni della riga di comando nella pagina delle proprietà del file per eliminare gli avvisi per un progetto o un singolo file. Ad esempio, per disabilitare l'avviso C26400 per un file:

1. Fare clic con il pulsante destro del mouse sul file in Esplora soluzioni e scegliere Proprietà.

2. Nella finestra di dialogo Pagine delle proprietà selezionare la pagina delle proprietà Proprietà>di configurazione C/C++>Riga di comando.

3. Nella casella di modifica Opzioni aggiuntive aggiungere /wd26400.

È possibile usare l'opzione della riga di comando per disabilitare temporaneamente tutte le analisi del codice per un file specificando /analyze-. Verrà visualizzato l'avviso D9025 che esegue l'override di "/analyze" con "/analyze-", che ricorda di riabilitare l'analisi del codice in un secondo momento.

Abilitare il controllo delle linee guida di base di C++ in file di progetto specifici

In alcuni casi è utile eseguire l'analisi mirata del codice e usare comunque l'IDE di Visual Studio. Provare lo scenario di esempio seguente per progetti di grandi dimensioni. Può risparmiare tempo di compilazione e rendere più semplice filtrare i risultati:

1. Nella shell dei comandi impostare la esp.extension variabile di ambiente.

2. Per ereditare questa variabile, aprire Visual Studio dalla shell dei comandi.

3. Caricare il progetto e aprire le relative proprietà.

4. Abilitare l'analisi del codice, selezionare i set di regole appropriati, ma non abilitare le estensioni di analisi del codice.

5. Passare al file che si vuole analizzare con il controllo delle linee guida di base di C++ e aprire le relative proprietà.

6. Scegliere Proprietà>di configurazione C/C++>Riga di comando>Opzioni aggiuntive e aggiungere/analyze:plugin EspXEngine.dll

7. Disabilitare l'uso dell'intestazione precompilata (Proprietà>di configurazione C/C++>Intestazioni precompilate). È necessario perché il motore delle estensioni potrebbe tentare di leggere le informazioni interne dall'intestazione precompilata (PCH). Se pch è stato compilato con le opzioni di progetto predefinite, non sarà compatibile.

8. Ricompilare il progetto. I controlli PREFast comuni devono essere eseguiti su tutti i file. Poiché il controllo delle linee guida di base di C++ non è abilitato per impostazione predefinita, deve essere eseguito solo nel file configurato per usarlo.

Come usare il controllo delle linee guida di base di C++ all'esterno di Visual Studio

È possibile usare i controlli delle linee guida di base di C++ nelle compilazioni automatizzate.

MSBuild

Il controllo di analisi del codice nativo (PREfast) è integrato nell'ambiente MSBuild da file di destinazioni personalizzate. È possibile usare le proprietà del progetto per abilitarla e aggiungere il controllo delle linee guida di base di C++ (basato su PREfast):

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

Assicurarsi di aggiungere queste proprietà prima dell'importazione del Microsoft.Cpp.targets file. È possibile selezionare set di regole specifici o creare un set di regole personalizzato. In alternativa, usare il set di regole predefinito che include altri controlli PREfast.

È possibile eseguire il controllo di base di C++ solo nei file specificati. Usare lo stesso approccio descritto in precedenza, ma usare i file MSBuild. Le variabili di ambiente possono essere impostate usando l'elemento BuildMacro :

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

Se non si vuole modificare il file di progetto, è possibile passare le proprietà nella riga di comando:

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

Progetti non MSBuild

Se si usa un sistema di compilazione che non si basa su MSBuild, è comunque possibile eseguire il controllo. Per usarlo, è necessario acquisire familiarità con alcuni elementi interni della configurazione del motore di analisi del codice. Non è garantito il supporto per questi elementi interni nelle versioni future di Visual Studio.

L'analisi del codice richiede alcune variabili di ambiente e opzioni della riga di comando del compilatore. È consigliabile usare l'ambiente del prompt dei comandi degli strumenti nativi in modo da non dover cercare percorsi specifici per il compilatore, includere directory e così via.

• Variabili di ambiente

  • set esp.extensions=cppcorecheck.dll Questo indica al motore di caricare il modulo Linee guida di base di C++.
  • Poiché Visual Studio 2019 non è più consigliabile impostare la esp.annotationbuildlevel variabile di ambiente perché l'impostazione può comportare falsi positivi. Se vengono visualizzati risultati imprevisti, rimuovere questa variabile dall'ambiente.
  • set caexcludepath=%include% È consigliabile disabilitare gli avvisi attivati nelle intestazioni standard. È possibile aggiungere altri percorsi qui, ad esempio il percorso delle intestazioni comuni nel progetto.

• Opzioni della riga di comando

  • /analyze Abilita l'analisi del codice (prendere in considerazione anche l'uso di /analyze:only e /analyze:quiet).
  • /analyze:plugin EspXEngine.dll Questa opzione carica il motore Code Analysis Extensions in PREfast. Questo motore, a sua volta, carica il controllo delle linee guida di base di C++.

Usare la libreria di supporto delle linee guida

La libreria di supporto delle linee guida (GSL) è progettata per aiutarti a seguire le linee guida di base. GSL include definizioni che consentono di sostituire costrutti soggetti a errori con alternative più sicure. Ad esempio, è possibile sostituire una T*, length coppia di parametri con il span<T> tipo . Il progetto GSL è disponibile in GitHub all'indirizzo https://github.com/Microsoft/GSL. La libreria è open source, quindi è possibile visualizzare le origini, inviare commenti o contribuire. È anche possibile usare la gestione pacchetti vcpkg per scaricare e installare la libreria in locale.

Vedi anche

• Informazioni di riferimento sul controllo di base di Visual Studio C++