Panoramica dell'analisi del codice sorgente .NET

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. 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. Per informazioni sull'abilitazione dell'analisi del codice nei progetti destinati a .NET Framework, vedere Abilitare l'analisi del codice nei progetti legacy.

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") 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 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 correzioni del codice associate che possono essere applicate per correggere automaticamente il problema. Le correzioni del codice sono visualizzate nel menu dell'icona a forma di lampadina.

Regole abilitate

Per impostazione predefinita, le regole seguenti sono abilitate come errori o avvisi in .NET 11. Le regole aggiuntive vengono abilitate come suggerimenti.

ID di diagnostica Categoria Gravità Versione aggiunta Descrizione
CA1416 Interoperabilità Avviso .NET 5 Convalidare la 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 è disabilitato genererà eccezioni di runtime
CA1422 Interoperabilità Avviso .NET 7 Convalida la compatibilità della piattaforma
CA1831 Prestazioni Avviso .NET 5 Usare AsSpan invece di indicizzatori basati su intervalli per le stringhe, se 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 Numero di parametri non corrispondente
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
CA2022 Affidabilità Avviso .NET 9 Evitare la lettura inesatta con Stream.Read
CA2023 Affidabilità Avviso .NET 10 Parentesi graffe non valide nel modello di messaggio
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 Abilitare le 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 attribuita con 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>
CA2264 Utilizzo Avviso .NET 9 Non passare un valore non nullable a ArgumentNullException.ThrowIfNull
CA2265 Utilizzo Avviso .NET 9 Non confrontare Span<T> con null o default
CA2266 Utilizzo Avviso .NET 10 Il punto di ingresso del programma basato su file deve iniziare con #!
CA2267 Utilizzo Avviso .NET 11 Spazi vuoti tra virgolette nei valori della direttiva del programma basata su file

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

Abilita 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 attivare selettivamente 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 vivamente consigliati per l'applicazione nella 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.globalconfig. Per .NET 7 e versioni precedenti, l'estensione del file è .editorconfig.)
Recommended Modalità più aggressiva rispetto alla modalità Minimum, in cui sono abilitate più regole come avvisi di compilazione. Per visualizzare quali regole sono incluse, esaminare il file %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.globalconfig. Per .NET 7 e versioni precedenti, l'estensione del file è .editorconfig.)
All Tutte le regole vengono abilitate come avvisi di compilazione*. È possibile escludere selettivamente 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>.

È anche possibile omettere <AnalysisMode> a favore di un valore composto per la <AnalysisLevel> proprietà . 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 gli 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, le regole di analisi del codice e i livelli di gravità predefiniti corrispondono alla versione del framework di destinazione. La versione più recente rilasciata .NET supportata dall'SDK usa le regole più recenti. I framework di destinazione meno recenti mantengono le regole corrispondenti, anche quando si compila con un SDK più recente. Per usare le regole più recenti indipendentemente dal framework di destinazione, impostare AnalysisLevel su latest.

  • 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, se si esegue l'aggiornamento da .NET 10 a .NET 11, ma si desidera mantenere le regole .NET 10, aggiungere la voce seguente al file di progetto.

    <PropertyGroup>
      <AnalysisLevel>10.0</AnalysisLevel>
    </PropertyGroup>
    

    Suggerimento

    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 dello stile del codice

Le regole di analisi dello stile del 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 di tipo codice è disabilitata, per impostazione predefinita, per tutti i progetti .NET nelle compilazioni da riga di comando.

    È 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 dello stile del codice è abilitata per impostazione predefinita per tutti i progetti .NET all'interno di Visual Studio come azioni rapide di refactoring del codice.

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

Abilita in compilazione

È possibile abilitare l'analisi dello stile del 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 in 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
    

Sopprimere 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.

Abilitare l'analisi del codice nei progetti legacy

L'analisi del codice è abilitata per impostazione predefinita per i progetti destinati a .NET 5 o versioni successive. Se il progetto è destinato a .NET Standard o .NET Framework, è necessario abilitare manualmente l'analisi del codice impostando la proprietà EnableNETAnalyzers su true.

Se il progetto usa il formato di file di progetto legacy, ovvero non fa riferimento a un SDK di progetto, è necessario eseguire alcuni passaggi aggiuntivi per abilitare l'analisi del codice:

  1. Aggiungere un riferimento al 📦 pacchetto NuGet Microsoft.CodeAnalysis.NetAnalyzers.
  2. Invece di impostare AnalysisLevel, che non è riconosciuto dai progetti non in stile SDK, aggiungere le proprietà seguenti al file di progetto:
  <EffectiveAnalysisLevel>9</EffectiveAnalysisLevel>
  <AnalysisMode>Recommended</AnalysisMode>

Analizzatori di terze parti

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

Vedi anche