Partilhar via

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

  • Artigo

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.

Gorjeta

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 no nível em massa, desde ativar ou desativar completamente a análise de código até a configuração de regras no nível da categoria. Para obter mais informações, consulte EnableNETAnalyzers, AnalysisLevel, AnalysisLevel<Category> e AnalysisMode.

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 seção editorconfig 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.

Nota

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

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, poderá colocar as opções de configuração de análise de código no mesmo arquivo.

Gorjeta

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

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.

Nota

A entrada is_global = true de nível superior não é necessária quando o arquivo é nomeado .globalconfig, mas é recomendada para maior clareza.

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. -->
  <EditorConfigFiles 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.

Locais de entrada conflitantes Regra de precedência
No mesmo arquivo de configuração A entrada que aparece posteriormente no arquivo vence. Isso é verdadeiro para entradas conflitantes dentro de um único EditorConfig arquivo e também dentro de um único arquivo global AnalyzerConfig.
Em dois EditorConfig ficheiros A entrada no EditorConfig arquivo que é mais profunda no sistema de arquivos e, portanto, tem um caminho de arquivo mais longo, ganha.
Em dois arquivos globais AnalyzerConfig .NET 5: Um aviso do compilador é relatado e ambas as entradas são ignoradas.
.NET 6 e versões posteriores: A entrada do arquivo com um valor mais alto para global_level tem precedência. Se global_level não estiver explicitamente definido e o arquivo for chamado .globalconfig, o valor padrão será 100; para todos os outros arquivos globais do AnalyzerConfig, global_level o global_level padrão será 0. Se os global_level valores 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 EditorConfig arquivo e um arquivo Global AnalyzerConfig A entrada no EditorConfig arquivo vence.

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