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

  • Artigo

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

Se você não quiser mudar para o SDK do .NET 5+, tiver um projeto .NET Framework que não seja no estilo SDK ou preferir um modelo baseado em pacote NuGet, os analisadores também estarão disponíveis no pacote NuGet Microsoft.CodeAnalysis.NetAnalyzers. Você pode preferir um modelo baseado em pacote para atualizações de versão sob demanda.

Nota

Os analisadores .NET são agnósticos em relação à estrutura de destino. Ou seja, seu projeto não precisa direcionar uma implementação .NET específica. Os analisadores funcionam para projetos destinados ao .NET 5+, bem como a versões anteriores do .NET, como o .NET Core 3.1 e o .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 de projeto.

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

Análise de qualidade de código

As regras de análise de qualidade de código ("CAxxxx") inspecionam seu código C# ou Visual Basic em busca de segurança, desempenho, design e outros problemas. A análise é habilitada, por padrão, para projetos destinados ao .NET 5 ou posterior. Você pode habilitar a análise de código em projetos destinados a versões anteriores do .NET definindo a propriedade EnableNETAnalyzers como true. Você também pode desabilitar a análise de código para seu projeto definindo EnableNETAnalyzers como false.

Gorjeta

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

Regras ativadas

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

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

Você pode alterar a severidade dessas regras para desativá-las ou elevá-las a erros. Você também pode habilitar mais regras.

  • Para obter uma lista de regras incluídas em cada versão do SDK do .NET, consulte Versões do analisador.
  • Para obter uma lista de todas as regras de qualidade de código, consulte Regras de qualidade de código.

Ativar 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 um pequeno número de regras é habilitado como avisos de compilação. Você pode alterar o modo de análise para seu projeto definindo a <AnalysisMode> propriedade no arquivo de projeto. Os valores permitidos são:

valor Description
None Todas as regras estão desativadas. Você pode optar seletivamente por regras individuais para habilitá-las.
Default Modo padrão, onde certas regras são habilitadas como avisos de compilação, certas regras são habilitadas como sugestões IDE do Visual Studio e o restante é desabilitado.
Minimum Modo mais agressivo do que Default o modo. Certas sugestões que são altamente recomendadas para a imposição de compilação são habilitadas como avisos de compilação. 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, onde mais regras são ativadas Minimum como avisos de compilação. 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 ativadas como avisos de compilação*. Você pode desativar seletivamente regras individuais para desativá-las.

* As seguintes regras não são ativadas definindo AnalysisMode para AllAnalysisLevellatest-all: CA1017, CA1045, CA1005, CA1014, CA1060, 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á-los individualmente usando uma dotnet_diagnostic.CAxxxx.severity = <severity> entrada.

A partir do .NET 6, você pode omitir <AnalysisMode> em favor de um valor composto para a <AnalysisLevel> propriedade. Por exemplo, o valor a seguir habilita o conjunto de regras recomendado para a versão mais recente: <AnalysisLevel>latest-Recommended</AnalysisLevel>. Para obter mais informações, veja AnalysisLevel.

Para encontrar a severidade padrão para cada regra disponível e se a regra está habilitada ou não no Default modo de análise, consulte 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 , você pode definir a CodeAnalysisTreatWarningsAsErrors propriedade MSBuild como false em seu arquivo de -warnaserrorprojeto.

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

Você ainda verá avisos de análise de código, mas eles não quebrarão sua compilação.

Atualizações mais recentes

Por padrão, você obterá as regras de análise de código mais recentes e as severidades de regras padrão à medida que atualiza para versões mais recentes do SDK do .NET. Se você não quiser esse comportamento, por exemplo, se quiser garantir que nenhuma nova regra seja habilitada ou desabilitada, você poderá substituí-lo de uma das seguintes maneiras:

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

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

    Gorjeta

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

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

  • Instale o pacote NuGet Microsoft.CodeAnalysis.NetAnalyzers para desacoplar atualizações de regras das atualizações do SDK do .NET. Para projetos destinados ao .NET 5+, a instalação do pacote desativa os analisadores SDK internos. Você receberá um aviso de compilação se o SDK contiver uma versão de assembly do analisador mais recente do que a do pacote NuGet. Para desativar o aviso, defina a _SkipUpgradeNetAnalyzersNuGetWarning propriedade como true.

    Nota

    Se você instalar o pacote NuGet Microsoft.CodeAnalysis.NetAnalyzers, não deverá adicionar a propriedade EnableNETAnalyzers ao arquivo de projeto ou a um arquivo Directory.Build.props . Quando o pacote NuGet é instalado e a EnableNETAnalyzers propriedade é definida como true, um aviso de compilação é 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 um estilo de código consistente em sua base de código. As configurações de ativação padrão são:

  • Compilação de linha de comando: A análise de estilo de código é desabilitada, por padrão, para todos os projetos .NET em compilações de linha de comando.

    A partir do .NET 5, você pode habilitar a análise de estilo de código na compilação, tanto na linha de comando quanto dentro do Visual Studio. As violações de estilo de código aparecem como avisos ou erros com um prefixo "IDE". Isso permite que você imponha estilos de código consistentes no momento da compilação.

  • Visual Studio: A análise de estilo de código é habilitada, por padrão, para todos os projetos .NET dentro do 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.

Ativar na compilação

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, um punhado de regras de estilo de código ainda se aplicará somente no IDE do Visual Studio.)

Siga estas etapas para habilitar a análise de estilo de código na compilação:

  1. Defina a propriedade MSBuild EnforceCodeStyleInBuild como true.

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

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

    Gorjeta

    A partir do .NET 9, você também pode usar o formato de opção para especificar uma severidade e fazer com que ela seja respeitada 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, você pode configurar uma categoria inteira para ser um aviso ou erro, por padrão, e, em seguida, desativar seletivamente as regras nessa categoria que você não deseja executar na compilação. 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 é definir a opção de gravidade 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 avisos de análise de código.

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

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

Analisadores de terceiros

Além dos analisadores .NET oficiais, você também pode instalar analisadores de terceiros, como StyleCop, Roslynator, XUnit Analyzers e Sonar Analyzer.

Consulte também