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

  • Artigo

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 no arquivo de projeto.

A opção mais comum que você vai 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, por exemplo, os nomes de métodos aos quais uma regra deve se aplicar.
  • As regras de estilo de código têm opções de preferências de estilo, por exemplo, quando novas linhas são recomendáveis.
  • As regras de analisador de terceiros podem definir as próprias opções de configuração, com nomes de chave personalizados e formatos de valor.

Opções gerais

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

Para opções adicionais, confira 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 estão habilitadas por padrão. O modo de análise determina o conjunto de regras que deve ser habilitado, se houver. Você pode escolher um modo de análise mais agressivo, em que a maioria ou todas as regras estão habilitadas. Ou, então, você pode escolher um modo de análise mais conservador, em que a maioria ou todas as regras estão desabilitadas e, em seguida, aceitar regras específicas, conforme necessário. Defina o modo de análise adicionando a propriedade <AnalysisMode> do 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>> do MSBuild.

Observação

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 habilitado em massa todas as regras ou uma categoria de regras em um arquivo .editorconfig, essa configuração será ignorada.

Habilitar a análise de código

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

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

Excluir código gerado

Os avisos do analisador de código do .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 nenhuma violação. Na maioria dos casos, os analisadores de código ignoram 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. Essa opção de configuração permite que você especifique padrões de nomenclatura adicionais a serem tratados como código gerado. Configure arquivos e pastas adicionais adicionando uma entrada generated_code = true | false ao 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 de regra

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

Nível de severidade

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

Valor da configuração de gravidade Comportamento em tempo de compilação
error As violações aparecem como erros e causam falha nos builds.
warning As violações aparecem como avisos de build, mas não fazem com que os builds falhem (a menos que você tenha uma opção definida para tratar avisos como erros).
suggestion As violações aparecem como mensagens de build e como sugestões no IDE do Visual Studio. (No Visual Studio, as sugestões aparecem como três pontos cinzas nos 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 foi 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 gravidade padrão da regra é usada. As gravidades padrão para cada versão do .NET são listadas no repositório de analisadores roslyn. Nessa tabela, "Desabilitado" corresponde a none, "Oculto" corresponde a silent e "Informações" corresponde a suggestion.

Escopo

  • Regra única

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

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

  • Categoria de regras

    Para definir a gravidade 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 regra. 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 gravidade 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 gravidade para várias regras com uma só entrada, seja para uma categoria de regras ou para todas as regras, a gravidade se aplica apenas às regras habilitadas por padrão. Se você habilitar todas as regras usando as propriedades <AnalysisMode> ou <AnalysisLevel> do MSBuild, todas as opções dotnet_analyzer_diagnostic em massa serão ignoradas. Por esse motivo, é melhor habilitar uma categoria de regras definindo <AnalysisMode<Category>> como All.

Observação

O prefixo para definir a gravidade de uma só regra, dotnet_diagnostic, é levemente diferente do prefixo para configurar a gravidade por meio de categoria ou para todas as regras, dotnet_analyzer_diagnostic.

Precedência

Se você tiver várias entradas de configuração de gravidade que podem 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 seguinte exemplo, em que 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 a CA1822. No entanto, usando as regras de precedência especificadas, a primeira entrada baseada em ID de regra vence nas próximas entradas. Neste exemplo, CA1822 terá uma gravidade efetiva de error. Todas as outras regras dentro da categoria "Desempenho" terão uma gravidade de warning.

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