File di configurazione per le regole di analisi del codice

  • Articolo

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.

Suggerimento

È anche possibile impostare le proprietà di configurazione dell'analisi del codice nel file di progetto. Queste proprietà configurano l'analisi del codice a livello di blocco, dall'attivazione o disattivazione completa alla configurazione a livello di categoria. Per altre informazioni, vedere EnableNETAnalyzers, AnalysisLevel, AnalysisLevel<Category> e AnalysisMode.

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.

Nota

Le opzioni EditorConfig si applicano solo ai file di origine in un progetto o in una directory. I file inclusi in un progetto come AdditionalFiles non sono considerati file di origine e le opzioni EditorConfig non vengono applicate a questi file. Per applicare un'opzione di regola ai file non di origine, specificare l'opzione in un file di configurazione globale.

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.

Suggerimento

Visual Studio offre un modello di elemento con estensione editorconfig che semplifica l'aggiunta di uno di questi file al progetto. Per altre informazioni, vedere Aggiungere un file EditorConfig a un progetto.

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

A partire da .NET 5 SDK (supportato in Visual Studio 2019 e versioni successive), è anche possibile configurare le opzioni dell'analizzatore con i file 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, questi 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.

Nota

La voce is_global = true di primo livello non è necessaria quando il file è denominato .globalconfig, ma è consigliabile usarla per maggiore chiarezza.

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.

Posizioni di immissione in conflitto Regola di precedenza
Nello stesso file di configurazione La voce visualizzata più avanti nel file ha priorità. Questo vale per le voci in conflitto all'interno di un singolo file EditorConfig e anche all'interno di un singolo file AnalyzerConfig globale.
In due file EditorConfig La voce nel file EditorConfig si trova più a fondo nel file system e quindi ha un percorso di file più lungo, pertanto prevale.
In due file AnalyzerConfig globali .NET 5: viene segnalato un avviso del compilatore ed entrambe le voci vengono ignorate.
.NET 6 e versioni successive: la voce del file con un valore superiore per global_level ha la precedenza. Se global_level non è definito in modo esplicito e il file è denominato .globalconfig, il valore predefinito global_level è 100; per tutti gli altri file AnalyzerConfig globali, per impostazione predefinita global_level è 0. Se i valori global_level per i file di configurazione con voci in conflitto sono uguali, viene segnalato un avviso del compilatore ed entrambe le voci vengono ignorate.
In un file EditorConfig e in un file Global AnalyzerConfig Prevale la voce nel file EditorConfig.

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