Personalizar regras do analisador Roslyn

Cada regra do analisador Roslyn, ou diagnóstico, tem um estado padrão de severidade e supressão que você pode personalizar para seu projeto. Este artigo aborda a definição de severidades do analisador e a supressão de violações do analisador.

Níveis de severidade

A tabela a seguir mostra as diferentes opções de severidade que você pode configurar para um diagnóstico:

Exibir violações de regra

Se um analisador encontrar violações de regra do analisador, ele as relatará na janela Lista de Erros e no editor de código.

A captura de tela a seguir mostra as violações de regra relatadas na janela Lista de Erros . As violações do analisador relatadas na lista de erros correspondem à configuração do nível de gravidade da regra:

As violações de regras do analisador também aparecem no editor de código como linhas onduladas sob o trecho de código incorreto. Por exemplo, a captura de tela a seguir mostra três violações: um erro (linha de rabiscos vermelho), um aviso (linha de rabiscos verde) e uma sugestão (três pontos cinzas):

Muitos diagnósticos têm uma ou mais correções de código associadas que você pode aplicar para corrigir a violação de regra. As correções de código são mostradas no menu ícone de lâmpada junto com outros tipos de Ações Rápidas. Para obter mais informações sobre correções de código, consulte Ações Rápidas Comuns.

Configurar níveis de severidade

Você pode definir a gravidade da regra usando qualquer um dos seguintes métodos:

Severidade silenciosa vs. Nenhuma gravidade

Silent As regras de severidade habilitadas por padrão diferem das regras de severidade desabilitadas ou None:

• Se uma correção de código for registrada para uma Silent regra de severidade, o Visual Studio oferecerá a correção de código como uma ação de refatoração de código de lâmpada, mesmo que o diagnóstico oculto não esteja visível para o usuário. Se a regra de severidade estiver desabilitada como None, a correção de código não será oferecida.
• As entradas que definem a gravidade de várias regras do analisador ao mesmo tempo em um arquivo EditorConfig podem configurar Silent regras de severidade em massa. None as regras de severidade não podem ser configuradas dessa maneira. Em vez disso, eles devem ser configurados por meio de entradas que definem a severidade em um arquivo EditorConfig para cada ID de regra.

Definir a gravidade da regra em um arquivo EditorConfig

Os arquivos EditorConfig estão disponíveis no Visual Studio 2019 versão 16.3 e posterior.

Definir a gravidade de uma regra em um arquivo EditorConfig tem precedência sobre qualquer severidade definida em um conjunto de regras ou no Gerenciador de Soluções. Você pode configurar a gravidade manualmente em um arquivo EditorConfig ou automaticamente por meio da lâmpada que aparece ao lado de uma violação.

Configurar manualmente a gravidade da regra em um arquivo EditorConfig

Para configurar a gravidade da regra, siga estas etapas:

1. Adicione um arquivo EditorConfig ao seu projeto, se você ainda não tiver um.

2. Adicione uma entrada para cada regra que você deseja configurar na extensão de arquivo correspondente.

   Por exemplo, a entrada para definir a gravidade de CA1822 como error em arquivos C# é a seguinte:

   [*.cs]
   dotnet_diagnostic.CA1822.severity = error
   

3. Você pode definir a gravidade da regra para cada ID de regra de diagnóstico em um arquivo EditorConfig com a seguinte sintaxe:

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

4. Para analisadores de estilo de código IDE, você também pode configurá-los em um arquivo EditorConfig usando uma sintaxe diferente.

   Por exemplo, dotnet_style_qualification_for_field = false:suggestion. No entanto, se você definir uma severidade usando a dotnet_diagnostic sintaxe, ela terá precedência. Para obter mais informações, consulte convenções de idioma para EditorConfig.

Definir a gravidade de várias regras do analisador ao mesmo tempo em um arquivo EditorConfig

A capacidade de definir várias regras do analisador ao mesmo tempo em um arquivo EditorConfig está disponível no Visual Studio 2019 versão 16.5 e posterior.

Você pode definir a gravidade para uma categoria específica de regras do analisador ou para todas as regras do analisador com uma única entrada em um arquivo EditorConfig:

• Defina a gravidade da regra para uma categoria de regras do analisador:

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

• Defina a gravidade da regra para todas as regras do analisador:

  dotnet_analyzer_diagnostic.severity = <severity>

As entradas que configuram várias regras do analisador de uma só vez se aplicam apenas às regras habilitadas por padrão. As regras do analisador marcadas como desabilitadas por padrão no pacote do analisador devem ser habilitadas por meio de entradas explícitas dotnet_diagnostic.<rule ID>.severity = <severity> .

Se você tiver várias entradas aplicáveis a uma ID de regra específica, a ordem de precedência para a entrada aplicável será a seguinte:

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

Considere o seguinte exemplo de EditorConfig, em que CA1822 é uma regra de desempenho:

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

Neste exemplo, todas as três entradas se aplicam à regra de desempenho CA1822. No entanto, usando as regras de precedência especificadas, a primeira entrada de severidade baseada em ID de regra tem precedência sobre as próximas entradas. Neste exemplo, CA1822 tem uma severidade efetiva de error. As regras de desempenho restantes têm uma severidade de warning. As regras do analisador que não são regras de desempenho têm uma gravidade de suggestion.

Defina a severidade da regra a partir do menu da lâmpada

O Visual Studio fornece uma maneira conveniente de configurar a gravidade de uma regra no menu de Ações Rápidas. Siga estas etapas:

1. Depois que ocorrer uma violação, passe o mouse sobre a linha de alternância de violação no editor e escolha Mostrar possíveis correções para abrir o menu de lâmpada. Ou coloque o cursor na linha e pressione Ctrl+. (ponto).

2. No menu de lâmpada, passe o mouse sobre um nível de severidade para uma visualização da alteração e configure a gravidade de acordo com as seguintes opções:

   • Configurar a gravidade da regra com ID <>. Defina a gravidade da regra específica.

   • Configure a severidade para todos os <analisadores de estilo> . Defina a gravidade de todas as regras na categoria de regra específica.

   • Configurar gravidade para todos os analisadores. Defina a gravidade para todas as categorias de regras do analisador.

     No exemplo a seguir, selecione Suprimir ou configurar problemas>Configurar <gravidade da ID> da regra.

     

3. Escolha uma das opções de severidade.

   

   O Visual Studio adiciona uma entrada ao arquivo EditorConfig para configurar a regra para o nível de severidade solicitado, conforme mostrado na caixa de visualização.

   Se você ainda não tiver um arquivo EditorConfig no projeto, o Visual Studio criará um para você.

Definir a gravidade da regra do Gerenciador de Soluções

Para definir a gravidade da regra do Gerenciador de Soluções, siga estas etapas:

1. No Explorador de Soluções, expanda Referências>Analisadores (ou Dependências>Analisadores para projetos do .NET Core).

2. Expanda o conjunto que contém a regra para a qual você deseja definir a severidade.

3. Clique com o botão direito do mouse na regra e selecione Definir severidade. No menu de contexto, escolha uma das opções de severidade.

   O Visual Studio adiciona uma entrada ao arquivo EditorConfig para configurar a regra para o nível solicitado. Se o projeto usar um arquivo de conjunto de regras em vez de um arquivo EditorConfig, a entrada de severidade será adicionada ao arquivo de conjunto de regras.

   Se você ainda não tiver um arquivo EditorConfig ou um arquivo de conjunto de regras no projeto, o Visual Studio criará um novo arquivo EditorConfig para você.

Exibir analisadores e diagnósticos do Gerenciador de Soluções

Você pode fazer grande parte da personalização do diagnóstico do analisador do Gerenciador de Soluções. Se você instalar um analisador como um pacote NuGet, um nó Analisadores aparecerá no nó Referências (ou no nó Dependências para projetos do .NET Core) no Gerenciador de Soluções. Siga estas etapas para exibir os analisadores e os diagnósticos:

1. No Gerenciador de Soluções, expanda seu projeto, expanda Referências ou Dependências e expanda Analisadores. Expanda um dos conjuntos do analisador para ver os diagnósticos no conjunto.

   O ícone ao lado de cada diagnóstico indica seu nível de gravidade:

   • x em um círculo indica uma severidade de Erro
   • ! em um triângulo indica um nível de severidade de Aviso
   • i em um círculo sólido indica uma severidade da Sugestão
   • i em um círculo pontilhado indica uma severidade de Silent
   • Seta apontando para baixo em um círculo sólido indica uma gravidade de None

   

2. Para exibir as propriedades de um diagnóstico, incluindo sua descrição e gravidade padrão, clique com o botão direito do mouse no diagnóstico e selecione Propriedades. Ou selecione o diagnóstico e pressione Alt+Enter.

   A janela Propriedades é exibida.

   

3. Para exibir propriedades para regras de estilo de código (prefixo IDE) na janela Propriedades , como severidade padrão, defina a propriedade EnforceCodeStyleInBuild como true.

4. Para obter a documentação online de um diagnóstico, clique com o botão direito do mouse no diagnóstico e selecione Exibir Ajuda.

Converter um arquivo de conjunto de regras existente em um arquivo EditorConfig

No Visual Studio 2019 versão 16.5 e posterior, os arquivos de conjunto de regras são preteridos em favor dos arquivos EditorConfig para a configuração do analisador para código gerenciado. Os arquivos EditorConfig são mais flexíveis e permitem que você configure as severidades de regra do analisador e as opções do analisador, incluindo opções de estilo de código do IDE do Visual Studio. Como as ferramentas do Visual Studio para a configuração de severidade de regras do analisador agora são otimizadas para funcionar com arquivos EditorConfig em vez de arquivos de conjunto de regras, você é incentivado a converter todos os projetos existentes que ainda usam arquivos de conjunto de regras.

Ao converter o arquivo de conjunto de regras existente em um arquivo EditorConfig, salve-o na raiz do repositório ou na pasta da solução. Isso garante que as configurações de severidade desse arquivo se apliquem automaticamente a todo o repositório ou solução, respectivamente.

Você pode converter um arquivo de conjunto de regras existente em um arquivo EditorConfig usando o editor de conjunto de regras ou a linha de comando.

Para usar o editor de conjunto de regras, siga estas etapas. Se o projeto já usar um arquivo específico de conjunto de regras para o valor de propriedade CodeAnalysisRuleSet, você pode convertê-lo em um arquivo EditorConfig equivalente no editor de conjunto de regras:

1. Clique duas vezes no arquivo de conjunto de regras no Gerenciador de Soluções.

   O arquivo de conjunto de regras é aberto no editor do conjunto de regras com uma barra de informações clicável na parte superior.

   

2. Selecione o link da barra de informações para migrar o arquivo do editor do conjunto de regras.

3. Na caixa de diálogo Salvar como , selecione o diretório onde você deseja gerar o arquivo EditorConfig e, em seguida, selecione Salvar.

   O EditorConfig gerado é aberto no editor. Além disso, a propriedade CodeAnalysisRuleSet MSBuild é atualizada no arquivo de projeto para que ela não faça mais referência ao arquivo de conjunto de regras original.

   O arquivo de conjunto de regras original pode ser removido do projeto.

   Observação

   Em um projeto do .NET Framework, o arquivo de conjunto de regras padrão não pode ser migrado ou removido do projeto.

Para usar a linha de comando, siga estas etapas:

1. Instale o pacote NuGet Microsoft.CodeAnalysis.RulesetToEditorconfigConverter.

2. Execute RulesetToEditorconfigConverter.exe do pacote instalado, com caminhos para o arquivo de conjunto de regras e o arquivo EditorConfig como argumentos de linha de comando.

   Por exemplo:

   Usage: RulesetToEditorconfigConverter.exe <%ruleset_file%> [<%path_to_editorconfig%>]
   

O exemplo a seguir mostra um arquivo de conjunto de regras a ser convertido em um arquivo EditorConfig:

<?xml version="1.0" encoding="utf-8"?>
<RuleSet Name="Rules for ConsoleApp" Description="Code analysis rules for ConsoleApp.csproj." ToolsVersion="16.0">
  <Rules AnalyzerId="Microsoft.Analyzers.ManagedCodeAnalysis" RuleNamespace="Microsoft.Rules.Managed">
    <Rule Id="CA1001" Action="Warning" />
    <Rule Id="CA1821" Action="Warning" />
    <Rule Id="CA2213" Action="Warning" />
    <Rule Id="CA2231" Action="Warning" />
  </Rules>
</RuleSet>

O exemplo a seguir mostra o arquivo EditorConfig resultante após a conversão:

# NOTE: Requires **VS2019 16.3** or later

# Rules for ConsoleApp
# Description: Code analysis rules for ConsoleApp.csproj.

# Code files
[*.{cs,vb}]

dotnet_diagnostic.CA1001.severity = warning
dotnet_diagnostic.CA1821.severity = warning
dotnet_diagnostic.CA2213.severity = warning
dotnet_diagnostic.CA2231.severity = warning

Configurar código gerado

Os analisadores rodam em arquivos de origem de um projeto e relatam quaisquer violações que encontrarem. No entanto, essas violações não são úteis para arquivos gerados pelo sistema. Exemplos são arquivos de código gerados, como arquivos de código gerados pelo designer, arquivos de origem temporários gerados pelo sistema de build e assim por diante. Para esses tipos de arquivos, os usuários não podem editar manualmente os arquivos e não estão preocupados em corrigir nenhuma violação.

Portanto, por padrão, o driver do analisador examina apenas arquivos com determinados nomes, extensões de arquivo ou cabeçalhos de arquivo gerados automaticamente como arquivos de código gerados. Por exemplo, um nome de arquivo que termina com .designer.cs ou .generated.cs é considerado código gerado. No entanto, essas heurísticas podem não ser capazes de identificar todos os arquivos de código gerados personalizados no código-fonte do usuário.

No Visual Studio 2019 versão 16.5 e posterior, os usuários finais podem configurar arquivos e pastas específicos para serem tratados como código gerado em um arquivo EditorConfig.

Para adicionar essa configuração, siga estas etapas:

1. Se você ainda não tiver um arquivo EditorConfig para seu projeto, adicione um.

2. Adicione a generated_code = true | false entrada para arquivos e pastas específicos. Por exemplo, para tratar todos os arquivos cujo nome termina .MyGenerated.cs como código gerado, use esta entrada:

   [*.MyGenerated.cs]
   generated_code = true
   

Suprimir violações

Você pode suprimir violações de regra usando vários métodos. Para obter informações, consulte Suprimir violações de análise de código.

Uso de linha de comando

Quando você cria seu projeto na linha de comando, as violações de regra aparecem na saída do build se as seguintes condições forem atendidas:

• Os analisadores são instalados com o SDK do .NET ou como um pacote NuGet e não como uma extensão .vsix .

  Para analisadores instalados usando o SDK do .NET, talvez seja necessário habilitar os analisadores. Para estilos de código, você também pode impor estilos de código em builds definindo uma propriedade MSBuild.

• Uma ou mais regras são violadas no código do projeto.

• O nível de severidade de uma regra violada é definido como aviso, caso em que as violações não fazem com que o build falhe ou erro, caso em que as violações fazem com que o build falhe.

A verbosidade da saída do build não afeta se as violações de regras são exibidas. Mesmo com a verbosidade silenciosa , as violações de regra aparecem na saída de build.

Se você estiver acostumado a executar análises de legado no prompt de comando, seja com FxCopCmd.exe ou por meio do msbuild utilizando o RunCodeAnalysis sinalizador, poderá substituir essa abordagem por analisadores de código.

Para ver as violações do analisador na linha de comando ao criar seu projeto usando o msbuild, execute um comando semelhante a:

msbuild myproject.csproj /target:rebuild /verbosity:minimal

A captura de tela a seguir mostra a saída de compilação de linha de comando de um projeto que contém uma violação de regra do analisador:

Projetos dependentes

Em um projeto do .NET Core, se você adicionar uma referência a um projeto que tenha analisadores Do NuGet, o Visual Studio adicionará automaticamente esses analisadores ao projeto dependente. Para desabilitar esse comportamento (por exemplo, se o projeto dependente for um projeto de teste de unidade), marque o pacote NuGet como privado definindo o PrivateAssets atributo no arquivo .csproj ou .vbproj do projeto referenciado:

<PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="5.0.0" PrivateAssets="all" />

Conteúdo relacionado

• Visão geral dos analisadores de código no Visual Studio
• Enviar um bug do analisador de código
• Usar conjuntos de regras
• Suprimir violações de análise de código
• Opções de configuração para análise de código