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

analisadores de Roslyn (plataforma de compilador .net) inspecionam seu código C# ou Visual Basic para problemas de qualidade de código e estilo. 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 projeto for destinado ao .NET 5 ou posterior, a análise de código será habilitada por padrão. se o seu projeto se destina a 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 migrar para o sdk do .net 5 +, tiver um projeto de .NET Framework de estilo não-SDK ou preferir um modelo baseado em pacote de NuGet, os analisadores também estarão disponíveis no pacote Microsoft. CodeAnalysis. netanalyzers NuGet. Você pode preferir um modelo baseado em pacote para atualizações de versão sob demanda.

Observação

Os analisadores .NET são independentes de estrutura de destino. Ou seja, seu projeto não precisa ter como destino uma implementação específica do .NET. Os analisadores funcionam para projetos direcionados net5.0 , bem como para versões anteriores do .net, como netcoreapp3.1 e net472 . 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 regra forem encontradas por um analisador, elas serão relatadas como uma sugestão, aviso ou erro, dependendo de como cada regra é configurada. 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 em C# ou Visual Basic para fins 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 direcionados 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 .

Dica

se você estiver usando 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âmpada.

Regras habilitadas

As regras a seguir estão habilitadas, por padrão, no .NET 6.

ID do diagnóstico Categoria Severidade Descrição
CA1416 Interoperabilidade Aviso Analisador de compatibilidade de plataforma
CA1417 Interoperabilidade Aviso Não usar OutAttribute em parâmetros de cadeia de caracteres para P/Invokes
CA1418 Interoperabilidade Aviso Usar cadeia de caracteres de plataforma válida
CA1831 Desempenho Aviso Use AsSpan em vez de indexadores baseados em intervalo para cadeia de caracteres quando apropriado
CA2013 Confiabilidade Aviso Não usar ReferenceEquals com tipos de valor
CA2014 Confiabilidade Aviso Não usar stackalloc em loops
CA2015 Confiabilidade Aviso Não defina finalizadores para tipos derivados de MemoryManager<T>
CA2017 Confiabilidade Aviso Incompatibilidade de contagem de parâmetros
CA2018 Confiabilidade Aviso O count argumento para Buffer.BlockCopy deve especificar o número de bytes a serem copiados
CA2200 Uso Aviso Relançar para preservar detalhes da pilha
CA2252 Uso Erro Aceitar recursos de visualização
CA2247 Uso Aviso O argumento passado para o TaskCompletionSource Construtor deve ser TaskCreationOptions enum em vez de TaskContinuationOptions
CA2255 Uso Aviso O ModuleInitializer atributo não deve ser usado em bibliotecas
CA2256 Uso Aviso Todos os membros declarados em interfaces pai devem ter uma implementação em uma DynamicInterfaceCastableImplementation interface atribuída
CA2257 Uso Aviso Os membros definidos em uma interface com o DynamicInterfaceCastableImplementationAttribute devem ser static
CA2258 Uso Aviso DynamicInterfaceCastableImplementationnão há suporte para fornecer uma interface no Visual Basic

Você pode alterar a severidade dessas regras para desabilitá-las ou promovê-las para erros. Você também pode 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, 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:

None

Default

Minimum

Recommended

All

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 recomendado de regras para a versão mais recente: <AnalysisLevel>latest-Recommended</AnalysisLevel> . Para obter mais informações, consulte AnalysisLevel.

Para localizar a severidade padrão de cada regra disponível e se a regra está habilitada ou não no modo de análise padrão, consulte a lista completa de regras.

Tratar avisos como erros

Se você usar o -warnaserror sinalizador ao compilar 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 em presença de -warnaserror , você pode definir a CodeAnalysisTreatWarningsAsErrors propriedade MSBuild como false no arquivo do projeto.

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

Você ainda verá quaisquer avisos de análise de código, mas eles não interromperã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 regra padrão ao atualizar para versões mais recentes do SDK do .NET. Se você não quiser esse comportamento, por exemplo, se quiser garantir que nenhuma regra nova seja habilitada ou desabilitada, você poderá substituí-la de uma das seguintes maneiras:

  • defina a AnalysisLevel propriedade MSBuild como um valor específico para bloquear os avisos para esse conjunto. Ao atualizar para um SDK mais recente, você ainda obterá 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 as que acompanham 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 AnalysisLevel propriedade é latest , o que significa que você sempre Obtém as últimas regras de análise de código à medida que passa para versões mais recentes do SDK do .net.

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

  • instale o pacote Microsoft. CodeAnalysis. netanalyzers NuGet para desassociar atualizações de regra das atualizações do SDK do .net. Para projetos direcionados ao .NET 5 +, a instalação do pacote desativa os analisadores integrados do SDK. 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 de NuGet. Para desabilitar o aviso, defina a _SkipUpgradeNetAnalyzersNuGetWarning propriedade como true .

    Observação

    se você instalar o pacote Microsoft. CodeAnalysis. netanalyzers NuGet, não deverá adicionar a propriedade EnableNETAnalyzers ao arquivo de projeto ou a um arquivo Directory. Build. props . quando o pacote de 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 o estilo de código consistente na codebase. As configurações de habilitação padrão são:

  • Compilação de linha de comando: a análise de estilo de código está 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 no Build, tanto na linha de comando quanto dentro de Visual Studio. 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 está habilitada, por padrão, para todos os projetos .net dentro de 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 em Visual Studio. (no entanto, por motivos de desempenho, algumas regras de estilo de código ainda serão aplicadas somente no IDE Visual Studio.)

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

  1. defina a propriedade de 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
    

    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
    

Observação

O recurso de análise de estilo de código é experimental e pode mudar entre as versões do .NET 5 e do .NET 6.

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 GitHub

a ação de GitHub dotnet/análise de código 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 de GitHub de análise de código .net.

Analisadores de terceiros

Além dos analisadores .NET oficiais, você também pode instalar analisadores de terceiros, como StyleCop, Roslynator, analisadores de xUnite o analisador de sonar.

Confira também