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.

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 editorconfig cabeçalho da seção para selecionar todos os arquivos C# com extensão de arquivo .cs dentro da 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.

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.

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

Você também pode configurar as opções do analisador com arquivos do 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.

Inclusão condicional

Você pode usar um arquivo de configuração global para desabilitar ou habilitar determinadas regras de análise de código em ambientes diferentes. Por exemplo, talvez você queira desabilitar algumas regras de análise de código para projetos de teste de unidade. Para fazer isso, você pode definir a gravidade das regras aplicáveis para none no arquivo de configuração, por exemplo:

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

Em seguida, você pode personalizar seu build para incluir apenas o arquivo de configuração em projetos de teste com base em condições específicas ao seu build. Por exemplo:

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

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.

Opções de severidade

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

• As opções de severidade especificadas na linha de comando como opções do compilador (-nowarn ou -warnaserror) sempre substituem as opções de configuração de severidade especificadas nos arquivos EditorConfig e AnalyzerConfig global.

• As regras de precedência para entradas de severidade conflitantes de um arquivo de conjunto de regras e um arquivo EditorConfig ou AnalyzerConfig global são indefinidas.

  Os arquivos de conjunto de regras são preteridos em favor dos arquivos EditorConfig e AnalyzerConfig global. Recomendamos converter arquivos de conjunto de regras em um arquivo EditorConfig equivalente.

• Para obter informações sobre regras de precedência para opções de severidade relacionadas com chaves diferentes, por exemplo, quando diferentes severidades são especificadas para uma única regra e para a categoria em que a regra se enquadra, confira Opções de configuração para análise de código.

Confira também

• Problema de design do EditorConfig x AnalyzerConfig global