Opzioni di configurazione per l'analisi codice

  • Articolo

Le regole di analisi codice hanno diverse opzioni di configurazione. Alcune di queste opzioni vengono specificate come coppie chiave-valore in un file di configurazione dell'analizzatore usando la sintassi <option key> = <option value>. Altre opzioni, che configurano l'analisi del codice nel suo complesso, sono disponibili come proprietà MSBuild nel file di progetto.

L'opzione più comune che verrà configurata è la gravità di una regola. È possibile configurare il livello di gravità per qualsiasi regola, incluse le regole di qualità del codice e le regole di stile del codice. Ad esempio, per abilitare una regola come avviso, aggiungere la coppia chiave-valore seguente a un file di configurazione dell'analizzatore:

dotnet_diagnostic.<rule ID>.severity = warning

Inoltre, è possibile configurare opzioni aggiuntive per personalizzare il comportamento delle regole:

  • Le regole di qualità del codice hanno opzioni di comportamento, ad esempio i nomi dei metodi a cui deve essere applicata una regola.
  • Le regole di stile del codice hanno opzioni di preferenza per lo stile , ad esempio i casi in cui sono auspicabili nuove righe.
  • Le regole di analizzatori di terze parti possono definire opzioni proprie di configurazione, con nomi di chiave e formati di valore personalizzati.

Opzioni generali

Tali opzioni si applicano all'analisi del codice nel suo complesso. Non possono essere applicate solo a una regola specifica.

Per altre opzioni, vedere Proprietà di analisi codice.

Modalità di analisi

Anche se .NET SDK include tutte le regole di analisi codice, solo alcune di esse sono abilitate per impostazione predefinita. La modalità di analisi determina quale set di regole, se presente, vada abilitato. È possibile scegliere una modalità di analisi più aggressiva in cui la maggior parte o tutte le regole sono abilitate. In alternativa, è possibile scegliere una modalità di analisi più conservativa, in cui la maggior parte o tutte le regole sono disabilitate ed è quindi possibile acconsentire esplicitamente a regole specifiche in base alle proprie esigenze. Impostare la modalità di analisi aggiungendo la proprietà MSBuild < AnalysisMode> al file di progetto.

<PropertyGroup>
  <AnalysisMode>Recommended</AnalysisMode>
</PropertyGroup>

A partire da .NET 6, è inoltre possibile abilitare in blocco una categoria di regole usando la proprietà MSBuild Categoria<<AnalysisMode>>.

Nota

Se si configura l'analisi del codice usando proprietà di MSBuild come AnalysisMode, tutte le opzioni di configurazione in blocco impostate nel file di configurazione vengono ignorate. Ad esempio, se sono state abilitate in blocco tutte le regole o una categoria di regole in un file .editorconfig, tale configurazione viene ignorata.

Abilitare l'analisi del codice

L'analisi del codice è abilitata per impostazione predefinita per i progetti destinati a .NET 5 e versioni successive. Se si dispone di .NET 5+ SDK, ma il progetto è destinato a un'implementazione .NET diversa, è possibile abilitare manualmente l'analisi del codice impostando la proprietà EnableNETAnalyzers nel file di progetto su true.

<PropertyGroup>
  <EnableNETAnalyzers>true</EnableNETAnalyzers>
</PropertyGroup>

Escludere il codice generato

Gli avvisi dell'analizzatore del codice .NET non sono utili per i file di codice generati dalla finestra di progettazione, come i file generati dalla finestra di progettazione, che gli utenti non possono modificare per correggere eventuali violazioni. Nella maggior parte dei casi, gli analizzatori del codice ignorano i file di codice generati e non segnalano violazioni su questi file.

Per impostazione predefinita, i file con determinate estensioni di file o intestazioni di file generati automaticamente vengono considerati come file di codice generati. Ad esempio, un nome di file che termina con .designer.cs o .generated.cs viene considerato codice generato. Questa opzione di configurazione consente di specificare modelli di denominazione aggiuntivi da considerare come codice generato. È possibile configurare file e cartelle aggiuntivi aggiungendo una voce generated_code = true | falseal file di configurazione. Ad esempio, per trattare tutti i file il cui nome termina con .MyGenerated.cs come codice generato, aggiungere la voce seguente:

[*.MyGenerated.cs]
generated_code = true

Opzioni specifiche delle regole

Le opzioni specifiche delle regole possono essere applicate a una singola regola, a un set di regole o a tutte le regole. Le opzioni specifiche delle regole includono:

Livello di gravità

La tabella seguente illustra i diversi livelli di gravità delle regole che è possibile configurare per tutte le regole dell'analizzatore, incluse le regole di qualità del codice e di stile del codice.

Valore di configurazione gravità Comportamento in fase di compilazione
error Le violazioni vengono visualizzate come errori di compilazione e determinano l'esito negativo delle compilazioni.
warning Le violazioni vengono visualizzate come avvisi di compilazione, ma non determinano errori nelle compilazioni (a meno che non sia impostata un'opzione che consideri gli avvisi come errori).
suggestion Le violazioni vengono visualizzate come messaggi di compilazione e come suggerimenti nell'IDE di Visual Studio. (In Visual Studio i suggerimenti sono indicati da tre punti grigi sotto i primi due caratteri.)
silent Le violazioni non sono visibili all'utente.

Per le regole di stile del codice, tuttavia, le funzionalità di generazione del codice di Visual Studio generano ancora codice in questo stile. Queste regole fanno anche parte della pulizia e vengono visualizzate nel menu Azioni rapide e refactoring in Visual Studio.
none La regola viene eliminata completamente.

Per le regole di stile del codice, tuttavia, le funzionalità di generazione del codice di Visual Studio generano ancora codice in questo stile.
default Viene utilizzata la gravità predefinita della regola. I livelli di gravità predefiniti per ogni versione di .NET sono elencati nel repository roslyn-analyzers. In tale tabella, "Disabled" corrisponde a none, "Hidden" corrisponde a silent e "Info" corrisponde a suggestion.

Ambito

  • Regola singola

    Per impostare la gravità della regola per una regola singola, usare la sintassi seguente.

    dotnet_diagnostic.<rule ID>.severity = <severity value>

  • Categoria di regole

    Per impostare la gravità predefinita della regola per una categoria di regole, usare la sintassi seguente. Tuttavia, tale impostazione di gravità influisce solo sulle regole nella categoria abilitata per impostazione predefinita.

    dotnet_analyzer_diagnostic.category-<rule category>.severity = <severity value>

    Le diverse categorie sono elencate e descritte in Categorie di regole. Inoltre, è possibile trovare la categoria per una regola specifica nella relativa pagina di riferimento, ad esempio CA1000.

  • Tutte le regole

    Per impostare la gravità della regola predefinita per tutte le regole dell'analizzatore, usare la sintassi seguente. Tuttavia, questa impostazione di gravità influisce solo sulle regole abilitate per impostazione predefinita.

    dotnet_analyzer_diagnostic.severity = <severity value>

Importante

Quando si configura il livello di gravità per più regole con una singola voce, per una categoria di regole o per tutte le regole, la gravità si applica solo alle regole abilitate per impostazione predefinita. Se si abilitano tutte le regole usando le proprietà di MSBuild <AnalysisMode> o <AnalysisLevel>, eventuali opzioni dotnet_analyzer_diagnostic in blocco vengono ignorate. Per questo motivo, è preferibile abilitare una categoria di regole impostando <Categoria<AnalysisMode>> su All.

Nota

Il prefisso per l'impostazione della gravità per una singola regola, dotnet_diagnostic, è leggermente diverso dal prefisso per la configurazione della gravità tramite categoria o per tutte le regole, che è dotnet_analyzer_diagnostic.

Precedenza

Se sono presenti più voci di configurazione di gravità che possono essere applicate allo stesso ID regola, la precedenza viene scelta nell'ordine seguente:

  • Una voce per una categoria ha la precedenza su una voce per tutte le regole dell'analizzatore.
  • Una voce per una singola regola per ID ha la precedenza su una voce per una categoria.

Si consideri l'esempio seguente, dove CA1822 ha la categoria "Prestazioni":

[*.cs]
dotnet_diagnostic.CA1822.severity = error
dotnet_analyzer_diagnostic.category-performance.severity = warning
dotnet_analyzer_diagnostic.severity = suggestion

Nell'esempio precedente, tutte e tre le voci di gravità sono applicabili a CA1822. Tuttavia, usando le regole di precedenza specificate, la prima voce basata su ID regola prevale sulle voci successive. In questo esempio, CA1822 avrà una gravità effettiva di error. Tutte le altre regole all'interno della categoria "Prestazioni" avranno una gravità pari a warning.

Per informazioni sulla modalità di decisione della precedenza tra file, vedere la sezione Precedenza dell'articolo File di configurazione.