Panoramica dell'analisi del codice sorgente .NET

Gli analizzatori della piattaforma del compilatore .NET (Roslyn) controllano il codice C# o Visual Basic per problemi di qualità e stile del codice. A partire da .NET 5, questi analizzatori sono inclusi in .NET SDK e non è necessario installarli separatamente. Se il progetto è destinato a .NET 5 o versione successiva, l'analisi del codice è abilitata per impostazione predefinita. Se il progetto è destinato a un'implementazione .NET diversa, ad esempio .NET Core, .NET Standard o .NET Framework, è necessario abilitare manualmente l'analisi del codice impostando la proprietà EnableNETAnalyzers su true.

Se non si vuole passare a .NET 5+ SDK, avere un progetto .NET Framework in stile non SDK o preferire un modello basato su pacchetto NuGet, gli analizzatori sono disponibili anche nel pacchetto NuGet Microsoft.CodeAnalysis.NetAnalyzers NuGet. Potrebbe essere preferibile un modello basato su pacchetto per gli aggiornamenti della versione su richiesta.

Nota

Gli analizzatori .NET sono agnostici del framework di destinazione. Questo significa che il progetto non deve essere di destinazione di un'implementazione .NET specifica. Gli analizzatori funzionano per i progetti destinati a .NET 5+ oltre alle versioni precedenti di .NET, ad esempio .NET Core 3.1 e .NET Framework 4.7.2. Tuttavia, per abilitare l'analisi del codice usando la proprietà EnableNETAnalyzers , il progetto deve fare riferimento a un SDK di progetto.

Se le violazioni delle regole vengono trovate da un analizzatore, vengono segnalate come suggerimento, avviso o errore, a seconda della modalità di configurazione di ogni regola. Le violazioni di analisi del codice vengono visualizzate con il prefisso "CA" o "IDE" per differenziarli dagli errori del compilatore.

Analisi della qualità del codice

Le regole di analisi della qualità del codice ("CAxxxx") controllano il codice C# o Visual Basic per la sicurezza, le prestazioni, la progettazione e altri problemi. L'analisi è abilitata, per impostazione predefinita, per i progetti destinati a .NET 5 o versioni successive. È possibile abilitare l'analisi del codice nei progetti destinati alle versioni precedenti di .NET impostando la proprietà EnableNETAnalyzers su true. È anche possibile disabilitare l'analisi del codice per il progetto impostando EnableNETAnalyzers su false.

Suggerimento

Se si usa Visual Studio, molte regole di analizzatore hanno correzioni del codice associate che è possibile applicare per correggere il problema. Le correzioni del codice vengono visualizzate nel menu dell'icona della lampadina.

Regole abilitate

Per impostazione predefinita, le regole seguenti sono abilitate in .NET 7.

ID di diagnostica Category Gravità Descrizione
CA1416 Interoperabilità Avviso Convalidare la compatibilità della piattaforma
CA1417 Interoperabilità Avviso Non usare OutAttribute nei parametri di stringa per P/Invokes
CA1418 Interoperabilità Avviso Usare una stringa di piattaforma valida
CA1420 Interoperabilità Avviso L'uso delle funzionalità che richiedono il marshalling di runtime quando è disabilitato genera eccezioni di runtime
CA1422 Interoperabilità Avviso Convalidare la compatibilità della piattaforma
CA1831 Prestazioni Avviso Usare AsSpan invece degli indicizzatori basati sull'intervallo per la stringa quando appropriato
CA2013 Affidabilità Avviso Non usare ReferenceEquals con i tipi di valore
CA2014 Affidabilità Avviso Non usare stackalloc nei cicli
CA2015 Affidabilità Avviso Non definire gli finalizzatori per i tipi derivati da MemoryManager<T>
CA2017 Affidabilità Avviso Mancata corrispondenza del conteggio dei parametri
CA2018 Affidabilità Avviso Argomento count da Buffer.BlockCopy specificare il numero di byte da copiare
CA2200 Uso Avviso Eseguire il rethrow per mantenere i dettagli dello stack
CA2252 Uso Errore Acconsentire esplicitamente alle funzionalità di anteprima
CA2247 Uso Avviso L'argomento passato al TaskCompletionSource costruttore deve essere TaskCreationOptions enumerazione anziché TaskContinuationOptions
CA22555 Uso Avviso L'attributo ModuleInitializer non deve essere usato nelle librerie
CA2256 Uso Avviso Tutti i membri dichiarati nelle interfacce padre devono avere un'implementazione in un'interfaccia DynamicInterfaceCastableImplementationcon attributi
CA2257 Uso Avviso I membri definiti in un'interfaccia con devono DynamicInterfaceCastableImplementationAttribute essere static
CA2258 Uso Avviso La fornitura di un'interfaccia DynamicInterfaceCastableImplementation in Visual Basic non è supportata
CA2259 Uso ThreadStatic influisce solo sui campi statici
CA2260 Uso Usare il parametro di tipo corretto

È possibile modificare la gravità di queste regole per disabilitarle o elevarle agli errori. È anche possibile abilitare altre regole.

Abilitare regole aggiuntive

La modalità di analisi si riferisce a una configurazione di analisi del codice predefinita in cui non sono abilitate nessuna, alcune o tutte le regole. Nella modalità di analisi predefinita, solo un numero ridotto di regole viene abilitato come avvisi di compilazione. È possibile modificare la modalità di analisi per il progetto impostando la <proprietà AnalysisMode> nel file di progetto. I valori consentiti sono:

None

Default

Minimum

Recommended

All

A partire da .NET 6, è possibile omettere <AnalysisMode> a favore di un valore composto per la <proprietà AnalysisLevel> . Ad esempio, il valore seguente abilita il set consigliato di regole per la versione più recente: <AnalysisLevel>latest-Recommended</AnalysisLevel>. Per altre informazioni, vedere AnalysisLevel.

Per trovare la gravità predefinita per ogni regola disponibile e se la regola è abilitata o meno nella modalità di analisi predefinita, vedere l'elenco completo delle regole.

Considera gli avvisi come errori

Se si usa il -warnaserror flag quando si compilano i progetti, anche tutti gli avvisi di analisi del codice vengono considerati errori. Se non si desidera che gli avvisi di qualità del codice (CAxxxx) vengano considerati come errori in presenza di -warnaserror, è possibile impostare la CodeAnalysisTreatWarningsAsErrors proprietà MSBuild su false nel file di progetto.

<PropertyGroup>
  <CodeAnalysisTreatWarningsAsErrors>false</CodeAnalysisTreatWarningsAsErrors>
</PropertyGroup>

Verranno comunque visualizzati avvisi di analisi del codice, ma non interromperanno la compilazione.

Aggiornamenti più recenti

Per impostazione predefinita, si otterranno le regole di analisi del codice più recenti e i livelli di gravità delle regole predefinite durante l'aggiornamento alle versioni più recenti di .NET SDK. Se questo comportamento non è necessario, ad esempio, se si vuole assicurarsi che non siano abilitate o disabilitate nuove regole, è possibile eseguirne l'override in uno dei modi seguenti:

  • Impostare la AnalysisLevel proprietà MSBuild su un valore specifico per bloccare gli avvisi su tale set. Quando si esegue l'aggiornamento a un SDK più recente, si otterranno comunque correzioni di bug per tali avvisi, ma non verranno abilitati nuovi avvisi e non verranno disabilitati avvisi esistenti. Ad esempio, per bloccare il set di regole a quelli forniti con la versione 5.0 di .NET SDK, aggiungere la voce seguente al file di progetto.

    <PropertyGroup>
      <AnalysisLevel>5.0</AnalysisLevel>
    </PropertyGroup>
    

    Suggerimento

    Il valore predefinito per la AnalysisLevel proprietà è latest, ovvero si ottengono sempre le regole di analisi del codice più recenti quando si passa alle versioni più recenti di .NET SDK.

    Per altre informazioni e per visualizzare un elenco di valori possibili, vedere AnalysisLevel.

  • Installare il pacchetto NuGet Microsoft.CodeAnalysis.NetAnalyzers per separare gli aggiornamenti delle regole dagli aggiornamenti di .NET SDK. Per i progetti destinati a .NET 5+, l'installazione del pacchetto disattiva gli analizzatori SDK predefiniti. Verrà visualizzato un avviso di compilazione se l'SDK contiene una versione più recente dell'assembly dell'analizzatore rispetto a quella del pacchetto NuGet. Per disabilitare l'avviso, impostare la _SkipUpgradeNetAnalyzersNuGetWarning proprietà su true.

    Nota

    Se si installa il pacchetto NuGet Microsoft.CodeAnalysis.NetAnalyzers, non è necessario aggiungere la proprietà EnableNETAnalyzers al file di progetto o a un file Directory.Build.props . Quando viene installato il pacchetto NuGet e la EnableNETAnalyzers proprietà è impostata su true, viene generato un avviso di compilazione.

Analisi in stile codice

Le regole di analisi in stile codice ("IDExxxx") consentono di definire e mantenere uno stile di codice coerente nella codebase. Le impostazioni di abilitazione predefinite sono:

  • Compilazione da riga di comando: l'analisi in stile codice è disabilitata, per impostazione predefinita, per tutti i progetti .NET nelle compilazioni da riga di comando.

    A partire da .NET 5, è possibile abilitare l'analisi in stile codice per la compilazione, sia nella riga di comando che all'interno di Visual Studio. Le violazioni dello stile del codice vengono visualizzate come avvisi o errori con un prefisso "IDE". In questo modo è possibile applicare stili di codice coerenti in fase di compilazione.

  • Visual Studio: l'analisi in stile codice è abilitata per impostazione predefinita per tutti i progetti .NET all'interno di Visual Studio come azioni rapide di refactoring del codice.

Per un elenco completo delle regole di analisi in stile codice, vedere Regole di stile del codice.

Abilitare in caso di compilazione

Con .NET 5 SDK e versioni successive, è possibile abilitare l'analisi in stile codice durante la compilazione dalla riga di comando e in Visual Studio. Tuttavia, per motivi di prestazioni, alcune regole di stile codice verranno comunque applicate solo nell'IDE di Visual Studio.

Seguire questa procedura per abilitare l'analisi in stile codice per la compilazione:

  1. Impostare la proprietà MSBuild EnforceCodeStyleInBuild su true.

  2. In un file con estensione editorconfigconfigurare ogni regola di stile di codice "IDE" che si vuole eseguire in compilazione come avviso o errore. Ad esempio:

    [*.{cs,vb}]
    # IDE0040: Accessibility modifiers required (escalated to a build warning)
    dotnet_diagnostic.IDE0040.severity = warning
    

    In alternativa, è possibile configurare un'intera categoria in modo che sia un avviso o un errore, per impostazione predefinita e quindi disattivare in modo selettivo le regole in tale categoria che non si vuole eseguire nella compilazione. Ad esempio:

    [*.{cs,vb}]
    
    # Default severity for analyzer diagnostics with category 'Style' (escalated to build warnings)
    dotnet_analyzer_diagnostic.category-Style.severity = warning
    
    # IDE0040: Accessibility modifiers required (disabled on build)
    dotnet_diagnostic.IDE0040.severity = silent
    

Nota

La funzionalità di analisi in stile codice è sperimentale e può cambiare tra le versioni di .NET 5 e .NET 6.

Eliminare un avviso

Un modo per eliminare una violazione di regola consiste nell'impostare l'opzione di gravità per tale ID regola su none in un file EditorConfig. Ad esempio:

dotnet_diagnostic.CA1822.severity = none

Per altre informazioni e altri modi per eliminare gli avvisi, vedere Come eliminare gli avvisi di analisi del codice.

Eseguire l'analisi del codice come azione GitHub

Dotnet/code-analysis GitHub Action consente di eseguire analizzatori di codice .NET come parte dell'integrazione continua (CI) in modalità offline. Per altre informazioni, vedere GitHub Action per l'analisi del codice .NET.

Analizzatori di terze parti

Oltre agli analizzatori .NET ufficiali, è anche possibile installare analizzatori di terze parti, ad esempio StyleCop, Roslynator, XUnit Analyzers e Sonar Analyzer.

Vedi anche