Обзор

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

Настройка уровней серьезности

Начиная с Visual Studio 2019 версии 16.3, можно настроить серьезность правил анализатора или диагностика в файле EditorConfig в меню лампочки и списке ошибок.

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

Уровень серьезности (Обозреватель решений) Уровень серьезности (файл EditorConfig) Поведение при сборке Поведение редактора
Ошибка error Нарушения отображаются как ошибки в списке ошибок и в выходных данных сборки из командной строки и приводят к сбою сборок. Соответствующий код ошибки подчеркнут красной волнистой линией и отмечен небольшой красной рамкой в полосе прокрутки.
Предупреждение warning Нарушения отображаются как предупреждения в списке ошибок и в выходных данных сборки из командной строки, но не приводят к сбою сборок. Соответствующий код подчеркнут зеленой волнистой линией и отмечен небольшой зеленой рамкой в полосе прокрутки.
Сведения suggestion Нарушения отображаются как сообщения в списке ошибок и отсутствуют в выходных данных сборки из командной строки. Соответствующий код подчеркнут серой волнистой линией и отмечен небольшой серой рамкой в полосе прокрутки.
Скрыт silent Невидимая для пользователя. Невидимая для пользователя. Тем не менее данные диагностики передаются в обработчик диагностики IDE.
нет none Полностью подавляется. Полностью подавляется.
По умолчанию. default Соответствует стандартному уровню серьезности правила. Чтобы определить, что такое значение по умолчанию для правила, просмотрите окно свойств. Соответствует стандартному уровню серьезности правила.

Нарушения правил, обнаруженные анализатором, отображаются в редакторе кода (как волнистый элемент в коде обиженного кода) и в окне списка ошибок анализатором.

Нарушения анализаторов, приведенные в списке ошибок, соответствуют уровню серьезности правила. Нарушения анализаторов выделяются в редакторе кода с помощью волнистых линий под соответствующим кодом. На следующем рисунке показаны три нарушения: одна ошибка (красная волнистая линия), одно предупреждение (зеленый волнистый цвет), а также одно предложение (три серые точки):

Squiggles in the code editor in Visual Studio

На следующем снимке экрана показаны те же три нарушения, что и в списке ошибок:

Error, warning, and info violation in Error List

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

Analyzer violation and Quick Action code fix

Уровень серьезности "Скрытый" и "Нет"

Hidden Правила серьезности, включенные по умолчанию, отличаются от отключенных или None правил серьезности в определенных аспектах.

Установка серьезности правил в файле EditorConfig

(Visual Studio 2019 версии 16.3 и более поздних версий)

Вы можете задать серьезность для предупреждений компилятора или правил анализатора в файле EditorConfig со следующим синтаксисом:

dotnet_diagnostic.<rule ID>.severity = <severity>

Задание серьезности правила в файле EditorConfig имеет приоритет над любой серьезностью, заданной в наборе правил или в Обозреватель решений. Вы можете вручную настроить серьезность в файле EditorConfig или автоматически с помощью лампочки, которая отображается рядом с нарушением.

Настройка серьезности правил нескольких правил анализатора одновременно в файле EditorConfig

(Visual Studio 2019 версии 16.5 и более поздних версий)

Можно задать серьезность для определенной категории правил анализатора или для всех правил анализатора с одной записью в файле EditorConfig.

  • Задайте уровень серьезности правил для категории правил анализатора:

dotnet_analyzer_diagnostic.category-<rule category>.severity = <severity>

  • Задайте уровень серьезности правил для всех правил анализатора:

dotnet_analyzer_diagnostic.severity = <severity>

Примечание.

Записи для настройки нескольких правил анализатора одновременно применяются только к правилам, включенным по умолчанию. Правила анализатора, помеченные как отключенные по умолчанию в пакете анализатора, должны быть включены с помощью явных dotnet_diagnostic.<rule ID>.severity = <severity> записей.

Если у вас несколько записей, применимых к определенному идентификатору правила, порядок приоритета для соответствующей записи следует:

  • Запись серьезности для отдельного правила по идентификатору имеет приоритет над записью серьезности для категории.
  • Запись серьезности для категории имеет приоритет над записью серьезности для всех правил анализатора.

Рассмотрим следующий пример EditorConfig, где CA1822 имеет категорию "Производительность":

[*.cs]
dotnet_diagnostic.CA1822.severity = error
dotnet_analyzer_diagnostic.category-performance.severity = warning
dotnet_analyzer_diagnostic.severity = suggestion

В предыдущем примере все три записи применяются к CA18222. Однако при использовании указанных правил приоритета первая запись серьезности на основе идентификатора правила выигрывает над следующими записями. В этом примере CA1822 имеет эффективную серьезность ошибки. Остальные правила с категорией "Производительность" имеют серьезность "предупреждение", а правила анализатора, у которых нет категории "Производительность", имеют серьезность "предложение".

Настройка серьезности правил вручную в файле EditorConfig

  1. Если у вас еще нет файла EditorConfig для проекта, добавьте его.

  2. Добавьте запись для каждого правила, которое требуется настроить в соответствующем расширении файла. Например, чтобы задать уровень серьезности для CA1822 дляerror файлов C#, запись выглядит следующим образом:

    [*.cs]
    dotnet_diagnostic.CA1822.severity = error
    

Примечание.

Для анализаторов в стиле кода интегрированной среды разработки их также можно настроить в файле EditorConfig с помощью другого синтаксиса, например dotnet_style_qualification_for_field = false:suggestion. Однако если задать серьезность с помощью синтаксиса dotnet_diagnostic , он имеет приоритет. Дополнительные сведения см. в разделе "Языковые соглашения" для EditorConfig.

Настройка серьезности правил в меню лампочки

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

  1. После нарушения наведите указатель мыши на значок нарушения в редакторе и выберите "Показать потенциальные исправления ", чтобы открыть меню лампочки. Или поместите курсор на строку и нажмите клавиши CTRL+ (период).

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

    • Настройка <серьезности идентификатора> правила— задание серьезности для конкретного правила.
    • Настройте серьезность для всех анализаторов стилей. Задайте уровень серьезности для всех <правил в определенной категории правил.>
    • Настройка серьезности для всех анализаторов — настройка серьезности для всех категорий правил анализатора.

    В следующем примере выберите "Настройка" или "Отключить проблемы>", чтобы настроить <серьезность идентификатора> правила.

    Configure rule severity from light bulb menu in Visual Studio

    Configure rule severity from light bulb menu in Visual Studio

  3. Выберите один из вариантов серьезности.

    Configure rule severity as Suggestion

    Configure rule severity as Suggestion

    Visual Studio добавляет запись в файл EditorConfig, чтобы настроить правило на запрошенный уровень, как показано в поле предварительного просмотра.

    Совет

    Если в проекте еще нет файла EditorConfig, Visual Studio создает его для вас.

Настройка серьезности правил в окне списка ошибок

Visual Studio также предоставляет удобный способ настройки серьезности правила в контекстном меню списка ошибок.

  1. После нарушения щелкните правой кнопкой мыши запись диагностики в списке ошибок.

  2. В контекстном меню выберите "Задать серьезность".

    Configure rule severity from error list in Visual Studio

  3. Выберите один из вариантов серьезности.

    Visual Studio добавляет запись в файл EditorConfig, чтобы настроить правило на запрошенный уровень.

    Совет

    Если в проекте еще нет файла EditorConfig, Visual Studio создает его для вас.

Установка серьезности правил из Обозреватель решений

Вы можете выполнить большую часть настройки анализатора диагностика из Обозреватель решений. Если вы устанавливаете анализаторы в виде пакета NuGet, узел анализаторов отображается в узле "Ссылки" или "Зависимости" в Обозреватель решений. Если развернуть анализаторы, а затем развернуть одну из сборок анализатора, вы увидите все диагностика в сборке.

Analyzers node in Solution Explorer

Свойства диагностики, включая описание и серьезность по умолчанию, можно просмотреть в окне "Свойства ". Чтобы просмотреть свойства, щелкните правой кнопкой мыши правило и выберите пункт "Свойства" или выберите правило, а затем нажмите клавиши ALT+ВВОД.

Diagnostic properties in Properties window

Чтобы просмотреть документацию по сети для диагностики, щелкните правой кнопкой мыши диагностику и выберите команду "Просмотреть справку".

Значки рядом с каждой диагностикой в Обозреватель решений соответствуют значкам, которые отображаются в наборе правил при открытии в редакторе:

Diagnostics icons in Solution Explorer

Примечание.

Чтобы просмотреть свойства правил стиля кода (префикс интегрированной среды разработки) в окно свойств, например серьезность по умолчанию, задайте для свойства EnforceCodeStyleInBuild значение true.

Преобразование существующего файла набора правил в файл EditorConfig

Начиная с Visual Studio 2019 версии 16.5 файлы наборов правил устарели в пользу файла EditorConfig для конфигурации анализатора для управляемого кода. Большинство средств Visual Studio для настройки серьезности правил анализатора обновляются для работы с файлами EditorConfig вместо файлов набора правил. Файлы EditorConfig позволяют настроить как серьезность правил анализатора, так и параметры анализатора, включая параметры стиля кода интегрированной среды разработки Visual Studio. Мы рекомендуем преобразовать существующий файл набора правил в файл EditorConfig. Кроме того, сохраните файл EditorConfig в корне репозитория или в папке решения. Используя корневой каталог репозитория или папки решения, убедитесь, что параметры серьезности из этого файла автоматически применяются ко всему репозиторию или решению соответственно.

Существует несколько способов преобразования существующего файла набора правил в файл EditorConfig:

  • В редакторе наборов правил в Visual Studio (требуется Visual Studio 2019 16.5 или более поздней версии). Если в проекте уже используется определенный файл CodeAnalysisRuleSetнабора правил, его можно преобразовать в эквивалентный файл EditorConfig из редактора правил в Visual Studio.

    1. Дважды щелкните файл набора правил в Обозреватель решений.

      Файл набора правил должен открыться в редакторе набора правил. В верхней части редактора набора правил появится панель сведений с возможностью щелчка.

      Convert Ruleset to EditorConfig file in Ruleset Editor

    2. Выберите ссылку на информационную панель .

      Действие должно открыть диалоговое окно "Сохранить как ", которое позволяет выбрать каталог, в котором нужно создать файл EditorConfig.

    3. Нажмите кнопку "Сохранить", чтобы создать файл EditorConfig.

      Созданная конфигурация EditorConfig должна открыться в редакторе. Кроме того, свойство CodeAnalysisRuleSet MSBuild обновляется в файле проекта, чтобы он больше не ссылался на исходный файл набора правил.

  • Из командной строки.

    1. Установите пакет NuGet Microsoft.CodeAnalysis.RulesetToEditorconfigConverter.

    2. Выполнение RulesetToEditorconfigConverter.exe из установленного пакета с путями к файлу набора правил и файлу EditorConfig в качестве аргументов командной строки.

    Usage: RulesetToEditorconfigConverter.exe <%ruleset_file%> [<%path_to_editorconfig%>]
    

Ниже приведен пример файла набора правил для преобразования:

<?xml version="1.0" encoding="utf-8"?>
<RuleSet Name="Rules for ConsoleApp" Description="Code analysis rules for ConsoleApp.csproj." ToolsVersion="16.0">
  <Rules AnalyzerId="Microsoft.Analyzers.ManagedCodeAnalysis" RuleNamespace="Microsoft.Rules.Managed">
    <Rule Id="CA1001" Action="Warning" />
    <Rule Id="CA1821" Action="Warning" />
    <Rule Id="CA2213" Action="Warning" />
    <Rule Id="CA2231" Action="Warning" />
  </Rules>
</RuleSet>

Ниже приведен преобразованный файл EditorConfig:

# NOTE: Requires **VS2019 16.3** or later

# Rules for ConsoleApp
# Description: Code analysis rules for ConsoleApp.csproj.

# Code files
[*.{cs,vb}]

dotnet_diagnostic.CA1001.severity = warning

dotnet_diagnostic.CA1821.severity = warning

dotnet_diagnostic.CA2213.severity = warning

dotnet_diagnostic.CA2231.severity = warning

Установка серьезности правил из Обозреватель решений

  1. В Обозреватель решений разверните анализаторы ссылок>(или анализаторы зависимостей>для проектов .NET Core).

  2. Разверните сборку, содержащую правило, для которого необходимо задать серьезность.

  3. Щелкните правой кнопкой мыши правило и выберите "Задать серьезность". В контекстном меню выберите один из параметров серьезности.

    Visual Studio добавляет запись в файл EditorConfig, чтобы настроить правило на запрошенный уровень. Если проект использует файл набора правил вместо файла EditorConfig, запись серьезности добавляется в файл набора правил.

    Совет

    Если в проекте еще нет файла EditorConfig или файла набора правил, Visual Studio создает новый файл EditorConfig.

Установка серьезности правил в файле набора правил

  1. Откройте файл активного набора правил одним из следующих способов:

    • В Обозреватель решений дважды щелкните файл, щелкните правой кнопкой мыши узел "Ссылки>на анализаторы" и выберите "Открыть активный набор правил".

      Rule set file in Solution Explorer

    • На странице свойств "Анализ кода" проекта нажмите кнопку "Открыть".

    Если вы впервые редактируете набор правил, Visual Studio создает копию файла набора правил по умолчанию, называет его <projectname.ruleset> и добавляет его в проект. Этот настраиваемый набор правил также становится активным набором правил для проекта.

    Примечание.

    Проекты .NET Core и .NET Standard не поддерживают команды меню для наборов правил в Обозреватель решений, например открыть активный набор правил. Чтобы указать набор правил, отличных от по умолчанию для проекта .NET Core или .NET Standard, вручную добавьте свойство CodeAnalysisRuleSet в файл проекта. Вы по-прежнему можете настроить правила в наборе правил в пользовательском интерфейсе редактора правил Visual Studio.

  2. Перейдите к правилу, разверните ее содержащую сборку.

  3. В столбце "Действие " выберите значение, чтобы открыть раскрывающийся список, и выберите нужную серьезность из списка.

    Rule set file open in editor

Настройка созданного кода

Анализаторы выполняются во всех исходных файлах проекта и сообщают о нарушениях. Однако нарушения не полезны для созданных файлов кода, таких как файлы кода конструктора, временные исходные файлы, созданные системой сборки, и т. д. Пользователи не могут вручную редактировать файлы и не обеспокоены устранением нарушений в созданных средствами файлах.

По умолчанию драйвер анализатора, на котором выполняются анализаторы, обрабатывает файлы с определенными именами, расширениями файлов или автоматически созданными заголовками файлов в виде созданных файлов кода. Например, имя файла, заканчивающееся .designer.cs или .generated.cs, считается созданным кодом. Однако эти эвристики могут не идентифицировать все пользовательские созданные файлы кода в исходном коде пользователя.

Начиная с Visual Studio 2019 16.5, конечные пользователи могут настроить определенные файлы и (или) папки для обработки как созданный код в файле EditorConfig. Выполните следующие действия, чтобы добавить такую конфигурацию:

  1. Если у вас еще нет файла EditorConfig для проекта, добавьте его.

  2. generated_code = true | false Добавьте запись для определенных файлов и (или) папок. Например, чтобы обрабатывать все файлы, имя которых заканчивается .MyGenerated.cs как созданный код, запись будет следующим образом:

    [*.MyGenerated.cs]
    generated_code = true
    

Подавление нарушений

Нарушения правил можно подавлять с помощью различных методов. Дополнительные сведения см. в разделе "Подавление нарушений анализа кода".

Использование командной строки

При сборке проекта в командной строке нарушения правил отображаются в выходных данных сборки, если выполнены следующие условия:

  • Анализаторы устанавливаются с помощью пакета SDK для .NET или пакета NuGet, а не в виде расширения VSIX.

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

  • В коде проекта нарушается одно или несколько правил.

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

Детализация выходных данных сборки не влияет на то, отображаются ли нарушения правил. Даже при тихой детализации правила отображаются в выходных данных сборки.

Совет

Если вы привыкли выполнять устаревший анализ из командной строки либо с помощью FxCopCmd.exe , либо через msbuild с флагом RunCodeAnalysis , вот как это сделать с анализаторами кода.

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

msbuild myproject.csproj /target:rebuild /verbosity:minimal

На следующем изображении показаны выходные данные сборки из командной строки для создания проекта, содержащего нарушение правила анализа:

MSBuild output with rule violation

Зависимые проекты

В проекте .NET Core при добавлении ссылки на проект с анализаторами NuGet эти анализаторы также автоматически добавляются в зависимый проект. Чтобы отключить это поведение, например, если зависимый проект является проектом модульного теста, помечайте пакет NuGet как закрытый в CSPROJ или VBPROJ-файле указанного проекта, задав атрибут PrivateAssets:

<PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="5.0.0" PrivateAssets="all" />