Personalizzare le regole dell'analizzatore Roslyn

Ogni regola dell'analizzatore Roslyn, o diagnostica, ha uno stato di gravità e eliminazione predefinito che è possibile personalizzare per il progetto. Questo articolo illustra l'impostazione dei livelli di gravità dell'analizzatore e l'eliminazione delle violazioni dell'analizzatore.

Livelli di gravità

È possibile configurare la gravità delle regole dell'analizzatore in un file EditorConfig e dal menu lampadina.

La tabella seguente illustra le diverse opzioni di gravità che è possibile configurare per una diagnostica:

Gravità (Esplora soluzioni)	Gravità (file EditorConfig)	Comportamento in fase di compilazione	comportamento Editor
Errore	error	Le violazioni vengono visualizzate nella scheda Errore nella finestra Elenco errori e nell'output della compilazione della riga di comando e causano l'esito negativo delle compilazioni.	Il codice che causa l'errore è sottolineato con una linea ondulata rossa e contrassegnata da una piccola casella rossa nella barra di scorrimento.
Avvertimento	warning	Le violazioni vengono visualizzate nella scheda Avviso nella finestra Elenco errori e nell'output della compilazione della riga di comando, ma non causano l'esito negativo delle compilazioni.	Il codice che causa l'errore è sottolineato con una linea ondulata verde e contrassegnata da una piccola casella verde nella barra di scorrimento.
Suggerimento	suggestion	Le violazioni vengono visualizzate nella scheda Messaggio nella finestra Elenco errori , ma non nell'output della compilazione della riga di comando.	Il codice interessato è sottolineato con una linea ondulata grigia e contrassegnata da una piccola casella grigia nella barra di scorrimento.
Automatico	silent	Invisibile all'utente.	Invisibile all'utente, ma la diagnostica viene segnalata al motore di diagnostica dell'IDE.
Nessuno	none	Soppresso completamente.	Soppresso completamente.
Predefinito	default	Corrisponde alla gravità predefinita della regola. Per determinare il valore predefinito per una regola, visualizzarne la finestra Proprietà.	Corrisponde alla gravità predefinita della regola.

Visualizzare le violazioni delle regole

Se un analizzatore rileva eventuali violazioni delle regole dell'analizzatore, le segnala nella finestra Elenco errori e nell'editor di codice.

Lo screenshot seguente mostra le violazioni delle regole segnalate nella finestra Elenco errori . Le violazioni dell'analizzatore segnalate nell'elenco degli errori corrispondono all'impostazione del livello di gravità della regola:

Le violazioni delle regole dell'analizzatore vengono visualizzate anche nell'editor di codice come linee ondulate sotto il codice che causa l'errore. Ad esempio, lo screenshot seguente mostra tre violazioni: un errore (linea ondulata rossa), un avviso (linea ondulata verde) e un suggerimento (tre punti grigi):

Molte operazioni di diagnostica includono una o più correzioni di codice associate che è possibile applicare per correggere la violazione della regola. Le correzioni del codice vengono visualizzate nel menu dell'icona a forma di lampadina insieme ad altri tipi di azioni rapide. Per altre informazioni sulle correzioni del codice, vedere Azioni rapide comuni.

Configurare i livelli di gravità

È possibile impostare la gravità della regola usando uno dei metodi seguenti:

• EditorConfig
• Menu lampadina
• Esplora soluzioni

Invisibile all'utente e nessuna gravità

Silent Le regole di gravità abilitate per impostazione predefinita differiscono dalle regole disabilitate o None di gravità:

• Se una correzione del codice viene registrata per una regola di gravità Silent, Visual Studio offre la correzione del codice come azione di refactoring visualizzata con un'icona a forma di lampadina, anche se la diagnostica nascosta non è visibile all'utente. Se la regola di gravità è disabilitata come None, la correzione del codice non viene offerta.
• Le voci che impostano la gravità di più regole dell'analizzatore contemporaneamente in un file EditorConfig possono configurare Silent in blocco le regole di gravità. None Le regole di gravità non possono essere configurate in questo modo. Devono invece essere configurati tramite voci che impostano la gravità in un file EditorConfig per ogni ID regola.

Impostare la gravità della regola in un file EditorConfig

I file EditorConfig sono disponibili in Visual Studio 2019 versione 16.3 e successive.

L'impostazione della gravità di una regola in un file EditorConfig ha la precedenza su qualsiasi set di gravità impostato in un set di regole o in Esplora soluzioni. È possibile configurare la gravità manualmente in un file EditorConfig o automaticamente tramite la lampadina visualizzata accanto a una violazione.

Configurare manualmente la gravità della regola in un file EditorConfig

Per configurare la gravità della regola, seguire questa procedura:

1. Aggiungere un file EditorConfig al progetto, se non ne è già disponibile uno.

2. Aggiungere una voce per ogni regola da configurare nell'estensione di file corrispondente.

   Ad esempio, la voce per impostare la gravità di CA1822 su error per i file C# è la seguente:

   [*.cs]
   dotnet_diagnostic.CA1822.severity = error
   

3. È possibile impostare la gravità della regola per ogni ID regola di diagnostica in un file EditorConfig con la sintassi seguente:

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

4. Per gli analizzatori in stile codice IDE, è anche possibile configurarli in un file EditorConfig usando una sintassi diversa.

   Ad esempio: dotnet_style_qualification_for_field = false:suggestion. Tuttavia, se si imposta un livello di gravità usando la dotnet_diagnostic sintassi, ha la precedenza. Per altre informazioni, vedere Convenzioni del linguaggio per EditorConfig.

Impostare la gravità di più regole dell'analizzatore contemporaneamente in un file EditorConfig

La possibilità di impostare più regole dell'analizzatore contemporaneamente in un file EditorConfig è disponibile in Visual Studio 2019 versione 16.5 e successive.

È possibile impostare la gravità per una categoria specifica di regole dell'analizzatore o per tutte le regole dell'analizzatore con una singola voce in un file EditorConfig:

• Impostare la gravità della regola per una categoria di regole dell'analizzatore:

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

• Impostare la gravità della regola per tutte le regole dell'analizzatore:

  dotnet_analyzer_diagnostic.severity = <severity>

Le voci che configurano più regole dell'analizzatore contemporaneamente si applicano solo alle regole abilitate per impostazione predefinita. Le regole dell'analizzatore contrassegnate come disabilitate per impostazione predefinita nel pacchetto dell'analizzatore devono essere abilitate tramite voci esplicite dotnet_diagnostic.<rule ID>.severity = <severity> .

Se sono presenti più voci applicabili a un ID regola specifico, l'ordine di precedenza per la voce applicabile è il seguente:

• Una voce di gravità per una singola regola per ID ha la precedenza su una voce di gravità per una categoria.
• Una voce di severità per una categoria ha la precedenza su una voce di severità per ogni regola dell'analizzatore.

Si consideri l'esempio EditorConfig seguente, dove CA1822 è una regola delle prestazioni:

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

In questo esempio, tutte e tre le voci si applicano alla regola di prestazioni CA1822. Tuttavia, usando le regole di precedenza specificate, la prima voce di gravità basata sul ID della regola ha la precedenza sulle voci successive. In questo esempio, CA1822 ha una gravità effettiva di error. Le altre regole di prestazione rimanenti hanno una gravità di warning. Le regole dell'analizzatore, che non sono regole di prestazioni, hanno una gravità pari a suggestion.

Impostare la gravità della regola dal menu della lampadina

Visual Studio offre un modo pratico per configurare la gravità di una regola dal menu Lampadina Azioni rapide . Segui questi passaggi:

1. Dopo che si verifica una violazione, passare il puntatore del mouse sulla riga ondulata di violazione nell'editor e scegliere Mostra possibili correzioni per aprire il menu lampadina. In alternativa, posiziona il cursore sulla riga e premi Ctrl+. (punto).

2. Dal menu della lampadina, passa il puntatore del mouse su un livello di severità per un'anteprima della modifica, quindi configura la severità in base alle opzioni seguenti.

   • Configurare la <gravità dell'ID> regola. Impostare la gravità per la regola specifica.

   • Configura la gravità per tutti gli <analizzatori di stile>. Impostare la gravità per tutte le regole nella categoria di regole specifica.

   • Configurare la gravità per tutti gli analizzatori. Impostare la gravità per tutte le categorie di regole dell'analizzatore.

     Nell'esempio seguente selezionare Elimina o configura problemi>Configurare la gravità dell'ID <> regola.

     

3. Scegliere una delle opzioni di gravità.

   

   Visual Studio aggiunge una voce al file EditorConfig per configurare la regola al livello di gravità richiesto, come illustrato nella casella di anteprima.

   Se nel progetto non è già presente un file EditorConfig, Visual Studio ne crea uno automaticamente.

Impostare la gravità della regola in Solution Explorer

Per impostare la gravità della regola da Esplora soluzioni, seguire questa procedura:

1. In Esplora soluzioni, espandi Riferimenti>Analizzatori (o Dipendenze>Analizzatori per progetti .NET Core).

2. Espandi l'assembly contenente la regola per cui vuoi definire la gravità.

3. Fare clic con il pulsante destro del mouse sulla regola e scegliere Imposta gravità. Nel menu di scelta rapida scegliere una delle opzioni di gravità.

   Visual Studio aggiunge una voce al file EditorConfig per configurare la regola al livello richiesto. Se il progetto utilizza un file del set di regole anziché un file EditorConfig, il livello di gravità viene aggiunto al file del set di regole.

   Se nel progetto non è già presente un file EditorConfig o un file di set di regole, Visual Studio crea automaticamente un nuovo file EditorConfig.

Visualizzare analizzatori e diagnostiche da Soluzione Explorer

È possibile eseguire gran parte della personalizzazione della diagnostica dell'analizzatore da Esplora soluzioni. Se si installa un analizzatore come pacchetto NuGet, un nodo Analizzatori viene visualizzato sotto il nodo Riferimenti (o il nodo Dipendenze per i progetti .NET Core) in Esplora soluzioni. Segui questi passaggi per visualizzare gli analizzatori e le diagnostiche.

1. In Esplora soluzioni, espandi il progetto, espandi Riferimenti o Dipendenze, quindi espandi Analizzatori. Espandere uno degli assembly dell'analizzatore per visualizzare le diagnostiche nell'assembly.

   L'icona accanto a ogni diagnostica indica il livello di gravità:

   • x in un cerchio indica una gravità dell'errore
   • ! in un triangolo indica un livello di gravità Avvertenza
   • i in un cerchio a tinta unita indica una gravità di Suggerimento
   • i in un cerchio punteggiato indica una gravità di Silent
   • Freccia rivolta verso il basso in un cerchio a tinta unita indica una gravità di Nessuno

   

2. Per visualizzare le proprietà di una diagnostica, inclusa la descrizione e la gravità predefinita, fare clic con il pulsante destro del mouse sulla diagnostica e quindi scegliere Proprietà. In alternativa, selezionare la diagnostica e quindi premere ALT+INVIO.

   Viene visualizzata la finestra Proprietà.

   

3. Per visualizzare le proprietà per le regole di stile del codice (prefisso IDE) nella finestra Proprietà , ad esempio la gravità predefinita, impostare la proprietà EnforceCodeStyleInBuild su true.

4. Per la documentazione online per una diagnostica, fare clic con il pulsante destro del mouse sulla diagnostica e quindi scegliere Visualizza guida.

Convertire un file del set di regole esistente in un file EditorConfig

In Visual Studio 2019 versione 16.5 e successive i file del set di regole sono deprecati a favore dei file EditorConfig per la configurazione dell'analizzatore per il codice gestito. I file EditorConfig sono più flessibili e consentono di configurare sia i livelli di gravità delle regole dell'analizzatore che le opzioni di analizzatore, incluse le opzioni di stile del codice dell'IDE di Visual Studio. Poiché gli strumenti di Visual Studio per la configurazione della gravità delle regole dell'analizzatore sono ora ottimizzati per lavorare con i file EditorConfig anziché con i file del set di regole, è consigliabile convertire tutti i progetti esistenti che usano ancora i file del set di regole.

Quando si converte il file del set di regole esistente in un file EditorConfig, salvarlo nella radice del repository o nella cartella della soluzione. In questo modo si garantisce che le impostazioni di gravità di questo file vengano applicate automaticamente all'intero repository o alla soluzione, rispettivamente.

È possibile convertire un file del set di regole esistente in un file EditorConfig usando l'editor del set di regole o la riga di comando.

Annotazioni

I progetti .NET Core e .NET 5+ non supportano i comandi di menu per i set di regole in Esplora soluzioni, ad esempio Apri set di regole attive. Per specificare un set di regole non predefinito per un progetto .NET Core o .NET 5+, aggiungere manualmente la proprietà CodeAnalysisRuleSet al file di progetto. È comunque possibile configurare le regole all'interno del set di regole nell'editor del set di regole.

Per usare l'editor del set di regole, seguire questa procedura. Se il progetto usa già un file del set di regole specifico per il valore della CodeAnalysisRuleSet proprietà, è possibile convertirlo in un file EditorConfig equivalente dall'editor del set di regole:

1. Fare doppio clic sul file del set di regole in Esplora soluzioni.

   Il file del set di regole viene aperto nell'editor del set di regole con una barra informazioni selezionabile nella parte superiore.

   

2. Selezionare il link infobar per migrare il file dell'editor del set di regole.

3. Nella finestra di dialogo Salva con nome selezionare la directory in cui si vuole generare il file EditorConfig e quindi selezionare Salva.

   EditorConfig generato viene aperto nell'editor. Inoltre, la proprietà CodeAnalysisRuleSet MSBuild viene aggiornata nel file di progetto in modo che non faccia più riferimento al file del set di regole originale.

   Il file del set di regole originale può essere rimosso dal progetto.

   Annotazioni

   In un progetto .NET Framework il file del set di regole predefinito non può essere migrato o rimosso dal progetto.

Per usare la riga di comando, seguire questa procedura:

1. Installare il pacchetto NuGet Microsoft.CodeAnalysis.RulesetToEditorconfigConverter.

2. Eseguire RulesetToEditorconfigConverter.exe dal pacchetto installato, con i percorsi del file del set di regole e il file EditorConfig come argomenti della riga di comando.

   Per esempio:

   Usage: RulesetToEditorconfigConverter.exe <%ruleset_file%> [<%path_to_editorconfig%>]
   

L'esempio seguente mostra un file del set di regole da convertire in un file EditorConfig:

<?xml version="1.0" encoding="utf-8"?>
<RuleSet Name="Rules for ConsoleApp" Description="Code analysis rules for ConsoleApp.csproj." ToolsVersion="16.0">
  <Rules AnalyzerId="Microsoft.Analyzers.ManagedCodeAnalysis" RuleNamespace="Microsoft.Rules.Managed">
    <Rule Id="CA1001" Action="Warning" />
    <Rule Id="CA1821" Action="Warning" />
    <Rule Id="CA2213" Action="Warning" />
    <Rule Id="CA2231" Action="Warning" />
  </Rules>
</RuleSet>

L'esempio seguente mostra il file EditorConfig risultante dopo la conversione:

# NOTE: Requires **VS2019 16.3** or later

# Rules for ConsoleApp
# Description: Code analysis rules for ConsoleApp.csproj.

# Code files
[*.{cs,vb}]

dotnet_diagnostic.CA1001.severity = warning
dotnet_diagnostic.CA1821.severity = warning
dotnet_diagnostic.CA2213.severity = warning
dotnet_diagnostic.CA2231.severity = warning

Configurare il codice generato

Gli analizzatori vengono eseguiti sui file di origine di un progetto e segnalano eventuali violazioni che trovano. Tuttavia, queste violazioni non sono utili per i file generati dal sistema. Esempi sono file di codice generati, ad esempio file di codice generati dalla finestra di progettazione, file di origine temporanei generati dal sistema di compilazione e così via. Per questi tipi di file, gli utenti non possono modificare manualmente i file e non sono preoccupati per la correzione di eventuali violazioni.

Pertanto, per impostazione predefinita, il driver analizzatore esamina solo i file con determinati nomi, estensioni di file o intestazioni di file generati automaticamente come file di codice generati. Ad esempio, un nome di file che termina con .designer.cs o .generated.cs viene considerato codice generato. Tuttavia, queste euristiche potrebbero non essere in grado di identificare tutti i file di codice generati personalizzati nel codice sorgente dell'utente.

In Visual Studio 2019 versione 16.5 e successive gli utenti finali possono configurare file e cartelle specifici da considerare come codice generato in un file EditorConfig.

Per aggiungere una configurazione di questo tipo, seguire questa procedura:

1. Se non si ha già un file EditorConfig per il progetto, aggiungerne uno.

2. Aggiungere l'elemento generated_code = true | false per file e cartelle specifici. Ad esempio, per trattare tutti i file il cui nome termina con .MyGenerated.cs come codice generato, usare questa voce:

   [*.MyGenerated.cs]
   generated_code = true
   

Eliminare le violazioni

È possibile eliminare le violazioni delle regole usando vari metodi. Per informazioni, vedere Eliminare le violazioni di analisi del codice.

Utilizzo della riga di comando

Quando si compila il progetto nella riga di comando, nell'output di compilazione vengono visualizzate violazioni delle regole se vengono soddisfatte le condizioni seguenti:

• Gli analizzatori vengono installati con .NET SDK o come pacchetto NuGet e non come estensione vsix .

  Per gli analizzatori installati con .NET SDK, potrebbe essere necessario abilitare gli analizzatori. Per gli stili di codice, è anche possibile applicare stili di codice alle compilazioni impostando una proprietà MSBuild.

• Una o più regole vengono violate nel codice del progetto.

• Il livello di gravità di una regola violata è impostato su un avviso, nel qual caso le violazioni non causano l'esito negativo della compilazione o l'errore, nel qual caso le violazioni causano l'esito negativo della compilazione.

Il livello di dettaglio dell'output di compilazione non influisce sulla visualizzazione delle violazioni delle regole. Anche con un livello di dettaglio minimo, le violazioni delle regole vengono visualizzate nell'output di compilazione.

Se si è abituati a eseguire l'analisi legacy dalla riga di comando, con FxCopCmd.exe o tramite msbuild con il RunCodeAnalysis flag, è possibile farlo con gli analizzatori del codice.

Per visualizzare le violazioni dell'analizzatore nella riga di comando quando si compila il progetto usando msbuild, eseguire un comando simile al seguente:

msbuild myproject.csproj /target:rebuild /verbosity:minimal

Il seguente screenshot mostra l'output della compilazione dal terminale di un progetto che include una violazione della regola di un analizzatore.

Progetti dipendenti

In un progetto .NET Core, se si aggiunge un riferimento a un progetto con analizzatori NuGet, Visual Studio aggiunge automaticamente tali analizzatori al progetto dipendente. Per disabilitare questo comportamento, ad esempio se il progetto dipendente è un progetto di unit test, contrassegnare il pacchetto NuGet come privato impostando l'attributo PrivateAssets nel file con estensione csproj o vbproj del progetto a cui si fa riferimento:

<PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="5.0.0" PrivateAssets="all" />

Contenuti correlati

• Panoramica degli analizzatori di codice in Visual Studio
• Inviare un bug dell'analizzatore del codice
• Usare i set di regole
• Eliminare le violazioni dell'analisi del codice
• Opzioni di configurazione per l'analisi del codice