Visão geral da análise de código-fonte do .NETOverview of .NET source code analysis

Analisadores de Roslyn (plataforma de compilador .NET) inspecionam seu código C# ou Visual Basic para problemas de qualidade de código e estilo..NET compiler platform (Roslyn) analyzers inspect your C# or Visual Basic code for code quality and style issues. A partir do .NET 5,0, esses analisadores estão incluídos no SDK do .NET e você não precisa instalá-los separadamente.Starting in .NET 5.0, these analyzers are included with the .NET SDK and you don't need to install them separately. Se o projeto for destinado ao .NET 5 ou posterior, a análise de código será habilitada por padrão.If your project targets .NET 5 or later, code analysis is enabled by default. 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 .If your project targets a different .NET implementation, for example, .NET Core, .NET Standard, or .NET Framework, you must manually enable code analysis by setting the EnableNETAnalyzers property to 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 NuGet, os analisadores também estarão disponíveis no pacote NuGet Microsoft. CodeAnalysis. Netanalyzers.If you don't want to move to the .NET 5+ SDK, have a non-SDK-style .NET Framework project, or prefer a NuGet package-based model, the analyzers are also available in the Microsoft.CodeAnalysis.NetAnalyzers NuGet package. Você pode preferir um modelo baseado em pacote para atualizações de versão sob demanda.You might prefer a package-based model for on-demand version updates.

Observação

Os analisadores .NET são independentes de estrutura de destino..NET analyzers are target-framework agnostic. Ou seja, seu projeto não precisa ter como destino uma implementação específica do .NET.That is, your project does not need to target a specific .NET implementation. Os analisadores funcionam para projetos direcionados net5.0 , bem como para versões anteriores do .net, como netcoreapp3.1 e net472 .The analyzers work for projects that target net5.0 as well as earlier .NET versions, such as netcoreapp3.1 and 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.However, to enable code analysis using the EnableNETAnalyzers property, your project must reference a project SDK.

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.If rule violations are found by an analyzer, they're reported as a suggestion, warning, or error, depending on how each rule is configured. Violações de análise de código aparecem com o prefixo "CA" ou "IDE" para diferenciá-las dos erros do compilador.Code analysis violations appear with the prefix "CA" or "IDE" to differentiate them from compiler errors.

Análise de qualidade de códigoCode quality analysis

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.Code quality analysis ("CAxxxx") rules inspect your C# or Visual Basic code for security, performance, design and other issues. A análise é habilitada, por padrão, para projetos direcionados ao .NET 5,0 ou posterior.Analysis is enabled, by default, for projects that target .NET 5.0 or later. Você pode habilitar a análise de código em projetos direcionados a versões anteriores do .NET definindo a propriedade EnableNETAnalyzers como true .You can enable code analysis on projects that target earlier .NET versions by setting the EnableNETAnalyzers property to true. Você também pode desabilitar a análise de código para seu projeto definindo EnableNETAnalyzers como false .You can also disable code analysis for your project by setting EnableNETAnalyzers to false.

Dica

Se você estiver usando o Visual Studio:If you're using Visual Studio:

  • Muitas regras do analisador têm correções de código associadas que você pode aplicar para corrigir o problema.Many analyzer rules have associated code fixes that you can apply to correct the problem. As correções de código são mostradas no menu de ícones de lâmpada.Code fixes are shown in the light bulb icon menu.
  • Você pode habilitar ou desabilitar a análise de código clicando com o botão direito do mouse em um projeto no Gerenciador de soluções e selecionando Propriedades > guia análise de código > habilitar analisadores .net.You can enable or disable code analysis by right-clicking on a project in Solution Explorer and selecting Properties > Code Analysis tab > Enable .NET analyzers.

Regras habilitadasEnabled rules

As regras a seguir estão habilitadas, por padrão, no .NET 5,0.The following rules are enabled, by default, in .NET 5.0.

ID do diagnósticoDiagnostic ID CategoriaCategory SeveridadeSeverity DescriçãoDescription
CA1416CA1416 InteroperabilidadeInteroperability AvisoWarning Analisador de compatibilidade de plataformaPlatform compatibility analyzer
CA1417CA1417 InteroperabilidadeInteroperability AvisoWarning Não usar OutAttribute em parâmetros de cadeia de caracteres para P/InvokesDo not use OutAttribute on string parameters for P/Invokes
CA1831CA1831 DesempenhoPerformance AvisoWarning Use AsSpan em vez de indexadores baseados em intervalo para cadeia de caracteres quando apropriadoUse AsSpan instead of range-based indexers for string when appropriate
CA2013CA2013 ConfiabilidadeReliability AvisoWarning Não usar ReferenceEquals com tipos de valorDo not use ReferenceEquals with value types
CA2014CA2014 ConfiabilidadeReliability AvisoWarning Não usar stackalloc em loopsDo not use stackalloc in loops
CA2015CA2015 ConfiabilidadeReliability AvisoWarning Não defina finalizadores para tipos derivados de MemoryManager<T>Do not define finalizers for types derived from MemoryManager<T>
CA2200CA2200 UsoUsage AvisoWarning Relançar para preservar detalhes da pilhaRethrow to preserve stack details
CA2247CA2247 UsoUsage AvisoWarning O argumento passado para o Construtor TaskCompletionSource deve ser TaskCreationOptions enum em vez de TaskContinuationOptionsArgument passed to TaskCompletionSource constructor should be TaskCreationOptions enum instead of TaskContinuationOptions

Você pode alterar a severidade dessas regras para desabilitá-las ou promovê-las para erros.You can change the severity of these rules to disable them or elevate them to errors. Você também pode habilitar mais regras.You can also enable more rules.

Habilitar regras adicionaisEnable additional rules

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.Analysis mode refers to a predefined code analysis configuration where none, some, or all rules are enabled. No modo de análise padrão, apenas um pequeno número de regras é habilitado como avisos de compilação.In the default analysis mode, only a small number of rules are enabled as build warnings. Você pode alterar o modo de análise para seu projeto definindo a <AnalysisMode> propriedade no arquivo de projeto.You can change the analysis mode for your project by setting the <AnalysisMode> property in the project file. Os valores permitidos são:The allowable values are:

ValorValue DescriçãoDescription
AllDisabledByDefault Esse é o modo mais conservador.This is the most conservative mode. Todas as regras são desabilitadas por padrão.All rules are disabled by default. Você pode optar seletivamente por regras individuais para habilitá-las.You can selectively opt into individual rules to enable them.

<AnalysisMode>AllDisabledByDefault</AnalysisMode>
AllEnabledByDefault Esse é o modo mais agressivo.This is the most aggressive mode. Todas as regras são habilitadas como avisos de compilação.All rules are enabled as build warnings. Você pode recusar seletivamente as regras individuais para desabilitá-las.You can selectively opt out of individual rules to disable them.

<AnalysisMode>AllEnabledByDefault</AnalysisMode>
Default O modo padrão, em que algumas regras são habilitadas como avisos, outras são habilitadas apenas como sugestões de IDE do Visual Studio com correções de código correspondentes e o restante é completamente desabilitado.The default mode, where a handful of rules are enabled as warnings, others are enabled only as Visual Studio IDE suggestions with corresponding code fixes, and the rest are disabled completely. Você pode aceitar ou recusar seletivamente as regras individuais para desabilitá-las.You can selectively opt into or out of individual rules to disable them.

<AnalysisMode>Default</AnalysisMode>

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.To find the default severity for each available rule and whether or not the rule is enabled in the default analysis mode, see the full list of rules.

Tratar avisos como errosTreat warnings as errors

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.If you use the -warnaserror flag when you build your projects, all code analysis warnings are also treated as errors. Se você não quiser que os avisos de qualidade de código (CAxxxx) sejam tratados como erros em presença de -warnaserror , você poderá definir a CodeAnalysisTreatWarningsAsErrors Propriedade do MSBuild como false no arquivo do projeto.If you do not want code quality warnings (CAxxxx) to be treated as errors in presence of -warnaserror, you can set the CodeAnalysisTreatWarningsAsErrors MSBuild property to false in your project file.

<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.You'll still see any code analysis warnings, but they won't break your build.

Atualizações mais recentesLatest updates

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.By default, you'll get the latest code analysis rules and default rule severities as you upgrade to newer versions of the .NET SDK. 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:If you don't want this behavior, for example, if you want to ensure that no new rules are enabled or disabled, you can override it in one of the following ways:

  • Defina a AnalysisLevel Propriedade MSBuild com um valor específico para bloquear os avisos para esse conjunto.Set the AnalysisLevel MSBuild property to a specific value to lock the warnings to that set. 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.When you upgrade to a newer SDK, you'll still get bug fixes for those warnings, but no new warnings will be enabled and no existing warnings will be disabled. 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.For example, to lock the set of rules to those that ship with version 5.0 of the .NET SDK, add the following entry to your project file.

    <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.The default value for the AnalysisLevel property is latest, which means you always get the latest code analysis rules as you move to newer versions of the .NET SDK.

    Para obter mais informações e ver uma lista de possíveis valores, consulte AnalysisLevel.For more information, and to see a list of possible values, see AnalysisLevel.

  • Instale o pacote NuGet Microsoft. CodeAnalysis. Netanalyzers para desassociar atualizações de regra das atualizações do SDK do .net.Install the Microsoft.CodeAnalysis.NetAnalyzers NuGet package to decouple rule updates from .NET SDK updates. A instalação do pacote desativa os analisadores internos do SDK e gera um aviso de compilação se o SDK contiver uma versão de assembly do analisador mais recente do que a do pacote NuGet.Installing the package turns off the built-in SDK analyzers and generates a build warning if the SDK contains a newer analyzer assembly version than that of the NuGet package.

Análise de estilo de códigoCode-style analysis

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.Code-style analysis ("IDExxxx") rules enable you to define and maintain consistent code style in your codebase. As configurações de habilitação padrão são:The default enablement settings are:

  • 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.Command-line build: Code-style analysis is disabled, by default, for all .NET projects on command-line builds.

    A partir do .NET 5,0, você pode habilitar a análise de estilo de código no Build, tanto na linha de comando quanto dentro do Visual Studio.Starting in .NET 5.0, you can enable code-style analysis on build, both at the command line and inside Visual Studio. Violações de estilo de código aparecem como avisos ou erros com um prefixo "IDE".Code style violations appear as warnings or errors with an "IDE" prefix. Isso permite que você imponha estilos de código consistentes no momento da compilação.This enables you to enforce consistent code styles at build time.

  • Visual Studio: a análise de estilo de código está habilitada, por padrão, para todos os projetos .NET dentro do Visual Studio como ações rápidas de refatoração de código.Visual Studio: Code-style analysis is enabled, by default, for all .NET projects inside Visual Studio as code refactoring quick actions.

Para obter uma lista completa de regras de análise de estilo de código, consulte regras de estilo de código.For a full list of code-style analysis rules, see Code style rules.

Habilitar no BuildEnable on build

Com o SDK do .NET 5,0 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.With the .NET 5.0 SDK and later versions, you can enable code-style analysis when building from the command-line and in 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.)(However, for performance reasons, a handful of code-style rules will still apply only in the Visual Studio IDE.)

Siga estas etapas para habilitar a análise de estilo de código na compilação:Follow these steps to enable code-style analysis on build:

  1. Defina a propriedade EnforceCodeStyleInBuild do MSBuild como true .Set the MSBuild property EnforceCodeStyleInBuild to 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.In an .editorconfig file, configure each "IDE" code style rule that you wish to run on build as a warning or an error. Por exemplo:For example:

    [*.{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.Alternatively, you can configure an entire category to be a warning or error, by default, and then selectively turn off rules in that category that you don't want to run on build. Por exemplo:For example:

    [*.{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.The code-style analysis feature is experimental and may change between the .NET 5 and .NET 6 releases.

Suprimir um avisoSuppress a warning

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.One way to suppress a rule violation is to set the severity option for that rule ID to none in an EditorConfig file. Por exemplo:For example:

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.For more information and other ways to suppress warnings, see How to suppress code analysis warnings.

Analisadores de terceirosThird-party analyzers

Além dos analisadores .NET oficiais, você também pode instalar analisadores de terceiros, como StyleCop, Roslynator, analisadores de xUnite o analisador de sonar.In addition to the official .NET analyzers, you can also install third party analyzers, such as StyleCop, Roslynator, XUnit Analyzers, and Sonar Analyzer.

Consulte tambémSee also