Personalizar as regras do analisador Roslyn.

Cada diagnóstico ou regra do analisador Roslyn tem um estado de gravidade e supressão padrão que pode ser substituído e personalizado para seu projeto. Este artigo aborda a configuração de severidades e a supressão de violações do analisador.

Níveis de severidade

No Visual Studio 2019 versão 16.3 e mais recente, você pode configurar a gravidade das regras do analisador, em um arquivo EditorConfig, no menu de lâmpada e na janela Lista de Erros.

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

Gravidade (Gerenciador de Soluções)	Gravidade (arquivo EditorConfig)	Comportamento em tempo de compilação	Comportamento do editor
Erro	error	As violações são exibidas na guia Erros na janela Lista de Erros e na saída do build da linha de comando e causam falha nos builds.	O código transgressor é sublinhado com um texto sublinhado vermelho e marcado por uma pequena caixa vermelha na barra de rolagem.
Aviso	warning	As violações aparecem na guia Avisos na janela Lista de Erros e na saída do build da linha de comando, mas não causam falha nos builds.	O código transgressor é sublinhado com um texto sublinhado verde e marcado por uma pequena caixa verde na barra de rolagem.
Sugestão	suggestion	As violações aparecem na guia Mensagens na janela Lista de Erros e não aparecem na saída do build da linha de comando.	O código transgressor é sublinhado com um texto sublinhado cinza e marcado por uma pequena caixa cinza na barra de rolagem.
Silent	silent	Invisível para o usuário.	Invisível para o usuário, mas o diagnóstico é relatado ao mecanismo de diagnóstico do IDE.
Nenhum	none	Suprimido completamente.	Suprimido completamente.
Padrão	default	Corresponde à gravidade padrão da regra. Para determinar o valor padrão de uma regra, visualize sua janela Propriedades.	Corresponde à gravidade padrão da regra.

Exibir violações de regras

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 violações de regras relatadas na janela Lista de Erros. As violações do analisador relatadas na lista de erros correspondem à configuração de nível de gravidade da regra:

As violações das regras do analisador também aparecem no editor de código como textos sublinhados sob o código transgressor. Por exemplo, a captura de tela a seguir mostra três violações: um erro (texto sublinhado vermelho), um aviso (texto sublinhado 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 do ícone de lâmpada, juntamente com outros tipos de Ações rápidas. Para obter mais informações sobre correções de código, confira Ações rápidas comuns.

Configurar níveis de severidade

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

• EditorConfig
• Menu de lâmpada
• Janela Lista de Erros
• Gerenciador de Soluções

Gravidade silenciosa versus nenhuma

As regras de gravidade Silent habilitadas por padrão são diferentes das regras desabilitadas ou de gravidade None:

• Se uma correção de código for registrada para uma regra de gravidade Silent, o Visual Studio oferece 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 gravidade 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 de uma só vez em um arquivo EditorConfig podem configurar Silent em massa as regras de gravidade. Regras com severidade None não podem ser configuradas dessa maneira. Em vez disso, elas devem ser configuradas por meio de entradas que definem a gravidade em um arquivo EditorConfig para cada ID de regra.

Definir a severidade da regra em um arquivo EditorConfig

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

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

Configurar manualmente a severidade da regra em um arquivo EditorConfig

Para configurar a gravidade da regra, siga estas etapas:

1. Adicione um arquivo EditorConfig ao seu projeto, caso ainda não tenha 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 do CA1822 para error 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 do 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 sintaxe dotnet_diagnostic, ela terá precedência. Para obter mais informações, consulte Convenções de linguagem para EditorConfig.

Definir a gravidade de várias regras do analisador de uma só vez 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 mais recente.

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

• Defina a gravidade de 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>

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

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

• Uma entrada de gravidade para uma regra individual por ID tem precedência sobre uma entrada de gravidade para uma categoria.
• Uma entrada de gravidade para uma categoria tem precedência sobre uma entrada de gravidade 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. Entretanto, usando as regras de precedência especificadas, a primeira entrada de gravidade baseada em ID de regra tem precedência sobre as próximas entradas. Nesse exemplo, o CA1822 tem uma gravidade efetiva de error. As regras de desempenho restantes têm uma gravidade de warning. As regras do analisador que não são regras de desempenho têm uma gravidade de suggestion.

Definir a severidade da regra no menu de lâmpada

O Visual Studio proporciona uma maneira conveniente de configurar a severidade de uma regra no menu de lâmpada Ações Rápidas. Siga estas etapas:

1. Após uma violação ocorrer, passe o mouse sobre o texto sublinhado de violação no editor e escolha Mostrar possíveis correções para abrir o menu de lâmpada. Ou coloque o cursor sobre a linha e pressione Ctrl+. (ponto final).

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

   • Configure a <gravidade do ID> da regra. Defina a gravidade para a regra específica.

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

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

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

     

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

   

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

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

Definir a severidade da regra na janela Lista de Erros

O Visual Studio também proporciona uma maneira conveniente de configurar a severidade de uma regra no menu de contexto da lista de erros. Siga estas etapas:

1. Depois que uma violação ocorrer, clique com o botão direito do mouse na entrada de diagnóstico na lista de erros.

2. No menu de contexto, selecione Definir gravidade e, em seguida, selecione uma das opções de gravidade.

   

   O Visual Studio adiciona uma entrada ao arquivo EditorConfig para configurar a regra para o nível solicitado.

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

Definir a severidade da regra de Gerenciador de Soluções

Para definir a gravidade da regra a partir do gerenciador de soluções, siga estes passos:

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

2. Expanda o assembly que contém a regra para a qual deseja definir a gravidade.

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 EditorConfig, a entrada de gravidade 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 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 no Gerenciador de Soluções. Se você instalar um analisador como um pacote NuGet, um nó de Analisadores será exibido sob o nó Referências (ou nó Dependências para projetos .NET Core) no Gerenciador de Soluções. Siga estas etapas para exibir os analisadores e 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 o diagnóstico no assembly.

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

   • x em um círculo indica uma gravidade de Erro
   • ! em um triângulo indica uma gravidade de Aviso
   • i em um círculo sólido indica uma gravidade de Sugestão
   • i em um círculo pontilhado indica uma gravidade de Silêncio
   • A seta apontando para baixo em um círculo sólido indica uma gravidade de Nenhum

   

2. Para visualizar as propriedades de um diagnóstico, incluindo a descrição e a 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 de regras de estilo de código (prefixo IDE) na janela Propriedades, como gravidade padrão, defina propriedade EnforceCodeStyleInBuild como true.

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

Converter um arquivo de conjunto de regras existente no arquivo EditorConfig

No Visual Studio 2019 versão 16.5 e mais recente, os arquivos de conjunto de regras são preteridos em favor dos arquivos EditorConfig para configuração do analisador para código gerenciado. Arquivos EditorConfig são mais flexíveis e permitem que você configure as gravidades 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 configuração de gravidade de regras do analisador agora são otimizadas para trabalhar com arquivos EditorConfig em vez de arquivos de conjunto de regras, você é incentivado a converter quaisquer 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 gravidade 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.

Observação

Projetos .NET Core e .NET Standard não dão suporte aos comandos de menu para conjuntos de regras no Gerenciador de Soluções, por exemplo, Abrir Conjunto de Regras Ativo. Para especificar um conjunto de regras não padrão para um projeto .NET Core ou .NET Standard, adicione manualmente a propriedade CodeAnalysisRuleSet ao arquivo de projeto. Você ainda pode configurar as regras no conjunto de regras no editor de conjunto de regras.

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

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

   O arquivo do 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 deseja gerar o arquivo EditorConfig e selecione Salvar.

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

Para usar a linha de comando, siga estas etapas:

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

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

   Por exemplo:

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

O exemplo a seguir mostra um arquivo de conjunto de regras para converter 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 são executados em todos os arquivos de origem em um projeto e relatam todas as violações encontradas. No entanto, essas violações não são úteis para arquivos gerados pelo sistema. Exemplos são os 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 editá-los manualmente e não se preocupam em corrigir violações.

Portanto, por padrão, o driver do analisador examina somente os arquivos com determinados nomes, extensões de arquivo ou cabeçalhos de arquivo gerados automaticamente como arquivos de código gerado. Por exemplo, um nome de arquivo que termina com .designer.cs ou .generated.cs é considerado código gerado. No entanto, essa heurística pode não ser capaz 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 mais recente, 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 tem um arquivo EditorConfig para o projeto, adicione um.

2. Adicione a entrada generated_code = true | false para arquivos e pastas específicos. Por exemplo, para tratar todos os arquivos cujo nome termina com .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 mais informações, consulte Suprimir violações de Code Analysis.

Uso da linha de comando

Quando você cria o projeto na linha de comando, as violações de regra aparecerão 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 nos builds definindo uma propriedade MSBuild.

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

• O nível de gravidade de uma regra violada é definido como aviso, caso em que as violações não causam falha no build, ou erro, caso em que as violações causam falha no build.

O detalhamento da saída do build não afeta se violações de regra são mostradas. Mesmo com o detalhamento silencioso, as violações de regra aparecem na saída do build.

Se estiver acostumado a executar a análise herdada a partir da linha de comando, seja com o FxCopCmd.exe ou por meio do msbuild com o sinalizador RunCodeAnalysis, você poderá fazer isso com 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 build da linha de comando da criação de um projeto que contém uma violação de regra de analisador:

Projetos dependentes

Em um projeto .NET Core, se você adicionar uma referência a um projeto que tenha analisadores NuGet, o Visual Studio adiciona 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 no arquivo .csproj ou .vbproj do projeto referenciado definindo o atributo PrivateAssets:

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

Conteúdo relacionado

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