Arquivos de configuração para regras de análise de código

As regras de análise de código têm várias opções de configuração. Especifique essas opções como pares chave-valor em um dos seguintes arquivos de configuração do analisador:

  • Arquivo EditorConfig: opções de configuração baseadas no arquivo ou na pasta.
  • Arquivo AnalyzerConfig global: opções de configuração do projeto. Útil quando alguns arquivos de projeto residem fora da pasta do projeto.

Dica

Você também pode definir propriedades de configuração de análise de código em seu arquivo de projeto. Essas propriedades configuram a análise de código em massa, desde a ativação ou desativação completa até a configuração na categoria. Para obter mais informações, confira EnableNETAnalyzers, AnalysisLevel, AnalysisLevel<Category> e AnalysisMode.

EditorConfig

Os arquivos EditorConfig são usados para fornecer opções que se aplicam a arquivos ou pastas de origem específicos. As opções são colocadas em cabeçalhos de seção para identificar os arquivos e pastas aplicáveis. Adicione uma entrada para cada regra que você deseja configurar e coloque-a na seção de extensão de arquivo correspondente, por exemplo: [*.cs].

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

No exemplo acima, [*.cs] é um cabeçalho da seção editorconfig para selecionar todos os arquivos C# com extensão de arquivo .cs na pasta atual, incluindo subpastas. A entrada seguinte,<option_name> = <option_value>, é uma opção de analisador que será aplicada a todos os arquivos C#.

Você pode aplicar as convenções de arquivo EditorConfig a uma pasta, a um projeto ou a um repositório inteiro, colocando o arquivo no diretório correspondente. Essas opções são aplicadas ao executar a análise no momento da compilação e ao editar o código no Visual Studio.

Observação

As opções EditorConfig aplicam-se apenas aos arquivos de origem de um projeto ou diretório. Os arquivos incluídos em um projeto como AdditionalFiles não são considerados arquivos de origem e as opções EditorConfig não são aplicadas a eles. Para aplicar uma opção de regra a arquivos que não são de origem, especifique a opção em um arquivo de configuração global.

Se você já tiver um arquivo .editorconfig para configurações do editor, como o tamanho do recuo ou se deseja cortar o espaço em branco à direita, poderá colocar suas opções de configuração de análise de código no mesmo arquivo.

Dica

O Visual Studio fornece um modelo de item .editorconfig que facilita a adição de um desses arquivos ao projeto. Para obter mais informações, confira Adicionar um arquivo EditorConfig a um projeto.

Exemplo

Veja a seguir um arquivo EditorConfig de exemplo para configurar opções e severidade da regra:

# 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 global

A partir do SDK do .NET 5 (com suporte no Visual Studio 2019 e posterior), você também pode configurar opções do analisador com os arquivos AnalyzerConfig globais. Esses arquivos são usados para fornecer opções que se aplicam a todos os arquivos de origem em um projeto, independentemente do nome ou do caminho do arquivo.

Ao contrário dos arquivos EditorConfig, os arquivos de configuração globais não podem ser usados para definir as configurações de estilo do editor para IDEs, como o tamanho do recuo ou a possibilidade de cortar o espaço em branco à direita. Em vez disso, eles são projetados puramente para especificar opções de configuração do analisador no projeto.

Formatar

Ao contrário dos arquivos EditorConfig, que devem ter cabeçalhos de seção, como [*.cs], para identificar os arquivos e pastas aplicáveis, os arquivos AnalyzerConfig globais não têm cabeçalhos de seção. Em vez disso, eles exigem uma entrada de nível superior do formulário is_global = true para diferenciá-los dos arquivos EditorConfig comuns. Isso indica que todas as opções no arquivo se aplicam ao projeto todo. Por exemplo:

is_global = true
<option_name> = <option_value>

Nomenclatura

Ao contrário dos arquivos EditorConfig, que devem receber o nome .editorconfig, os arquivos de configuração globais não precisam ter um nome ou extensão específico. No entanto, se você nomear esses arquivos como .globalconfig, eles serão aplicados implicitamente a todos os projetos C# e Visual Basic da pasta atual, incluindo subpastas. Caso contrário, você deverá adicionar explicitamente o item GlobalAnalyzerConfigFiles ao arquivo de projeto do MSBuild:

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

Considere as seguintes recomendações de nomenclatura:

  • Os usuários finais devem atribuir aos arquivos de configuração globais o nome .globalconfig.
  • Os criadores de pacotes NuGet devem atribuir aos arquivos de configuração globais o nome <%Package_Name%>.globalconfig.
  • Os arquivos de configuração globais gerados pela ferramenta MSBuild devem receber o nome <%Target_Name%>_Generated.globalconfig ou semelhante.

Observação

A entrada is_global = true de nível superior não é necessária quando o arquivo recebe o nome .globalconfig, mas é recomendável para dar mais clareza.

Distribuição em pacotes NuGet

Os arquivos Global AnalyzerConfig podem ser distribuídos com pacotes NuGet. Para fazer isso, adicione um arquivo .props ao pacote NuGet. No arquivo .props, adicione um item GlobalAnalyzerConfigFiles no nó Project:

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

Exemplo

Veja a seguir um exemplo de arquivo AnalyzerConfig global para configurar opções e severidade da regra no projeto:

# 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

Precedência

Os arquivos EditorConfig e os arquivos AnalyzerConfig globais especificam um par chave-valor para cada opção. Conflitos surgem quando há várias entradas com a mesma chave, mas valores diferentes. As regras de precedência a seguir são usadas para resolver conflitos.

Locais de entrada conflitantes Regra de precedência
No mesmo arquivo de configuração A entrada que aparece mais tarde no arquivo ganha. Isso é verdadeiro para entradas conflitantes em um único arquivo EditorConfig e em um único arquivo AnalyzerConfig global.
Em dois arquivos EditorConfig A entrada no arquivo EditorConfig mais profunda no sistema de arquivos e, portanto, tem um caminho de arquivo mais longo, ganha.
Em dois arquivos AnalyzerConfig globais .NET 5: um aviso do compilador é relatado e as duas entradas são ignoradas.
.NET 6 e versões posteriores: a entrada do arquivo com um valor maior para global_level tem precedência. Se global_level não for definido explicitamente e o arquivo for chamado de .globalconfig, o valor global_level será 100 por padrão; para todos os outros arquivos globais analyzerConfig, global_level será 0 por padrão. Se os valores de global_level dos arquivos de configuração com entradas conflitantes forem iguais, um aviso do compilador será relatado e ambas as entradas serão ignoradas.
Em um arquivo EditorConfig e um arquivo AnalyzerConfig global A entrada no arquivo EditorConfig ganha.

Opções de severidade

Para opções de configuração de severidade, as seguintes regras de precedência adicionais se aplicam:

Confira também