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 configuraçã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 gravidade que você pode configurar para um diagnóstico:

Ver violações de regras

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

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 linhas onduladas sob o código problemático. Por exemplo, a captura de tela a seguir mostra três violações: um erro (linha de ondulação vermelha), um aviso (linha de ondulação 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 da regra. As correções de código são mostradas no menu de ícones de lâmpadas, juntamente 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 severidade da regra usando qualquer um dos seguintes métodos:

Gravidade silenciosa vs. nenhuma

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

• Se uma correção de código for registada para uma regra de severidade Silent, o Visual Studio oferecerá a correção de código como uma ação de refatoração de código do tipo lâmpada, mesmo que o diagnóstico escondido não esteja visível para o utilizador. 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 regras de gravidade em massa. None As regras de gravidade não podem ser configuradas dessa forma. Em vez disso, eles devem ser configurados 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 posterior.

Definir a severidade 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 através 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, se 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 severidade para CA1822 para error arquivos C# é a seguinte:

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

3. Você pode definir a severidade 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 severidade de várias regras do analisador de uma só vez em um arquivo EditorConfig

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

Você pode definir a severidade 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 severidade da regra para uma categoria de regras do analisador:

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

• Defina a severidade 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 aplicam-se 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 que são aplicáveis a um ID de regra específico, a ordem de precedência para a entrada aplicável é 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 gravidade para uma categoria tem precedência sobre uma entrada de gravidade para todas as regras da ferramenta de análise.

Considere o seguinte exemplo de EditorConfig, onde 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, de acordo com as regras de precedência especificadas, a primeira entrada que determina a gravidade com base no ID da regra tem primazia sobre as entradas subsequentes. Neste exemplo, CA1822 tem uma severidade efetiva de error. As restantes regras de desempenho têm uma severidade de warning. As regras do analisador que não são regras de desempenho têm uma severidade de suggestion.

Definir a severidade da regra a partir do menu de lâmpadas

O Visual Studio fornece uma maneira conveniente de configurar a severidade de uma regra no menu de lâmpadas Ações Rápidas . Siga estes passos:

1. Depois de ocorrer uma violação, coloque o cursor sobre a linha ondulada de violação no editor e escolha Mostrar possíveis correções para abrir o menu da lâmpada. Ou coloque o cursor na linha e pressione Ctrl+.

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

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

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

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

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

     

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 para você.

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

Para definir a severidade da regra a partir do Solution Explorer, siga estes passos:

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

2. Expanda o conjunto 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 gravidade. No menu de contexto, escolha 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 seu projeto usa um arquivo de conjunto de regras em vez de um arquivo EditorConfig, a entrada de gravidade é 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 a partir do Gerenciador de Soluções. Se você instalar um analisador como um pacote NuGet, um nó Analisadores aparecerá sob o nó Referências (ou nó Dependências para projetos .NET Core) no Gerenciador de Soluções. Siga estas etapas para visualizar os analisadores e diagnósticos:

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

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

   • x em um círculo indica uma gravidade de Erro
   • ! num triângulo indica uma gravidade de Aviso
   • i num círculo sólido indica severidade de 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 Nenhum

   

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 Properties é exibida.

   

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

4. Para obter documentação online para um diagnóstico, clique com o botão direito do rato no diagnóstico e, em seguida, selecione Ver 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 de arquivos EditorConfig para configuração do analisador para código gerenciado. Os arquivos EditorConfig são mais flexíveis e permitem configurar as severidades das regras do analisador e as opções do analisador, incluindo opções de estilo de código IDE do Visual Studio. Como as ferramentas do Visual Studio para configuração de gravidade de regras do analisador agora estão otimizadas para trabalhar 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 do 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.

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

1. Clique duas vezes no arquivo do 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 MSBuild é atualizada no arquivo de projeto para que ele não faça mais referência ao arquivo de conjunto de regras original.

   O arquivo original do conjunto de regras 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 utilizar a linha de comandos, siga estes passos:

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

2. Execute RulesetToEditorconfigConverter.exe a partir 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 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 arquivos de origem em um projeto e relatam quaisquer violações encontradas. 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 compilação 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 quaisquer violações.

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 de forma personalizada 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 com .MyGenerated.cs como código gerado, use esta entrada:

   [*.MyGenerated.cs]
   generated_code = true
   

Suprimir violações

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

Uso da linha de comando

Quando você cria seu projeto na linha de comando, as violações de regra aparecem na saída da compilação 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 habilitá-los. Para estilos de código, você também pode impor estilos de código em compilações 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 na compilação, ou erro, caso em que as violações fazem com que a compilação falhe.

A verbosidade da saída de compilação não afeta se as violações de regras são mostradas. Mesmo com a verborragia silenciosa , as violações de regras aparecem na saída da compilação.

Se estiver habituado a executar análise de legado a partir da linha de comandos, seja com FxCopCmd.exe ou através do msbuild com o RunCodeAnalysis flag, pode fazê-lo com analisadores de código.

Para ver as violações do analisador na linha de comando quando você cria seu projeto usando 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 da criação de um projeto que contém uma violação de regra do analisador:

Projetos dependentes

Em um projeto .NET Core, se você adicionar uma referência a um projeto que tenha analisadores 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