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 no nível em massa, desde ativar ou desativar completamente a análise de código até a configuração de regra no nível da 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 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.
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
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.
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.
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.
| 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:
As opções de severidade especificadas na linha de comando como opções do compilador (
-nowarnou-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.
