Поделиться через


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

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

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

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

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

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

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

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

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

Снимок экрана: нарушения анализатора в окне списка ошибок.

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

Снимок экрана: метки ошибок, предупреждений и предложений в редакторе кода.

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

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

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

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

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

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

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

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

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

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

      Снимок экрана: настройка серьезности правил в меню лампочки в Visual Studio 2022.

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

      Снимок экрана: настройка серьезности правил из меню лампочки в Visual Studio 2019.

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

    Снимок экрана: уровень серьезности правил, выбранный в меню в Visual Studio 2022.

    Снимок экрана: уровень серьезности правил, выбранный в меню в Visual Studio 2019.

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

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

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

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

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

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

    Снимок экрана: настройка серьезности правил в окне списка ошибок в Visual Studio.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    Примечание.

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

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

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

    Снимок экрана: файл набора правил, открытый в редакторе набора правил, с указанными уровнями серьезности.

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

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

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

Снимок экрана: выходные данные MSBuild с нарушением правила в командной строке разработчика.

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

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

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