Visão geral

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

Configurar níveis de severidade

A partir do Visual Studio 2019 versão 16.3, você pode configurar a severidade das regras do analisador ou o diagnóstico , em um arquivo EditorConfig, no menude lâmpada e na lista de erros.

Você pode configurar a severidade das regras do analisador, ou diagnóstico, se você instalar os analisadores como um NuGet pacote. Você pode alterar a severidade de uma regra de Gerenciador de Soluções ou em um arquivo de conjunto de regras.

A tabela a seguir mostra as diferentes opções de severidade:

Gravidade (Gerenciador de Soluções) Gravidade (arquivo EditorConfig) Comportamento em tempo de compilação Comportamento do editor
Erro error As violações aparecem como Erros na Lista de Erros e na saída de build de linha de comando e causam falha nos builds. O código ofensivo é sublinhado com uma alternância vermelha e marcado por uma pequena caixa vermelha na barra de rolagem.
Aviso warning As violações aparecem como Avisos na Lista de Erros e na saída de build de linha de comando, mas não causam falha nos builds. O código ofensivo é sublinhado com uma alternância verde e marcado por uma pequena caixa verde na barra de rolagem.
Info suggestion As violações aparecem como Mensagens na Lista de Erros e não na saída de build de linha de comando. O código ofensivo é sublinhado com uma alternância cinza e marcado por uma pequena caixa cinza na barra de rolagem.
Hidden silent Não visível para o usuário. Não visível para o usuário. No entanto, o diagnóstico é relatado ao mecanismo de diagnóstico do IDE.
Nenhum none Suprimido completamente. Suprimido completamente.
Padrão default Corresponde à severidade padrão da regra. Para determinar qual é o valor padrão de uma regra, procure no janela Propriedades. Corresponde à severidade padrão da regra.

Se as violações de regra são encontradas por um analisador, elas são relatadas no editor de código (como uma alternância sob o código ofensivo) e na janela Lista de Erros.

As violações do analisador relatadas na lista de erros corresponderão à configuração de nível de severidade da regra. As violações do analisador também aparecem no editor de códigos como alternâncias sob o código ofensivo. A imagem a seguir mostra três violações: um erro (alternância vermelha), um aviso (alternância verde) e uma — sugestão (três pontos cinzas):

Alternâncias no editor de códigos Visual Studio

A captura de tela a seguir mostra as mesmas três violações que aparecem na Lista de Erros:

Erro, aviso e violação de informações na Lista de Erros

Muitas regras de analisador, ou diagnóstico, 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 saber mais sobre essas correções de código, confira Ações rápidas comuns.

Violação do analisador e correção de código de Ação Rápida

Severidade 'Hidden' versus 'None'

Hidden as regras de severidade habilitadas por padrão são diferentes das regras desabilitadas ou None de severidade de duas maneiras.

  • Se qualquer correção de código tiver sido registrada para uma regra de severidade, a correção será oferecida como uma ação de refactoração de código de lâmpada no Visual Studio, mesmo que o diagnóstico oculto não esteja visível para o Hidden usuário. Esse não é o caso para regras de None severidade desabilitadas.
  • Hidden As regras de severidade podem ser configuradas em massa por entradas que configuram a severidade da regra de várias regras de analisador ao mesmo tempo em um arquivo EditorConfig. None As regras de severidade não podem ser configuradas dessa maneira. Em vez disso, eles devem ser configurados por meio de entradas que deverão definir a severidade da regra em um arquivo EditorConfig para cada ID de regra.

Definir a severidade da regra em um arquivo EditorConfig

(Visual Studio 2019 versão 16.3 e posterior)

Você pode definir a severidade para avisos do compilador ou regras do analisador em um arquivo EditorConfig com a seguinte sintaxe:

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

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

Definir a severidade da regra de várias regras de analisador ao mesmo tempo em um arquivo EditorConfig

(Visual Studio 2019 versão 16.5 e posterior)

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

  • Definir a severidade da regra para uma categoria de regras do analisador:

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

  • Definir a severidade da regra para todas as regras do analisador:

dotnet_analyzer_diagnostic.severity = <severity>

Observação

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

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

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

Considere o seguinte exemplo editorConfig, 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 são aplicáveis à CA1822. No entanto, usando as regras de precedência especificadas, a primeira entrada de severidade baseada em ID de regra vence nas próximas entradas. Neste exemplo, CA1822 terá uma severidade efetiva de "erro". Todas as regras restantes com a categoria "Desempenho" terão "aviso" de severidade. Todas as regras restantes do analisador, que não têm a categoria "Desempenho", terão a severidade "sugestão".

Configurar manualmente a severidade da regra em um arquivo EditorConfig

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

  2. Adicione uma entrada para cada regra que você deseja configurar na extensão de arquivo correspondente. Por exemplo, para definir a severidade de CA1822 como para arquivos C#, a entrada error tem a seguinte aparência:

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

Observação

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 dotnet_diagnostic a sintaxe , ela tem precedência. Para obter mais informações, consulte Convenções de linguagem para EditorConfig.

Definir a severidade da regra no menu de lâmpada

Visual Studio fornece uma maneira conveniente de configurar a severidade de uma regra no menu de lâmpada ações rápidas.

  1. Depois que ocorrer uma violação, passe o mouse sobre a alternância de violação no editor e abra o menu de lâmpada. Ou coloque o cursor na linha e pressione Ctrl + . (ponto).

  2. No menu de lâmpada, selecione Configurar ou Suprimir problemas Configurar > <rule ID> severidade.

    Configurar a severidade da regra no menu de lâmpada Visual Studio

  3. A partir daí, escolha uma das opções de severidade.

    Configurar a severidade da regra como Sugestão

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

    Dica

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

Definir a severidade da regra da janela Lista de Erros

Visual Studio também fornece uma maneira conveniente de configurar a severidade de uma regra no menu de contexto da lista de erros.

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

  2. No menu de contexto, selecione Definir severidade.

    Configurar a severidade da regra da lista de erros Visual Studio

  3. A partir daí, escolha uma das opções de severidade.

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

    Dica

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

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

Você pode fazer grande parte da personalização do diagnóstico do Analyzer do Gerenciador de soluções. se você instalar os analisadores como um pacote de NuGet, um nó de analisadores será exibido no nó referências ou dependências em Gerenciador de Soluções. Se você expandir os analisadores e, em seguida, expandir um dos assemblies do analisador, verá todos os diagnósticos no assembly.

Nó de analisadores no Gerenciador de Soluções

Você pode exibir as propriedades de um diagnóstico, incluindo sua descrição e severidade padrão, na janela Propriedades . Para exibir as propriedades, clique com o botão direito do mouse na regra e selecione Propriedades, ou selecione a regra e pressione ALT + Enter.

Propriedades de diagnóstico no janela Propriedades

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

Os ícones ao lado de cada diagnóstico no Gerenciador de soluções correspondem aos ícones que você vê no conjunto de regras ao abri-lo no editor:

  • o "x" em um círculo indica uma severidade de erro
  • o "!" em um triângulo indica uma severidade de aviso
  • o "i" em um círculo indica uma severidade de informações
  • o "i" em um círculo em um plano de fundo com cor clara indica uma severidade de oculto
  • a seta apontando para baixo em um círculo indica que o diagnóstico foi suprimido

Ícones de diagnóstico no Gerenciador de Soluções

Converter um arquivo RuleSet existente no arquivo EditorConfig

a partir do Visual Studio 2019 versão 16,5, os arquivos ruleset são preteridos em favor do arquivo EditorConfig para a configuração do analisador para código gerenciado. a maioria das ferramentas de Visual Studio para a configuração de severidade da regra do analisador foi atualizada para funcionar em arquivos EditorConfig em vez de arquivos ruleset. os arquivos EditorConfig permitem que você configure ambas as opções do analisador e gravidade da regra do analisador, incluindo Visual Studio opções de estilo de código IDE. É altamente recomendável que você converta o arquivo RuleSet existente em um arquivo EditorConfig. Também é recomendável que você salve o arquivo EditorConfig na raiz do seu repositório ou na pasta da solução. Usando a raiz do seu repositório ou pasta de solução, você garante que as configurações de severidade desse arquivo sejam aplicadas automaticamente a todo o repositório ou solução, respectivamente.

Há duas maneiras de converter um arquivo RuleSet existente em um arquivo EditorConfig:

  • no Editor de conjunto de regras no Visual Studio (requer Visual Studio 2019 16,5 ou posterior). Se o seu projeto já usa um arquivo RuleSet específico como seu CodeAnalysisRuleSet , você pode convertê-lo em um arquivo EditorConfig equivalente do editor de RuleSet no Visual Studio.

    1. Clique duas vezes no arquivo RuleSet em Gerenciador de Soluções.

      O arquivo RuleSet deve ser aberto no editor de RuleSet. Você deverá ver uma barra de edição clicável na parte superior do editor de conjunto de regras.

      Converter RuleSet em arquivo EditorConfig no editor de RuleSet

    2. Selecione o link da barra de opções.

      Isso deve abrir uma caixa de diálogo salvar como que permite selecionar o diretório onde você deseja gerar o arquivo EditorConfig.

    3. Selecione o botão salvar para gerar o arquivo EditorConfig.

      O EditorConfig gerado deve ser aberto no editor. além disso, a propriedade MSBuild CodeAnalysisRuleSet é atualizada no arquivo de projeto para que ele não referencie mais o arquivo ruleset original.

  • Na linha de comando:

    1. instale o pacote de NuGet Microsoft. CodeAnalysis. RulesetToEditorconfigConverter.

    2. Execute RulesetToEditorconfigConverter.exe a partir do pacote instalado, com caminhos para arquivo RuleSet e arquivo EditorConfig como argumentos de linha de comando.

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

Aqui está um exemplo de arquivo RuleSet para converter:

<?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>

Este é o arquivo EditorConfig convertido:

# 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

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

  1. Em Gerenciador de soluções, expanda referências > analisadores (ou > analisadores de dependências para projetos do .NET Core).

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

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

    Visual Studio adiciona uma entrada ao arquivo EditorConfig para configurar a regra para o nível solicitado. Se o seu projeto usa um arquivo RuleSet em vez de um arquivo EditorConfig, a entrada de severidade é adicionada ao arquivo RuleSet.

    Dica

    se você ainda não tiver um arquivo EditorConfig ou um arquivo ruleset no projeto, Visual Studio criará um novo arquivo EditorConfig para você.

  1. Clique com o botão direito do mouse na regra e selecione definir severidade do conjunto de regras. No menu de contexto, escolha uma das opções de gravidade.

    A severidade da regra é salva no arquivo de conjunto de regras ativo.

Definir a severidade da regra no arquivo de conjunto de regras

Arquivo de conjunto de regras no Gerenciador de Soluções

  1. Abra o arquivo de conjunto de regras ativo de uma das seguintes maneiras:
  • Em Gerenciador de soluções, clique duas vezes no arquivo, clique com o botão direito do mouse no > nó analisadores de referências e selecione abrir conjunto de regras ativas.

  • na página de propriedades Code Analysis para o projeto, selecione abrir .

    se esta for a primeira vez que você está editando o conjunto de regras, Visual Studio faz uma cópia do arquivo de conjunto de regras padrão, nomeia-o <projectname> . ruleset e o adiciona ao seu projeto. Esse conjunto de regras personalizadas também se torna o conjunto de regras ativo para seu projeto.

    Observação

    Os projetos .NET Core e .NET Standard não dão suporte aos comandos de menu para conjuntos de regras em Gerenciador de soluções, por exemplo, abrir conjunto de regras ativas. Para especificar um conjunto de regras não padrão para um projeto do .NET Core ou .NET Standard, adicione manualmente a propriedade CodeAnalysisRuleSet ao arquivo do projeto. você ainda pode configurar as regras dentro do conjunto de regras na interface do usuário do editor de conjunto de regras Visual Studio.

  1. Navegue até a regra expandindo seu assembly recipiente.

  2. Na coluna ação , selecione o valor para abrir uma lista suspensa e escolha a severidade desejada na lista.

    Arquivo de conjunto de regras aberto no editor

Configurar o código gerado

Os analisadores são executados em todos os arquivos de origem em um projeto e violações de relatório sobre eles. No entanto, essas violações não são úteis em arquivos de código gerados, como arquivos de código gerados pelo designer, arquivos de origem temporários gerados pelo sistema de compilação etc. Os usuários não podem editar esses arquivos manualmente e/ou não se preocupam com a correção de violações nesses tipos de arquivos gerados por ferramentas.

Por padrão, o driver do analisador que executa analisadores trata arquivos com determinado nome, extensão de arquivo ou cabeçalho de arquivo gerado 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.

a partir do Visual Studio 2019 16,5, os usuários finais podem configurar arquivos e/ou pastas específicos para serem tratados como código gerado em um arquivo EditorConfig. Siga as etapas abaixo para adicionar essa configuração:

  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/ou pastas específicas. Por exemplo, para tratar todos os arquivos cujo nome termina com .MyGenerated.cs o código gerado, a entrada seria a seguinte:

    [*.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 análise de código.

Uso da linha de comando

Quando você cria seu projeto na linha de comando, 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 do 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 na compilação definindo uma propriedade MSBuild.

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

  • A severidade de uma regra violada é definida como aviso; nesse caso, as violações não causam a falha da compilação ou erros, caso em que as violações causam a falha da compilação.

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

Dica

Se você estiver acostumado a executar a análise herdada na linha de comando, seja com FxCopCmd.exe ou por meio do MSBuild com o sinalizador RunCodeAnalysis , veja como fazer isso com analisadores de código.

Para ver as violações do analisador na linha de comando ao compilar seu projeto usando o MSBuild, execute um comando como este:

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

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

Saída do MSBuild com violação de regra

Projetos dependentes

em um projeto do .net Core, se você adicionar uma referência a um projeto que tenha NuGet analisadores, esses analisadores serão automaticamente adicionados ao projeto dependente. para desabilitar esse comportamento, por exemplo, se o projeto dependente for um projeto de teste de unidade, marque o pacote de 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" />

Confira também