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. Você especifica essas opções como pares chave-valor em um dos seguintes arquivos de configuração do analisador:

• EditorConfig file: opções de configuração baseadas em arquivo ou em pasta.
• Arquivo Global AnalyzerConfig : opções de configuração no nível do projeto. Útil quando alguns arquivos de projeto residem fora da pasta do projeto.

EditorConfig

EditorConfig Os arquivos são usados para fornecer opções que se aplicam a arquivos ou pastas de origem específicos. As opções são colocadas sob 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 de editorconfig seção para selecionar todos os arquivos C# com .cs extensão de arquivo dentro da pasta atual, incluindo subpastas. A entrada subsequente, <option_name> = <option_value>, é uma opção de analisador que será aplicada a todos os arquivos C#.

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

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

Exemplo

A seguir está um arquivo de exemplo EditorConfig para configurar opções e gravidade 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

Global AnalyzerConfig

Você também pode configurar opções do analisador com arquivos globais AnalyzerConfig . Esses arquivos são usados para fornecer opções que se aplicam a todos os arquivos de origem em um projeto, independentemente de seus nomes de arquivo ou caminhos de arquivo.

Ao contrário EditorConfig dos arquivos, os arquivos de configuração global não podem ser usados para definir configurações de estilo de editor para IDEs, como o tamanho do recuo ou se o espaço em branco deve ser cortado à direita. Em vez disso, eles são projetados exclusivamente para especificar opções de configuração do analisador no nível do projeto.

Formato

Ao contrário EditorConfig dos arquivos, que devem ter cabeçalhos de seção, como [*.cs], para identificar os arquivos e pastas aplicáveis, os arquivos globais do AnalyzerConfig 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 regulares EditorConfig . Isso indica que todas as opções no arquivo se aplicam a todo o projeto. Por exemplo:

is_global = true
<option_name> = <option_value>

Atribuição de nomes

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

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

Considere as seguintes recomendações de nomenclatura:

• Os usuários finais devem nomear seus arquivos de configuração global como .globalconfig.
• Os criadores de pacotes NuGet devem nomear seus arquivos <de configuração global como %Package_Name%>.globalconfig.
• Os arquivos de configuração global gerados por ferramentas do MSBuild devem ser nomeados <%Target_Name%>_Generated.globalconfig ou similar.

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 severidade das regras aplicáveis no none 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 sua compilação para incluir apenas o arquivo de configuração em projetos de teste com base em condições específicas para sua compilação. 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 GlobalAnalyzerConfigFiles item sob o Project nó:

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

Exemplo

A seguir está um exemplo de arquivo AnalyzerConfig global para configurar opções e gravidade da regra no nível do 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

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

Opções de gravidade

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

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

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

  Os arquivos do conjunto de regras são preteridos em favor dos EditorConfig arquivos AnalyzerConfig globais. Recomendamos que você converta arquivos de conjunto de regras em um arquivo equivalenteEditorConfig.

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

Consulte também

• EditorConfig vs problema de design global do AnalyzerConfig