Opções de configuração para análise de código

As regras de análise de código têm várias opções de configuração. Algumas dessas opções são especificadas como pares chave-valor em um arquivo de configuração do analisador usando a sintaxe <option key> = <option value>. Outras opções, que configuram a análise de código como um todo, estão disponíveis como propriedades do MSBuild em seu arquivo de projeto.

A opção mais comum que você configurará é a gravidade de uma regra. Você pode configurar o nível de gravidade para qualquer regra, incluindo regras de qualidade de código e regras de estilo de código. Por exemplo, para habilitar uma regra como um aviso, adicione o seguinte par chave-valor a um arquivo de configuração do analisador:

dotnet_diagnostic.<rule ID>.severity = warning

Você também pode configurar opções adicionais para personalizar o comportamento da regra:

• As regras de qualidade de código têm opções de comportamento, como a quais nomes de método uma regra deve se aplicar.
• As regras de estilo de código têm opções de preferência de estilo, como onde novas linhas são desejáveis.
• As regras do analisador de terceiros podem definir suas próprias opções de configuração, com nomes de chave e formatos de valor personalizados.

Opções gerais

Essas opções se aplicam à análise de código como um todo. Não podem ser aplicadas apenas a uma regra específica.

• Modo de análise
• Habilitar análise de código
• Excluir código gerado

Para obter opções adicionais, consulte Propriedades de análise de código.

Modo de análise

Embora o SDK do .NET inclua todas as regras de análise de código, apenas algumas delas são habilitadas por padrão. O modo de análise determina qual, se houver, conjunto de regras a habilitar. Você pode escolher um modo de análise mais agressivo onde a maioria ou todas as regras estão habilitadas. Ou você pode escolher um modo de análise mais conservador, onde a maioria ou todas as regras são desativadas e, em seguida, você pode optar por regras específicas, conforme necessário. Defina o modo de análise adicionando a <propriedade AnalysisMode MSBuild ao arquivo de> projeto.

<PropertyGroup>
  <AnalysisMode>Recommended</AnalysisMode>
</PropertyGroup>

A partir do .NET 6, você também pode habilitar em massa uma categoria de regras usando a <propriedade AnalysisMode<Category>> MSBuild.

Nota

Se você configurar a análise de código usando propriedades do MSBuild, como AnalysisMode, todas as opções de configuração em massa definidas no arquivo de configuração serão ignoradas. Por exemplo, se você tiver ativado em massa todas as regras ou uma categoria de regras em um arquivo .editorconfig , essa configuração será ignorada.

Habilitar análise de código

A análise de código é habilitada por padrão para projetos destinados ao .NET 5 e versões posteriores. Se você tiver o SDK do .NET 5+, mas seu projeto tiver como alvo uma implementação .NET diferente, poderá habilitar manualmente a análise de código definindo a propriedade EnableNETAnalyzers no arquivo de projeto como true.

<PropertyGroup>
  <EnableNETAnalyzers>true</EnableNETAnalyzers>
</PropertyGroup>

Excluir código gerado

Os avisos do analisador de código .NET não são úteis em arquivos de código gerados, como arquivos gerados pelo designer, que os usuários não podem editar para corrigir violações. Na maioria dos casos, os analisadores de código ignoram os arquivos de código gerados e não relatam violações nesses arquivos.

Por padrão, arquivos com determinadas extensões de arquivo ou cabeçalhos de arquivo gerados automaticamente são tratados como arquivos de código gerados. Por exemplo, um nome de arquivo que termina com .designer.cs ou .generated.cs é considerado código gerado. Esta opção de configuração permite especificar padrões de nomenclatura adicionais a serem tratados como código gerado. Você configura arquivos e pastas adicionais adicionando uma generated_code = true | false entrada ao seu arquivo de configuração. Por exemplo, para tratar todos os arquivos cujo nome termina com .MyGenerated.cs como código gerado, adicione a seguinte entrada:

[*.MyGenerated.cs]
generated_code = true

Opções específicas da regra

As opções específicas da regra podem ser aplicadas a uma única regra, a um conjunto de regras ou a todas as regras. As opções específicas da regra incluem:

• Nível de severidade da regra
• Opções específicas para regras de qualidade de código

Nível de gravidade

A tabela a seguir mostra as diferentes severidades de regras que você pode configurar para todas as regras do analisador, incluindo regras de qualidade e estilo de código.

Valor de configuração de severidade	Comportamento em tempo de construção
error	As violações aparecem como erros de compilação e fazem com que as compilações falhem.
warning	As violações aparecem como avisos de compilação , mas não fazem com que as compilações falhem (a menos que você tenha uma opção definida para tratar avisos como erros).
suggestion	As violações aparecem como mensagens de compilação e como sugestões no IDE do Visual Studio. (No Visual Studio, as sugestões aparecem como três pontos cinzas sob os dois primeiros caracteres.)
silent	As violações não são visíveis para o usuário. No entanto, para regras de estilo de código, os recursos de geração de código do Visual Studio ainda geram código nesse estilo. Essas regras também participam da limpeza e aparecem no menu Ações Rápidas e Refatorações no Visual Studio.
none	A regra é completamente suprimida. No entanto, para regras de estilo de código, os recursos de geração de código do Visual Studio ainda geram código nesse estilo.
default	A severidade padrão da regra é usada. As gravidades padrão para cada versão do .NET estão listadas no repositório roslyn-analyzers. Nessa tabela, "Desativado" corresponde a none, "Oculto" corresponde a silent, e "Info" corresponde a suggestion.

Âmbito

• Regra única

  Para definir a severidade da regra para uma única regra, use a sintaxe a seguir.

  dotnet_diagnostic.<rule ID>.severity = <severity value>
  

• Categoria de regras

  Para definir a severidade da regra padrão para uma categoria de regras, use a sintaxe a seguir. No entanto, essa configuração de gravidade afeta apenas as regras nessa categoria habilitadas por padrão.

  dotnet_analyzer_diagnostic.category-<rule category>.severity = <severity value>
  

  As diferentes categorias são listadas e descritas em Categorias de regras. Além disso, você pode encontrar a categoria para uma regra específica em sua página de referência, por exemplo, CA1000.

• Todas as regras

  Para definir a severidade da regra padrão para todas as regras do analisador, use a sintaxe a seguir. No entanto, essa configuração de gravidade afeta apenas as regras habilitadas por padrão.

  dotnet_analyzer_diagnostic.severity = <severity value>
  

Importante

Quando você configura o nível de severidade para várias regras com uma única entrada, seja para uma categoria de regras ou para todas as regras, a severidade só se aplica a regras habilitadas por padrão. E se você habilitar todas as regras usando as propriedades <do MSBuild AnalysisMode ou <AnalysisLevel>, todas as opções em> massa dotnet_analyzer_diagnostic serão ignoradas. Por esse motivo, é melhor habilitar uma categoria de regras definindo AnalysisMode<Category>> como All.<

Nota

O prefixo para definir a severidade para uma única regra, dotnet_diagnostic, é ligeiramente diferente do prefixo para configurar a severidade via categoria ou para todas as regras, dotnet_analyzer_diagnostic.

Precedência

Se você tiver várias entradas de configuração de severidade que possam ser aplicadas à mesma ID de regra, a precedência será escolhida na seguinte ordem:

• Uma entrada para uma categoria tem precedência sobre uma entrada para todas as regras do analisador.
• Uma entrada para uma regra individual por ID tem precedência sobre uma entrada para uma categoria.

Considere o exemplo a seguir, onde CA1822 tem a categoria "Desempenho":

[*.cs]
dotnet_diagnostic.CA1822.severity = error
dotnet_analyzer_diagnostic.category-performance.severity = warning
dotnet_analyzer_diagnostic.severity = suggestion

No exemplo anterior, todas as três entradas de gravidade são aplicáveis ao CA1822. No entanto, usando as regras de precedência especificadas, a primeira entrada baseada em ID de regra vence as próximas entradas. Neste exemplo, CA1822 terá uma severidade efetiva de error. Todas as outras regras dentro da categoria "Desempenho" terão uma severidade de warning.

Para obter informações sobre como a precedência entre arquivos é decidida, consulte a seção Precedência do artigo Arquivos de configuração.