File di configurazione per le regole di analisi del codice

Le regole di analisi codice hanno diverse opzioni di configurazione. Queste opzioni vengono specificate come coppie chiave-valore in uno dei file di configurazione dell'analizzatore seguenti:

• File EditorConfig: opzioni di configurazione basate su file o su cartelle.
• File Global AnalyzerConfig: opzioni di configurazione a livello di progetto. Utile quando alcuni file di progetto si trovano all'esterno della cartella del progetto.

EditorConfig

I file EditorConfig vengono usati per fornire opzioni applicabili a file o cartelle di origine specifici. Le opzioni vengono inserite nelle intestazioni di sezione per identificare i file e le cartelle applicabili. Aggiungere una voce per ogni regola da configurare e inserirla nella sezione corrispondente dell'estensione di file, ad esempio [*.cs].

[*.cs]
<option_name> = <option_value>

Nell'esempio precedente, [*.cs] è un'intestazione di sezione editorconfig per selezionare tutti i file C# con estensione di file .cs all'interno della cartella corrente, incluse le sottocartelle. La voce successiva, <option_name> = <option_value>, è un'opzione dell'analizzatore che verrà applicata a tutti i file C#.

È possibile applicare convenzioni di file EditorConfig a una cartella, a un progetto o a un intero repository inserendo il file nella directory corrispondente. Queste opzioni vengono applicate durante l'esecuzione dell'analisi in fase di compilazione e durante la modifica del codice in Visual Studio.

Se si dispone di un file con estensione .editorconfig esistente per le impostazioni dell'editor, ad esempio le dimensioni del rientro o se tagliare gli spazi finali, è possibile inserire le opzioni di configurazione dell'analisi del codice nello stesso file.

Esempio

Di seguito è riportato un file di esempio EditorConfig per configurare le opzioni e la gravità della regola:

# Remove the line below if you want to inherit .editorconfig settings from higher directories
root = true

# C# files
[*.cs]

#### Core EditorConfig Options ####

# Indentation and spacing
indent_size = 4
indent_style = space
tab_width = 4

#### .NET Coding Conventions ####

# this. and Me. preferences
dotnet_style_qualification_for_method = true

#### Diagnostic configuration ####

# CA1000: Do not declare static members on generic types
dotnet_diagnostic.CA1000.severity = warning

AnalyzerConfig globale

È anche possibile configurare le opzioni dell'analizzatore con i file di AnalyzerConfig globali. Questi file vengono usati per fornire opzioni applicabili a tutti i file di origine in un progetto, indipendentemente dai relativi nomi di file o percorsi di file.

A differenza dei file EditorConfig, i file di configurazione globali non possono essere usati per configurare le impostazioni dello stile dell'editor per gli IDE, ad esempio le dimensioni del rientro o se tagliare gli spazi vuoti finali. Sono invece progettati esclusivamente per specificare le opzioni di configurazione dell'analizzatore a livello di progetto.

Formato

A differenza dei file EditorConfig, che devono avere intestazioni di sezione, ad esempio [*.cs], per identificare i file e le cartelle applicabili, i file AnalyzerConfig globali non hanno intestazioni di sezione. Richiedono invece una voce di primo livello del modulo is_global = true per distinguerle dai file EditorConfig normali. Ciò indica che tutte le opzioni nel file si applicano all'intero progetto. Ad esempio:

is_global = true
<option_name> = <option_value>

Denominazione

A differenza dei file EditorConfig, che devono essere denominati .editorconfig, i file di configurazione globale non devono avere un nome o un'estensione specifici. Tuttavia, se si denominano questi file come .globalconfig, vengono applicati in modo implicito a tutti i progetti C# e Visual Basic all'interno della cartella corrente, incluse le sottocartelle. In caso contrario, è necessario aggiungere in modo esplicito l'elemento GlobalAnalyzerConfigFiles al file di progetto MSBuild:

<ItemGroup>
  <GlobalAnalyzerConfigFiles Include="<path_to_global_analyzer_config>" />
</ItemGroup>

Considerare le seguenti raccomandazioni di denominazione:

• Gli utenti finali devono denominare i file di configurazione globali con estensione globalconfig.
• Gli autori di pacchetti NuGet devono denominare i file di configurazione globali <%Package_Name%>.globalconfig.
• I file di configurazione globali generati da MSBuild devono essere denominati <%Target_Name%>_Generated.globalconfig o in modo simile.

Inclusione condizionale

È possibile usare un file di configurazione globale per disabilitare o abilitare determinate regole di Code Analysis in ambienti diversi. Ad esempio, è possibile disabilitare alcune regole di Code Analysis per i progetti di unit test. A tale scopo, è possibile impostare la gravità delle regole applicabili su none nel file di configurazione, ad esempio:

# CA1861: Prefer 'static readonly' fields over constant array arguments
dotnet_diagnostic.CA1861.severity = none

È quindi possibile personalizzare la compilazione in modo da includere solo il file di configurazione nei progetti di test in base a condizioni specifiche della propria compilazione. Ad esempio:

<ItemGroup Condition="'$(IsShipping)' == 'false'">
  <!-- Include CodeAnalysis.test.globalconfig to override (relax) some rules from the primary configuration. -->
  <GlobalAnalyzerConfigFiles Include="$(MSBuildThisFileDirectory)CodeAnalysis.test.globalconfig" />
</ItemGroup>

Distribuzione nei pacchetti NuGet

I file Global AnalyzerConfig possono essere distribuiti con pacchetti NuGet. A tale scopo, aggiungere un file con estensione props al pacchetto NuGet. Nel file con estensione props aggiungere un elemento GlobalAnalyzerConfigFiles nel nodo Project:

<Project>
  <ItemGroup>
    <GlobalAnalyzerConfigFiles Include="Relative/Path/to/PackageName.globalconfig" />
  </ItemGroup>
</Project>

Esempio

Di seguito è riportato un esempio di file AnalyzerConfig globale per configurare le opzioni e la gravità della regola a livello di progetto:

# Top level entry required to mark this as a global AnalyzerConfig file
is_global = true

# NOTE: No section headers for configuration entries

#### .NET Coding Conventions ####

# this. and Me. preferences
dotnet_style_qualification_for_method = true:warning

#### Diagnostic configuration ####

# CA1000: Do not declare static members on generic types
dotnet_diagnostic.CA1000.severity = warning

Precedenza

Sia i file EditorConfig che i file AnalyzerConfig globali specificano una coppia chiave-valore per ogni opzione. I conflitti si verificano quando sono presenti più voci con la stessa chiave ma con valori diversi. Per risolvere i conflitti vengono usate le regole di precedenza seguenti.

Opzioni di gravità

Per le opzioni di configurazione della gravità, si applicano le regole di precedenza aggiuntive seguenti:

• Le opzioni di gravità specificate nella riga di comando come opzioni del compilatore (-nowarn o -warnaserror) sostituiscono sempre le opzioni di configurazione della gravità specificate in EditorConfig e nei file AnalyzerConfig globali.

• Le regole di precedenza per le voci di gravità in conflitto da un file del set di regole e unEditorConfig o un file AnalyzerConfig globale sono indefinite.

  I file del set di regole sono deprecati a favore dei file EditorConfig e AnalyzerConfig globali. È consigliabile convertire i file del set di regole in un file EditorConfig equivalente.

• Per informazioni sulle regole di precedenza per le opzioni di gravità correlate con chiavi diverse, ad esempio quando vengono specificate gravità diverse per una singola regola e per la categoria in cui rientra la regola, vedere Opzioni di configurazione per l'analisi codice.

Vedi anche

• Problema di progettazione di EditorConfig e AnalyzerConfig globale a confronto