Настройка правил анализатора Roslyn

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

Уровни серьезности

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

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

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

Просмотр нарушений правил

Если анализатор находит нарушения правил анализатора, он сообщает их в окне списка ошибок и в редакторе кода.

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

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

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

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

Вы можете задать серьезность правила с помощью любого из следующих методов:

• EditorConfig
• Меню лампочки
• Окно "Список ошибок"
• Обозреватель решений

Безмолвный и нет серьезности

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

• Если исправление кода зарегистрировано для Silent правила серьезности, Visual Studio предлагает исправление кода как действие рефакторинг кода лампочки, даже если скрытая диагностика не отображается пользователю. Если правило серьезности отключено как None, исправление кода не предлагается.
• Записи, которые задают серьезность нескольких правил анализатора одновременно в файле EditorConfig, могут массово настраивать Silent правила серьезности. None Правила серьезности не могут быть настроены таким образом. Вместо этого их необходимо настроить с помощью записей, которые задают серьезность в файле EditorConfig для каждого идентификатора правила.

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

Файлы EditorConfig доступны в Visual Studio 2019 версии 16.3 и более поздних версиях.

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

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

Чтобы настроить серьезность правил, выполните следующие действия.

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

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

   Например, запись для задания серьезности для CA18222 error для файлов C# выглядит следующим образом:

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

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

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

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

   Например, dotnet_style_qualification_for_field = false:suggestion. Однако если задать серьезность с помощью синтаксиса dotnet_diagnostic , он имеет приоритет. Дополнительные сведения см. в разделе "Языковые соглашения" для 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

В этом примере все три записи применяются к правилу производительности CA1822. Однако при использовании указанных правил приоритета первая запись серьезности на основе идентификатора правила имеет приоритет над следующими записями. В этом примере CA1822 имеет эффективную степень серьезности error. Остальные правила производительности имеют серьезность warning. Правила анализатора, которые не являются правилами производительности, имеют серьезность suggestion.

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

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

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

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

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

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

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

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

     

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

   

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

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

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

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

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

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

   

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

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

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

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

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

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

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

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

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

Просмотр анализаторов и диагностика из Обозреватель решений

Вы можете выполнить большую часть настройки анализатора диагностика из Обозреватель решений. При установке анализатора в виде пакета NuGet узел анализаторов отображается в узле "Ссылки" (или узле зависимостей для проектов .NET Core) в Обозреватель решений. Выполните следующие действия, чтобы просмотреть анализаторы и диагностика:

1. В Обозреватель решений разверните проект, разверните ссылки или зависимости, а затем разверните анализаторы. Разверните одну из сборок анализатора, чтобы увидеть диагностика в сборке.

   Значок рядом с каждой диагностикой указывает уровень серьезности:

   • x в круге указывает серьезность ошибки
   • ! в треугольнике указывает серьезность предупреждения
   • i в сплошном круге указывает на серьезность предложения
   • i в пунктирном круге указывает на серьезность "Молча"
   • Стрелка вниз в сплошном круге указывает на серьезность None

   

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

   Откроется окно Свойства .

   

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

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

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

В Visual Studio 2019 версии 16.5 и более поздних версиях файлы наборов правил устарели в пользу файлов EditorConfig для конфигурации анализатора для управляемого кода. Файлы EditorConfig являются более гибкими и позволяют настроить параметры стиля кода visual Studio IDE как правила анализатора, так и параметры анализатора. Так как средства Visual Studio для конфигурации серьезности правил анализатора оптимизированы для работы с файлами EditorConfig вместо файлов набора правил, рекомендуется преобразовать все существующие проекты, которые по-прежнему используют файлы набора правил.

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

Существующий файл набора правил можно преобразовать в файл EditorConfig с помощью редактора набора правил или командной строки.

Примечание.

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

Чтобы использовать редактор набора правил, выполните следующие действия. Если проект уже использует определенный файл набора правил для его CodeAnalysisRuleSet значения свойства, его можно преобразовать в эквивалентный файл EditorConfig из редактора набора правил:

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

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

   

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

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

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

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

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

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

   Например:

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

В следующем примере показан файл набора правил для преобразования в файл 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

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

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

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

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

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

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

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

Связанный контент

• Обзор анализаторов кода в Visual Studio
• Отправка ошибки анализатора кода
• Использование наборов правил
• Подавление нарушений анализа кода
• Параметры конфигурации для анализа кода