Visão geral da análise do código-fonte do .NET

  • Artigo

Os analisadores do .NET Compiler Platform (Roslyn) inspecionam código em C# ou no Visual Basic em busca de problemas de estilo e de qualidade. A partir do .NET 5, esses analisadores estão incluídos no SDK do .NET e não é necessário instalá-los separadamente. Se o destino do projeto for o .NET 5 ou posterior, a análise de código será habilitada por padrão. Se o destino do projeto for uma implementação diferente do .NET, por exemplo, .NET Core, .NET Standard ou .NET Framework, você deverá habilitar manualmente a análise de código definindo a propriedade EnableNETAnalyzers como true.

Se você não quiser migrar para o SDK do .NET 5+, tenha um projeto .NET Framework de estilo não SDK ou prefira um modelo baseado em pacote NuGet. Os analisadores também estarão disponíveis no pacote NuGet Microsoft.CodeAnalysis.NetAnalyzers. Talvez você prefira um modelo baseado em pacote para atualizações de versão sob demanda.

Observação

Os analisadores do .NET são independentes da estrutura de destino. Ou seja, seu projeto não precisa ser destinado a uma implementação específica do .NET. Os analisadores trabalham para projetos destinados ao .NET 5+, bem como versões anteriores do .NET, como .NET Core 3.1 e .NET Framework 4.7.2. No entanto, para habilitar a análise de código usando a propriedade EnableNETAnalyzers, seu projeto deve fazer referência a um SDK do projeto.

Se forem encontradas violações de regra por um analisador, elas serão relatadas como uma sugestão, aviso ou erro, dependendo de como cada regra foi configurada. As violações da análise de código aparecem com o prefixo "CA" ou "IDE" para diferenciá-las de erros do compilador.

Análise de qualidade de código

As regras de análise de qualidade de código ("CAxxxx") inspecionam o código em C# ou no Visual Basic para analisar a segurança, o desempenho, o design e problemas diversos. A análise está habilitada, por padrão, para projetos direcionados ao .NET 5 ou posterior. É possível habilitar a análise de código em projetos direcionados a versões anteriores do .NET definindo a propriedade EnableNETAnalyzers como true. Também é possível desabilitar a análise de código do projeto definindo EnableNETAnalyzers como false.

Dica

Se você estiver usando o Visual Studio, muitas regras do analisador têm correções de código associadas que podem ser aplicadas para corrigir o problema. As correções de código são mostradas no menu do ícone de lâmpada.

Regras habilitadas

As regras a seguir são habilitadas, por padrão, como erros ou avisos no .NET 8. Regras adicionais são habilitadas como sugestões.

ID do diagnóstico Categoria Severidade Versão adicionada Descrição
CA1416 Interoperabilidade Aviso .NET 5 validar a compatibilidade da plataforma
CA1417 Interoperabilidade Aviso .NET 5 Não usar OutAttribute em parâmetros de cadeia de caracteres para P/Invokes
CA1418 Interoperabilidade Aviso .NET 6 Usar uma cadeia de caracteres de plataforma válida
CA1420 Interoperabilidade Aviso .NET 7 Usar recursos que exigem marshalling de runtime quando ele está desabilitado resulta em exceções no tempo de execução
CA1422 Interoperabilidade Aviso .NET 7 validar a compatibilidade da plataforma
CA1831 Desempenho Aviso .NET 5 Usar AsSpan em vez de indexadores baseados em intervalo na cadeia de caracteres quando apropriado
CA1856 Desempenho Erro .NET 8 Uso incorreto do atributo ConstantExpected
CA1857 Desempenho Aviso .NET 8 Uma constante é esperada para o parâmetro
CA2013 Confiabilidade Aviso .NET 5 Não use ReferenceEquals com tipos de valor
CA2014 Confiabilidade Aviso .NET 5 Não use stackalloc em loops
CA2015 Confiabilidade Aviso .NET 5 Não definir finalizadores para tipos derivados do MemoryManager<T>
CA2017 Confiabilidade Aviso .NET 6 Incompatibilidade de contagem de parâmetros
CA2018 Confiabilidade Aviso .NET 6 O argumento count para Buffer.BlockCopy deve especificar o número de bytes a serem copiados
CA2021 Confiabilidade Aviso .NET 8 Não chame Enumerable.Cast<T> ou Enumerable.OfType<T> com tipos incompatíveis
CA2200 Uso Aviso .NET 5 Relançar para preservar detalhes da pilha
CA2247 Uso Aviso .NET 5 O argumento passado para o construtor TaskCompletionSource deve ser a enumeração TaskCreationOptions em vez de TaskContinuationOptions
CA2252 Uso Erro .NET 6 Optar pela versão prévia dos recursos
CA2255 Uso Aviso .NET 6 O atributo ModuleInitializer não deve ser usado em bibliotecas
CA2256 Uso Aviso .NET 6 Todos os membros declarados em interfaces pai devem ter uma implementação em uma interface atribuída a DynamicInterfaceCastableImplementation
CA2257 Uso Aviso .NET 6 Membros definidos em uma interface com o DynamicInterfaceCastableImplementationAttribute devem ser static
CA2258 Uso Aviso .NET 6 O fornecimento de uma interface DynamicInterfaceCastableImplementation no Visual Basic não tem suporte
CA2259 Uso Aviso .NET 7 ThreadStatic afeta apenas campos estáticos
CA2260 Uso Aviso .NET 7 Usar o parâmetro de tipo correto
CA2261 Uso Aviso .NET 8 Não use ConfigureAwaitOptions.SuppressThrowing com Task<TResult>

Você pode alterar a gravidade dessas regras para desabilitá-las ou elevá-las a erros. Também é possível habilitar mais regras.

Habilitar regras adicionais

O modo de análise refere-se a uma configuração de análise de código predefinida em que nenhuma, algumas ou todas as regras estão habilitadas. No modo de análise padrão (Default), apenas algumas regras são habilitadas como avisos de build. É possível alterar o modo de análise do projeto definindo a propriedade <AnalysisMode> no arquivo de projeto. Os valores permitidos são:

Valor Descrição
None Todas as regras estão desabilitadas. Você pode aderir seletivamente a regras individuais para habilitá-las.
Default Modo padrão, no qual certas regras são ativadas como avisos de build, certas regras são habilitadas como sugestões do IDE do Visual Studio e as demais são desabilitadas.
Minimum Modo mais agressivo do que o modo Default. Algumas sugestões altamente recomendadas para a imposição de build são habilitadas como avisos de build. Para ver quais regras isso inclui, inspecione o arquivo %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.editorconfig.
Recommended Modo mais agressivo do que o modo Minimum, em que mais regras são habilitadas como avisos de build. Para ver quais regras isso inclui, inspecione o arquivo %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.editorconfig.
All Todas as regras são habilitadas como avisos de build*. Você pode recusar seletivamente regras individuais para desabilitá-las.

* As regras a seguir não são habilitadas definindo AnalysisMode como All ou AnalysisLevel como latest-all: CA1017, CA1045, CA1005, CA1014, CA1060 e CA1021 e as regras do analisador de métricas de código (CA1501, CA1502, CA1505, CA1506 e CA1509). Essas regras herdadas podem ser preteridas em uma versão futura. No entanto, você ainda pode habilitá-las individualmente usando uma entrada dotnet_diagnostic.CAxxxx.severity = <severity>.

A partir do .NET 6, é possível omitir <AnalysisMode> em favor de um valor composto para a propriedade <AnalysisLevel>. Por exemplo, o seguinte valor habilita o conjunto de regras recomendado para a versão mais recente: <AnalysisLevel>latest-Recommended</AnalysisLevel>. Para obter mais informações, consulte AnalysisLevel.

Para encontrar a gravidade padrão de cada regra disponível e se a regra está habilitada no modo de análise Default, confira a lista completa de regras.

Tratar avisos como erros

Se você usar o sinalizador -warnaserror ao criar seus projetos, todos os avisos de análise de código também serão tratados como erros. Se você não quiser que os avisos de qualidade de código (CAxxxx) sejam tratados como erros na presença de -warnaserror, defina a propriedade do MSBuild CodeAnalysisTreatWarningsAsErrors como false no arquivo de projeto.

<PropertyGroup>
  <CodeAnalysisTreatWarningsAsErrors>false</CodeAnalysisTreatWarningsAsErrors>
</PropertyGroup>

Avisos de análise de código ainda serão exibidos, mas eles não interromperão o build.

Atualizações mais recentes

Por padrão, você obterá as regras de análise de código mais recentes e as severidades de regra padrão ao atualizar para versões mais recentes do SDK do .NET. Caso esse comportamento não seja desejado, por exemplo, para garantir que nenhuma nova regra seja habilitada ou desabilitada, uma substituição poderá ser feita de uma das seguintes maneiras:

  • Defina a propriedade do MSBuild AnalysisLevel como um valor específico para bloquear os avisos para esse conjunto. Ao atualizar para um SDK mais recente, você ainda receberá correções de bug para esses avisos, mas nenhum aviso novo será habilitado e nenhum aviso existente será desabilitado. Por exemplo, para bloquear o conjunto de regras para aqueles fornecidos com a versão 5.0 do SDK do .NET, adicione a seguinte entrada ao arquivo de projeto.

    <PropertyGroup>
  <AnalysisLevel>5.0</AnalysisLevel>
</PropertyGroup>

    Dica

    O valor padrão da propriedade AnalysisLevel é latest, o que significa que você sempre obtém as regras de análise de código mais recentes à medida que passa para versões mais recentes do SDK do .NET.

    Para obter mais informações e obter uma lista de valores possíveis, consulte AnalysisLevel.

  • Instale o pacote NuGet Microsoft.CodeAnalysis.NetAnalyzers para desvincular as atualizações de regras das atualizações do SDK do .NET. Nos projetos direcionados ao .NET 5+, a instalação do pacote desativa os analisadores internos do SDK. Um aviso de build será exibido se o SDK contiver uma versão mais recente do assembly do analisador do que a do pacote NuGet. Para desabilitar o aviso, defina a propriedade _SkipUpgradeNetAnalyzersNuGetWarning como true.

    Observação

    Ao instalar o pacote NuGet Microsoft.CodeAnalysis.NetAnalyzers, não adicione a propriedade EnableNETAnalyzers ao arquivo de projeto ou a um arquivo Directory.Build.props. Quando o pacote NuGet é instalado e a propriedade EnableNETAnalyzers é definida como true, um aviso de build é gerado.

Análise de estilo de código

As regras de análise de estilo de código ("IDExxxx") permitem que você defina e mantenha o estilo de código consistente em sua base de código. As configurações de habilitação padrão são:

  • Build de linha de comando: a análise de estilo de código é desabilitada, por padrão, em todos os projetos do .NET em builds de linha de comando.

    A partir do .NET 5, é possível habilitar a análise de estilo de código no build, tanto na linha de comando quanto no Visual Studio. As violações de estilo de código aparecem como avisos ou erros com o prefixo "IDE". Isso permite que você imponha estilos de código consistentes no tempo de build.

  • Visual Studio: a análise de estilo de código é habilitada, por padrão, para todos os projetos do .NET no Visual Studio como ações rápidas de refatoração de código.

Para obter uma lista completa de regras de análise de estilo de código, consulte Regras de estilo de código.

Habilitar no build

Com o SDK do .NET 5 e versões posteriores, você pode habilitar a análise de estilo de código ao criar a partir da linha de comando e no Visual Studio. (No entanto, por motivos de desempenho, algumas regras de estilo de código ainda serão aplicadas somente no IDE do Visual Studio.)

Siga estas etapas para habilitar a análise de estilo de código no build:

  1. Defina a propriedade do MSBuild EnforceCodeStyleInBuild como true.

  2. Em um arquivo .editorconfig, configure cada regra de estilo de código "IDE" que você deseja executar no build como um aviso ou erro. Por exemplo:

    [*.{cs,vb}]
# IDE0040: Accessibility modifiers required (escalated to a build warning)
dotnet_diagnostic.IDE0040.severity = warning

    Dica

    A partir do .NET 9, você também pode usar o formato de opção para especificar um nível de gravidade e isso será considerado no momento da compilação. Por exemplo:

    [*.{cs,vb}]
# IDE0040: Accessibility modifiers required (escalated to a build warning)
dotnet_style_require_accessibility_modifiers = always:warning

    Como alternativa, é possível configurar uma categoria inteira para ser um aviso ou erro, por padrão, e desativar seletivamente as regras nessa categoria que não deseja executar no build. Por exemplo:

    [*.{cs,vb}]

# Default severity for analyzer diagnostics with category 'Style' (escalated to build warnings)
dotnet_analyzer_diagnostic.category-Style.severity = warning

# IDE0040: Accessibility modifiers required (disabled on build)
dotnet_diagnostic.IDE0040.severity = silent

Suprimir um aviso

Uma maneira de suprimir uma violação de regra é definindo a opção de severidade para essa ID de regra como none em um arquivo EditorConfig. Por exemplo:

dotnet_diagnostic.CA1822.severity = none

Para obter mais informações e outras maneiras de suprimir avisos, consulte Como suprimir os avisos da análise de código.

Executar a análise de código como uma ação do GitHub

A Ação do GitHub dotnet/code-analysis permite executar analisadores de código .NET como parte da CI (integração contínua) em um modo offline. Para obter mais informações, consulte Ação do GitHub da análise de código do .NET.

Analisadores de terceiros

Além dos analisadores oficiais do .NET, também é possível instalar analisadores de terceiros, como StyleCop, Roslynator, XUnit Analyzers e Sonar Analyzer.

Confira também