Panoramica dell'analisi del codice sorgente .NET

  • Articolo

Gli analizzatori della piattaforma del compilatore .NET (Roslyn) ispezionano il codice C# o Visual Basic per individuare problemi relativi alla qualità e allo stile del codice. A partire da .NET 5, questi analizzatori sono inclusi in .NET SDK e non è necessario installarli separatamente. L'analisi del codice è abilitata per impostazione predefinita per i progetti destinati a .NET 5 o versioni successive. 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, si dispone di un progetto .NET Framework non in stile SDK o si preferisce un modello basato su pacchetto NuGet, gli analizzatori sono disponibili anche nel pacchetto NuGet Microsoft.CodeAnalysis.NetAnalyzers. Si potrebbe anche preferire un modello basato su pacchetto per gli aggiornamenti delle versioni su richiesta.

Nota

Gli analizzatori .NET sono indipendenti dal framework di destinazione. Ciò significa che il progetto non deve avere come destinazione un'implementazione .NET specifica. Gli analizzatori funzionano per i progetti destinati a .NET 5+ e versioni precedenti, 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 un analizzatore rileva violazioni delle regole, queste vengono segnalate come suggerimenti, avvisi o errori, a seconda di come è configurata ciascuna regola. Le violazioni dell'analisi del codice vengono visualizzate con il prefisso "CA" o "IDE" per differenziarle dagli errori del compilatore.

Analisi della qualità del codice

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

Suggerimento

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

Regole abilitate

Le regole seguenti sono abilitate, per impostazione predefinita, come errori o avvisi in .NET 8. Le regole aggiuntive vengono abilitate come suggerimenti.

ID di diagnostica Categoria Gravità Versione aggiunta Descrizione
CA1416 Interoperabilità Avviso .NET 5 Convalida compatibilità della piattaforma
CA1417 Interoperabilità Avviso .NET 5 Non usare OutAttribute sui parametri di stringa per P/Invokes
CA1418 Interoperabilità Avviso .NET 6 Usare una stringa di piattaforma valida
CA1420 Interoperabilità Avviso .NET 7 L'uso di funzionalità che richiedono il marshalling di runtime quando lo stesso è disabilitato genererà eccezioni di runtime
CA1422 Interoperabilità Avviso .NET 7 Convalida compatibilità della piattaforma
CA1831 Prestazioni Avviso .NET 5 Usare AsSpan invece di indicizzatori basati su intervallo per la stringa quando appropriato
CA1856 Prestazioni Error .NET 8 Utilizzo non corretto dell'attributo ConstantExpected
CA1857 Prestazioni Avviso .NET 8 È prevista una costante per il parametro
CA2013 Affidabilità Avviso .NET 5 Non usare ReferenceEquals con i tipi valore
CA2014 Affidabilità Avviso .NET 5 Non usare stackalloc nei cicli
CA2015 Affidabilità Avviso .NET 5 Non definire finalizzatori per i tipi derivati da MemoryManager<T>
CA2017 Affidabilità Avviso .NET 6 Mancata corrispondenza del conteggio dei parametri
CA2018 Affidabilità Avviso .NET 6 L'argomento count di Buffer.BlockCopy dovrebbe specificare il numero di byte da copiare
CA2021 Affidabilità Avviso .NET 8 Non chiamare Enumerable.Cast<T> o Enumerable.OfType<T> con tipi incompatibili
CA2200 Utilizzo Avviso .NET 5 Eseguire il rethrow per mantenere i dettagli dello stack
CA2247 Utilizzo Avviso .NET 5 L'argomento passato al costruttore TaskCompletionSource deve essere l'enumerazione TaskCreationOptions anziché TaskContinuationOptions
CA2252 Utilizzo Error .NET 6 Fornire consenso esplicito alle funzionalità di anteprima
CA2255 Utilizzo Avviso .NET 6 L'attributo ModuleInitializer non deve essere usato nelle librerie
CA2256 Utilizzo Avviso .NET 6 Tutti i membri dichiarati nelle interfacce padre devono avere un'implementazione in un'interfaccia con attributi DynamicInterfaceCastableImplementation
CA2257 Utilizzo Avviso .NET 6 I membri definiti in un'interfaccia con DynamicInterfaceCastableImplementationAttribute devono essere static
CA2258 Utilizzo Avviso .NET 6 La fornitura di un'interfaccia DynamicInterfaceCastableImplementation in Visual Basic non è supportata
CA2259 Utilizzo Avviso .NET 7 ThreadStatic influisce solo sui campi statici
CA2260 Utilizzo Avviso .NET 7 Usare il parametro di tipo corretto
CA2261 Utilizzo Avviso .NET 8 Non usare ConfigureAwaitOptions.SuppressThrowing con Task<TResult>

È possibile modificare il livello di gravità di queste regole per disabilitarle o elevarle allo stato di errore. È inoltre possibile abilitare regole aggiuntive.

Abilitare regole aggiuntive

La modalità di analisi si riferisce a una configurazione di analisi del codice predefinita in cui nessuna, alcune o tutte le regole sono abilitate. Nella modalità di analisi predefinita (Default), 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:

Valore Descrizione
None Tutte le regole sono disabilitate. È possibile acconsentire in modo selettivo alle singole regole per abilitarle.
Default Modalità predefinita, in cui alcune regole sono abilitate come avvisi di compilazione, alcune regole vengono abilitate come suggerimenti dell'IDE di Visual Studio e il resto sono disabilitate.
Minimum Modalità più aggressiva rispetto alla modalità Default. Alcuni suggerimenti consigliati per l'imposizione della compilazione sono abilitati come avvisi di compilazione. Per visualizzare le regole incluse, esaminare il file %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.editorconfig.
Recommended Modalità più aggressiva rispetto alla modalità Minimum, in cui sono abilitate più regole come avvisi di compilazione. Per visualizzare le regole incluse, esaminare il file %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.editorconfig.
All Tutte le regole vengono abilitate come avvisi di compilazione*. È possibile rifiutare esplicitamente le singole regole per disabilitarle.

* Le regole seguenti non sono abilitate impostandoAnalysisMode su All o impostando AnalysisLevel su latest-all: CA1017, CA1045, CA1005, CA1014, CA1060, CA1021 e le regole dell'analizzatore delle metriche del codice (CA1501, CA1502, CA1505, CA1506 e CA1509). Queste regole legacy potrebbero essere deprecate in una versione futura. Tuttavia, è comunque possibile abilitarle singolarmente usando una voce dotnet_diagnostic.CAxxxx.severity = <severity>.

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 di regole consigliato per la versione più recente: <AnalysisLevel>latest-Recommended</AnalysisLevel>. Per ulteriori informazioni, vedere AnalysisLevel.

Per individuare il livello di gravità predefinito per ogni regola disponibile o comprendere se la regola è abilitata o meno in modalità di analisi Default, vedere l'elenco completo delle regole.

Considera avvisi come errori

Se si usa il flag -warnaserror quando si compilano i progetti, anche tutti gli avvisi di analisi della qualità del codice vengono considerati come errori. Se non si desidera che gli avvisi della qualità del codice (CAxxxx) vengano considerati come errori in presenza di -warnaserror, è possibile impostare la proprietà MSBuild CodeAnalysisTreatWarningsAsErrors 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 non si vuole questo comportamento e, ad esempio, ci si vuole assicurare che non siano abilitate o disabilitate nuove regole, è possibile eseguire l'override in uno dei seguenti modi:

  • Impostare la proprietà MSBuild AnalysisLevel 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 proprietà AnalysisLevel è latest, ciò significa che si otterranno sempre le regole di analisi del codice più recenti quando si passa alle versioni più recenti di .NET SDK.

    Per ottenere ulteriori informazioni e per visualizzare un elenco di valori possibili, consultare la sezione 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 dell'assembly dell'analizzatore più recente rispetto a quella del pacchetto NuGet. Per disabilitare l'avviso, impostare la proprietà _SkipUpgradeNetAnalyzersNuGetWarning su true.

    Nota

    Se si installa il pacchetto NuGet Microsoft.CodeAnalysis.NetAnalyzers, non è consigliabile aggiungere la proprietà EnableNETAnalyzers al file di progetto o a un file Directory.Build.props. Quando viene installato il pacchetto NuGet e la proprietà EnableNETAnalyzers è 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 le seguenti:

  • 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 refactoring delle azioni rapide da parte del codice .

Per ottenere un elenco completo delle regole di analisi in stile codice, consultare l'articolo Regole in stile codice.

Abilitare per la 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 in 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 .editorconfig, configurare ogni regola di stile di codice "IDE" che si vuole eseguire in fase di compilazione come avviso o errore. Ad esempio:

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

    Suggerimento

    A partire da .NET 9, è anche possibile usare il formato di opzione per specificare un livello di gravità e farlo rispettare in fase di compilazione. Ad esempio:

    [*.{cs,vb}]
# IDE0040: Accessibility modifiers required (escalated to a build warning)
dotnet_style_require_accessibility_modifiers = always: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

Eliminare un avviso

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

dotnet_diagnostic.CA1822.severity = none

Per ricevere ulteriori informazioni e scoprire altri modi per eliminare gli avvisi, consultare l'articolo Come eliminare gli avvisi di analisi del codice.

Eseguire l'analisi del codice come azione GitHub

L'azione GitHub dotnet/code-analysis consente di eseguire analizzatori di codice .NET come parte dell'integrazione continua (CI) in modalità offline. Per ricevere altre informazioni, vedere la sezione Azioni GitHub per l'analisi del codice .NET.

Analizzatori di terze parti

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

Vedi anche