Обзор анализа исходного кода .NETOverview of .NET source code analysis

Анализаторы компилятора .NET Platform (Roslyn) Analyzer проверяют код C# или Visual Basic для проблем качества кода и стиля..NET compiler platform (Roslyn) analyzers inspect your C# or Visual Basic code for code quality and style issues. Начиная с .NET 5,0 эти анализаторы входят в состав пакета SDK для .NET, и вам не нужно устанавливать их отдельно.Starting in .NET 5.0, these analyzers are included with the .NET SDK and you don't need to install them separately. Если проект предназначен для .NET 5 или более поздней версии, анализ кода включен по умолчанию.If your project targets .NET 5 or later, code analysis is enabled by default. Если проект предназначен для другой реализации .NET, например .NET Core, .NET Standard или платформа .NET Framework, необходимо вручную включить анализ кода, задав для свойства енабленетанализерс значение 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.

Если вы не хотите переходить на пакет SDK для .NET 5 +, иметь платформа .NET Framework проект без пакета SDK или предпочитаете модель на основе пакета NuGet, анализаторы также доступны в пакете NuGet Microsoft. CodeAnalysis. нетанализерс.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. Вы можете предпочесть модели на основе пакетов для обновления версий по требованию.You might prefer a package-based model for on-demand version updates.

Примечание

Анализаторы .NET являются независимыми от целевой платформы..NET analyzers are target-framework agnostic. То есть проект не обязан ориентироваться на конкретную реализацию .NET.That is, your project does not need to target a specific .NET implementation. Анализаторы работают для проектов, предназначенных для, а также для net5.0 более ранних версий .NET, таких как netcoreapp3.1 и net472 .The analyzers work for projects that target net5.0 as well as earlier .NET versions, such as netcoreapp3.1 and net472. Однако, чтобы включить анализ кода с помощью свойства енабленетанализерс , ваш проект должен ссылаться на пакет SDK проекта.However, to enable code analysis using the EnableNETAnalyzers property, your project must reference a project SDK.

Если анализатор обнаруживает нарушения правил, они включаются в отчет как предложение, предупреждение или ошибку в зависимости от того, как настроенокаждое правило.If rule violations are found by an analyzer, they're reported as a suggestion, warning, or error, depending on how each rule is configured. Нарушения анализа кода отображаются с префиксом "CA" или "IDE", чтобы отличать их от ошибок компилятора.Code analysis violations appear with the prefix "CA" or "IDE" to differentiate them from compiler errors.

Анализ качества кодаCode quality analysis

Правила анализа качества кода ("какскскскс") проверяют код C# или Visual Basic для обеспечения безопасности, производительности, проектирования и других проблем.Code quality analysis ("CAxxxx") rules inspect your C# or Visual Basic code for security, performance, design and other issues. По умолчанию для проектов, предназначенных для .NET 5,0 или более поздней версии, включен анализ.Analysis is enabled, by default, for projects that target .NET 5.0 or later. Вы можете включить анализ кода для проектов, предназначенных для более ранних версий .NET, задав для свойства енабленетанализерс значение true .You can enable code analysis on projects that target earlier .NET versions by setting the EnableNETAnalyzers property to true. Можно также отключить анализ кода для проекта, задав для значение EnableNETAnalyzers false .You can also disable code analysis for your project by setting EnableNETAnalyzers to false.

Совет

Если вы используете Visual Studio:If you're using Visual Studio:

  • Многие правила анализатора связаны с исправлениями кода , которые можно применить для устранения проблемы.Many analyzer rules have associated code fixes that you can apply to correct the problem. Исправления кода отображаются в меню значка лампочки.Code fixes are shown in the light bulb icon menu.
  • Можно включить или отключить анализ кода, щелкнув правой кнопкой мыши проект в Обозреватель решений и выбрав Свойства > вкладка анализ кода > включить анализаторы .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.

Включенные правилаEnabled rules

По умолчанию в .NET 5,0 включены следующие правила.The following rules are enabled, by default, in .NET 5.0.

ИД диагностикиDiagnostic ID КатегорияCategory СтатусSeverity ОписаниеDescription
CA1416CA1416 СовместимостьInteroperability ПредупреждениеWarning Анализатор совместимости платформPlatform compatibility analyzer
CA1417CA1417 СовместимостьInteroperability ПредупреждениеWarning Не используйте OutAttribute в строковых параметрах для P/InvokeDo not use OutAttribute on string parameters for P/Invokes
CA1831CA1831 ПроизводительностьPerformance ПредупреждениеWarning Используйте AsSpan вместо индексаторов на основе диапазона для строки, если это уместноUse AsSpan instead of range-based indexers for string when appropriate
CA2013CA2013 НадежностьReliability ПредупреждениеWarning Не используйте ReferenceEquals с типами значенийDo not use ReferenceEquals with value types
CA2014CA2014 НадежностьReliability ПредупреждениеWarning Не используйте stackalloc в циклахDo not use stackalloc in loops
CA2015CA2015 НадежностьReliability ПредупреждениеWarning Не определяйте методы завершения для типов, производных от MemoryManager<T>Do not define finalizers for types derived from MemoryManager<T>
CA2200CA2200 ИспользованиеUsage ПредупреждениеWarning Повторно порождайте исключения для сохранения сведений стекаRethrow to preserve stack details
CA2247CA2247 ИспользованиеUsage ПредупреждениеWarning Аргумент, переданный в конструктор TaskCompletionSource, должен быть TaskCreationOptions перечислением, а не TaskContinuationOptionsArgument passed to TaskCompletionSource constructor should be TaskCreationOptions enum instead of TaskContinuationOptions

Можно изменить серьезность этих правил, чтобы отключить их или повысить их уровень до ошибок.You can change the severity of these rules to disable them or elevate them to errors. Можно также включить дополнительные правила.You can also enable more rules.

Включить дополнительные правилаEnable additional rules

Режим анализа означает предопределенную конфигурацию анализа кода, в которой включены все правила, некоторые или все.Analysis mode refers to a predefined code analysis configuration where none, some, or all rules are enabled. В режиме анализа по умолчанию только небольшое количество правил включается в качестве предупреждений сборки.In the default analysis mode, only a small number of rules are enabled as build warnings. Можно изменить режим анализа для проекта, задав <AnalysisMode> свойство в файле проекта.You can change the analysis mode for your project by setting the <AnalysisMode> property in the project file. Допустимые значения:The allowable values are:

ЗначениеValue ОписаниеDescription
AllDisabledByDefault Это наиболее консервативный режим.This is the most conservative mode. По умолчанию все правила отключены.All rules are disabled by default. Можно выборочно принять отдельные правила, чтобы включить их.You can selectively opt into individual rules to enable them.

<AnalysisMode>AllDisabledByDefault</AnalysisMode>
AllEnabledByDefault Это самый агрессивный режим.This is the most aggressive mode. Все правила включены как предупреждения сборки.All rules are enabled as build warnings. Можно выборочно отказаться от отдельных правил, чтобы отключить их.You can selectively opt out of individual rules to disable them.

<AnalysisMode>AllEnabledByDefault</AnalysisMode>
Default Режим по умолчанию, где несколько правил включены как предупреждения, другие включаются только в качестве предложений интегрированной среды разработки Visual Studio с соответствующими исправлениями кода, а остальные отключаются полностью.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. Вы можете выборочно принять или отказаться от отдельных правил, чтобы отключить их.You can selectively opt into or out of individual rules to disable them.

<AnalysisMode>Default</AnalysisMode>

Чтобы найти уровень серьезности по умолчанию для каждого доступного правила и определить, включено ли правило в режиме анализа по умолчанию, см. полный список правил.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.

Рассматривать предупреждения как ошибкиTreat warnings as errors

При использовании -warnaserror флага при построении проектов все предупреждения анализа кода также обрабатываются как ошибки.If you use the -warnaserror flag when you build your projects, all code analysis warnings are also treated as errors. Если вы не хотите, чтобы предупреждения качества кода обрабатывались как ошибки в присутствии -warnaserror , можно задать CodeAnalysisTreatWarningsAsErrors для свойства MSBuild значение false в файле проекта.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>

Вы по-прежнему увидите предупреждения анализа кода, но они не нарушат сборку.You'll still see any code analysis warnings, but they won't break your build.

Последние обновленияLatest updates

По умолчанию при обновлении до более новых версий пакета SDK для .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. Если вы не хотите этого делать, например, если вы хотите убедиться, что новые правила не включены или отключены, их можно переопределить одним из следующих способов.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:

  • Задайте AnalysisLevel для свойства MSBuild определенное значение, чтобы заблокировать предупреждения для этого набора.Set the AnalysisLevel MSBuild property to a specific value to lock the warnings to that set. При обновлении до более нового пакета SDK вы по-прежнему получаете исправления ошибок для этих предупреждений, но новые предупреждения не будут включены, а существующие предупреждения не будут отключены.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. Например, чтобы заблокировать набор правил для тех, которые поставляются с пакетом SDK для .NET версии 5,0, добавьте следующую запись в файл проекта.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>
    

    Совет

    Значение свойства по умолчанию AnalysisLevellatest , что означает, что вы всегда получаете последние правила анализа кода при переходе на более новые версии пакета SDK для .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.

    Дополнительные сведения и список возможных значений см. в разделе аналисислевел.For more information, and to see a list of possible values, see AnalysisLevel.

  • Установите пакет NuGet Microsoft. CodeAnalysis. нетанализерс для отделения обновлений правил от обновлений пакета SDK для .NET.Install the Microsoft.CodeAnalysis.NetAnalyzers NuGet package to decouple rule updates from .NET SDK updates. При установке пакета отключаются встроенные анализаторы SDK и создается предупреждение о сборке, если пакет SDK содержит более новую версию сборки анализатора, чем версия пакета 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.

Анализ в стиле кодаCode-style analysis

Правила анализа в стиле кода ("идекскскскс") позволяют определять и поддерживать единообразный стиль кода в базе кода.Code-style analysis ("IDExxxx") rules enable you to define and maintain consistent code style in your codebase. Параметры включения по умолчанию:The default enablement settings are:

  • Сборка из командной строки. по умолчанию для всех проектов .NET в сборках из командной строки отключен анализ в стиле кода.Command-line build: Code-style analysis is disabled, by default, for all .NET projects on command-line builds.

    Начиная с .NET 5,0, можно Включить анализ в стиле кода для сборкикак в командной строке, так и в Visual Studio.Starting in .NET 5.0, you can enable code-style analysis on build, both at the command line and inside Visual Studio. Нарушения стиля кода отображаются как предупреждения или ошибки с префиксом "IDE".Code style violations appear as warnings or errors with an "IDE" prefix. Это позволяет применять единообразные стили кода во время сборки.This enables you to enforce consistent code styles at build time.

  • Visual Studio: анализ в стиле кода включен по умолчанию для всех проектов .NET в Visual Studio в виде быстрых действий по оптимизации кода.Visual Studio: Code-style analysis is enabled, by default, for all .NET projects inside Visual Studio as code refactoring quick actions.

Полный список правил анализа в стиле кода см. в разделе правила стиля кода.For a full list of code-style analysis rules, see Code style rules.

Включить при сборкеEnable on build

С помощью пакета SDK для .NET 5,0 и более поздних версий можно включить анализ в стиле кода при построении из командной строки и в 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. (Однако по соображениям производительности некоторые правила стиля кода по-прежнему будут применяться только в интегрированной среде разработки Visual Studio.)(However, for performance reasons, a handful of code-style rules will still apply only in the Visual Studio IDE.)

Чтобы включить анализ в стиле кода для сборки, выполните следующие действия.Follow these steps to enable code-style analysis on build:

  1. Задайте для свойства MSBuild енфорцекодестилеинбуилд значение true .Set the MSBuild property EnforceCodeStyleInBuild to true.

  2. В editorconfig -файле Настройте каждое правило стиля кода "IDE", которое вы хотите запускать при сборке как предупреждение или ошибку.In an .editorconfig file, configure each "IDE" code style rule that you wish to run on build as a warning or an error. Пример:For example:

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

    Кроме того, можно настроить всю категорию как предупреждение или ошибку, по умолчанию, а затем выборочно отключить правила в этой категории, которые не нужно выполнять при сборке.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. Пример: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
    

Примечание

Функция анализа в стиле кода экспериментальна и может изменяться в выпусках .NET 5 и .NET 6.The code-style analysis feature is experimental and may change between the .NET 5 and .NET 6 releases.

Подавлять предупреждениеSuppress a warning

Одним из способов отключения нарушения правил является установка параметра серьезности для этого идентификатора правила none в файл EditorConfig.One way to suppress a rule violation is to set the severity option for that rule ID to none in an EditorConfig file. Пример:For example:

dotnet_diagnostic.CA1822.severity = none

Дополнительные сведения и другие способы отключения предупреждений см. в разделе Отключение предупреждений анализа кода.For more information and other ways to suppress warnings, see How to suppress code analysis warnings.

Сторонние анализаторыThird-party analyzers

Помимо официальных анализаторов .NET, можно также установить сторонние анализаторы, такие как StyleCop, Рослинатор, xUnit Analyzersи анализатор Sonar.In addition to the official .NET analyzers, you can also install third party analyzers, such as StyleCop, Roslynator, XUnit Analyzers, and Sonar Analyzer.

См. также разделSee also