Обзор анализа исходного кода .NET

  • Статья

Анализаторы .NET Compiler Platform (Roslyn) проверяют код C# или Visual Basic на наличие проблем с качеством и стилем. Начиная с .NET 5, эти анализаторы включены в пакет SDK для .NET. Их не нужно устанавливать отдельно. Если ваш проект предназначен для .NET 5 или более поздней версии, анализ кода будет включен по умолчанию. Если ваш проект предназначен для другой реализации .NET, например .NET Core, .NET Standard или .NET Framework, необходимо вручную включить анализ кода, установив для свойства EnableNETAnalyzers значение true.

Если вы не хотите переходить на использование пакета SDK для .NET 5+, работаете с проектом, стиль которого отличается от стиля пакета SDK для .NET Framework, или предпочитаете использовать модель на основе пакетов NuGet, тогда вы можете воспользоваться анализаторами, которые также доступны в пакете NuGet Microsoft.CodeAnalysis .NetAnalyzers. Возможно, вы предпочтете модель на основе пакета для обновлений версий по требованию.

Примечание.

Анализаторы .NET не зависят от целевой платформы. То есть при работе с проектом не нужно ориентироваться на конкретную реализацию .NET. Анализаторы можно использовать для проектов, предназначенных для .NET 5+, а также для более ранних версий .NET, таких как .NET Core 3.1 и .NET Framework 4.7.2. Однако для включения анализа кода с помощью свойства EnableNETAnalyzers ваш проект должен содержать ссылку на пакет SDK проекта.

Если анализатор обнаруживает нарушения правил, он отправляет о них оповещение в виде предложения, предупреждения или ошибки, в зависимости от настройки каждого правила. Нарушения анализа кода появляются с префиксом CA или IDE. Этот префикс отличает их от ошибок компилятора.

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

Правила анализа качества кода (CAxxxx) проверяют код C# или Visual Basic на наличие проблем с безопасностью, производительностью, дизайном и т. д. По умолчанию анализ включен для проектов, предназначенных для .NET 5 или более поздних версий. Вы можете включить анализ кода для проектов, предназначенных для более ранних версий .NET, задав для свойства EnableNETAnalyzers значение true. Кроме того, вы можете отключить анализ кода для своего проекта, установив для EnableNETAnalyzers значение false.

Совет

В Visual Studio многие правила анализатора связаны с исправлениями кода, которые можно применить для устранения проблемы. Исправления кода показаны в меню со значком лампочки.

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

Следующие правила включены по умолчанию в виде ошибок или предупреждений в .NET 8. Дополнительные правила включены в качестве предложений.

ИД диагностики Категория Важность Добавлено в версии Description
CA1416 Совместимость Предупреждение .NET 5 Проверка совместимости платформ
CA1417 Совместимость Предупреждение .NET 5 Не используйте OutAttribute в параметрах строки для P/Invokes
CA1418 Совместимость Предупреждение .NET 6 Использование допустимой строки платформы
CA1420 Совместимость Предупреждение .NET 7 Использование функций, требующих маршаллинга среды выполнения при отключении, приведет к исключениям во время выполнения
CA1422 Совместимость Предупреждение .NET 7 Проверка совместимости платформ
CA1831 Производительность Предупреждение .NET 5 При необходимости используйте AsSpan вместо индексаторов на основе диапазона для строки
CA1856 Производительность Ошибка .NET 8 Неправильное использование атрибута ConstantExpected
CA1857 Производительность Предупреждение .NET 8 Ожидается константа для параметра
CA2013 Надежность Предупреждение .NET 5 Не используйте ReferenceEquals с типами значений
CA2014 Надежность Предупреждение .NET 5 Не используйте stackalloc в циклах
CA2015 Надежность Предупреждение .NET 5 Не определяйте методы завершения для типов, производных от MemoryManager<T>
CA2017 Надежность Предупреждение .NET 6 Несоответствие количества параметров
CA2018 Надежность Предупреждение .NET 6 Аргумент count в Buffer.BlockCopy должен задавать число байт копирования
CA2021 Надежность Предупреждение .NET 8 Не вызывайте или Enumerable.OfType<T> не вызывайте Enumerable.Cast<T> несовместимые типы
CA2200 Использование Предупреждение .NET 5 Повторно порождайте исключения для сохранения сведений стека
CA2247 Использование Предупреждение .NET 5 Аргумент, передаваемый конструктору TaskCompletionSource, должен иметь значение перечисления TaskCreationOptions вместо TaskContinuationOptions
CA2252 Использование Ошибка .NET 6 Согласие на использование предварительных версий функций
CA2255 Использование Предупреждение .NET 6 Атрибут ModuleInitializer не должен использоваться в библиотеках
CA2256 Использование Предупреждение .NET 6 У всех элементов, объявленных в родительских интерфейсах, должна быть реализация в интерфейсе с атрибутом DynamicInterfaceCastableImplementation
CA2257 Использование Предупреждение .NET 6 Члены, определенные в интерфейсе с DynamicInterfaceCastableImplementationAttribute, должны иметь значение static
CA2258 Использование Предупреждение .NET 6 Предоставление интерфейса DynamicInterfaceCastableImplementation в Visual Basic не поддерживается
CA2259 Использование Предупреждение .NET 7 ThreadStatic влияет только на статические поля
CA2260 Использование Предупреждение .NET 7 Использование правильного параметра типа
CA2261 Использование Предупреждение .NET 8 Не используйте ConfigureAwaitOptions.SuppressThrowing с Task<TResult>

Вы можете изменить важность этих правил, чтобы отключить их или повысить их до уровня ошибок. Вы также можете включить большее количество правил.

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

Режим анализа относится к предопределенной конфигурации анализа кода, в которой правила отключены или включены (несколько или все). В режиме анализа по умолчанию (Default) в качестве предупреждений сборки включены только небольшое количество правил. Вы можете изменить режим анализа для своего проекта, установив свойство <AnalysisMode> в файле проекта. Допустимые значения:

значение Описание
None Все правила отключены. Можно выборочно принять отдельные правила, чтобы включить их.
Default Режим по умолчанию, при котором определенные правила включаются в виде предупреждений сборки, некоторые правила включаются в качестве предложений интегрированной среды разработки Visual Studio, а остальные отключаются.
Minimum Более агрессивный режим, чем Default режим. Определенные предложения, которые настоятельно рекомендуются для принудительного применения сборки, включены как предупреждения сборки. Чтобы узнать, какие правила включаются, проверьте файл %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.editorconfig file.
Recommended Более агрессивный режим, чем Minimum режим, где в качестве предупреждений сборки включены дополнительные правила. Чтобы узнать, какие правила включаются, проверьте файл %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.editorconfig-файл .
All Все правила включены в качестве предупреждений сборки*. Вы можете выборочно отказаться от отдельных правил, чтобы отключить их.

* Следующие правила не включены с помощью параметров AllAnalysisMode или параметров AnalysisLevellatest-all: CA1017, CA1045, CA1005, CA1014, CA1060, CA1021 и правил анализатора метрик кода (CA1501, CA1502, CA1505, CA1506 и CA1509). Эти устаревшие правила могут быть устаревшими в будущей версии. Однако их можно включить по отдельности dotnet_diagnostic.CAxxxx.severity = <severity> с помощью записи.

Начиная с .NET 6, можно опустить <AnalysisMode> в пользу составного значения для свойства <AnalysisLevel>. Например, следующее значение включает рекомендуемый набор правил для последнего выпуска: <AnalysisLevel>latest-Recommended</AnalysisLevel>. Дополнительные сведения см. в разделе AnalysisLevel.

Чтобы найти уровень серьезности по умолчанию для каждого доступного правила и включить ли правило в Default режиме анализа, см . полный список правил.

Обработка предупреждений как ошибок

Если вы используете флажок -warnaserror при сборке проектов, все предупреждения анализа кода также обрабатываются как ошибки. Если вы не хотите, чтобы предупреждения о качестве кода (CAxxxx) рассматривались как ошибки при наличии -warnaserror, вы можете установить для свойства MSBuild CodeAnalysisTreatWarningsAsErrors значение false в файле проекта.

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

Предупреждения анализа кода будут отображаться по-прежнему, но при этом они не будут нарушать сборку.

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

По умолчанию вы будете получать последние правила анализа кода и стандартные уровни важности правил при обновлении до более новых версий пакета SDK для .NET. Если такое поведение вас не устраивает, например, если вы хотите убедиться, что новые правила включены или отключены, вы можете переопределить его одним из следующих способов:

  • Задайте для свойства MSBuild AnalysisLevel определенное значение, чтобы заблокировать предупреждения для этого набора. При обновлении до более новой версии пакета SDK вы по-прежнему будете получать исправления ошибок для этих предупреждений, однако новые предупреждения не будут включены, а существующие не будут отключены. Например, чтобы заблокировать набор правил для предупреждений, поставляемых с версией 5.0 пакета SDK для .NET, добавьте приведенную ниже запись в файл проекта.

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

    Совет

    Значение по умолчанию для свойства AnalysisLevel — latest. Это означает, что вы всегда получаете последние правила анализа кода при переходе к использованию более новых версий пакета SDK для .NET.

    Дополнительные сведения и список возможных значений см. на странице AnalysisLevel.

  • Установите пакет NuGet Microsoft.CodeAnalysis.NetAnalyzers, чтобы отделить обновления правил от обновлений пакета SDK для .NET. Для проектов, предназначенных для .NET 5+, при установке пакета отключаются встроенные анализаторы SDK. Вы получите предупреждение о сборке, если пакет SDK содержит более новую версию сборки анализатора, чем пакет NuGet. Чтобы отключить предупреждение, установите для свойства _SkipUpgradeNetAnalyzersNuGetWarning значение true.

    Примечание.

    При установке пакета NuGet Microsoft.CodeAnalysis.NetAnalyzers не нужно добавлять свойство EnableNETAnalyzers в файл проекта или в файл Directory.Build.props. После установки пакета NuGet и задания для свойства EnableNETAnalyzers значения true создастся предупреждение сборки.

Анализ стиля кода

Правила анализа стиля кода (IDExxxx) позволяют определять и поддерживать согласованный стиль кода в базе кода. Параметры включения по умолчанию:

  • Сборка из командной строки: анализ стиля кода по умолчанию отключен для всех проектов .NET при сборке из командной строки.

    Начиная с .NET 5 вы можете включить анализ стиля кода при сборке как в командной строке, так и внутри Visual Studio. Нарушения стиля кода отображаются в виде предупреждений или ошибок с префиксом IDE. Это позволяет вам применять согласованные стили кода во время сборки.

  • Visual Studio: анализ стиля кода включен по умолчанию для всех проектов .NET внутри Visual Studio в виде быстрых действий по рефакторингу кода.

Полный список правил анализа стиля кода см. на этой странице.

Включение при сборке

С помощью пакета SDK для .NET 5 и более поздних версий вы можете включить анализ стиля кода при сборке из командной строки и в Visual Studio. (Однако по соображениям производительности некоторые правила стиля кода по-прежнему будут применяться только в IDE Visual Studio.)

Выполните следующие действия, чтобы включить анализ стиля кода при сборке:

  1. Установите для свойства MSBuild EnforceCodeStyleInBuild значение true.

  2. В файле .editorconfigнастройте каждое правило стиля кода с префиксом IDE, которое вы хотите запускать при сборке как предупреждение или ошибку. Например:

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

    Совет

    Начиная с .NET 9, можно также использовать формат параметра для указания серьезности и соблюдения его во время сборки. Например:

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

    Кроме того, вы можете настроить всю категорию как предупреждение или ошибку по умолчанию, а затем выборочно отключить правила в этой категории, которые не нужно запускать при сборке. Например:

    [*.{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

Отключение предупреждений

Один из способов пропустить нарушение правила — установить для параметра важности этого идентификатора правила значение none в файле EditorConfig. Например:

dotnet_diagnostic.CA1822.severity = none

Дополнительные сведения и другие способы отключения предупреждений см. на этой странице.

Выполнение анализа кода как GitHub Actions

Экземпляр GitHub Actions dotnet/code-analysis позволяет запускать анализаторы кода .NET в рамках непрерывной интеграции (CI) в автономном режиме. Дополнительные сведения см. в разделе Анализ кода в .NET с помощью GitHub Actions.

Сторонние анализаторы

Помимо официальных анализаторов .NET, вы также можете установить сторонние анализаторы, такие как StyleCop, Roslynator, XUnit Analyzers и Sonar Analyzer.

См. также