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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   Например, запись для задания серьезности для CA18222error для файлов 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 доступна в 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 создает его для вас.

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

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

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

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

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

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

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

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

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

   • x в круге указывает серьезность ошибки
   • ! в треугольнике указывает серьезность предупреждения
   • i в сплошном круге указывает на степень важности рекомендации
   • i в пунктирном круге указывает на степень тяжести «Тихо»
   • Стрелка вниз в сплошном круге указывает на серьезность None

   

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

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

   

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

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

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

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

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

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

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

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

   

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

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

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

   Исходный файл набора правил можно удалить из проекта.

   Примечание

   В проекте .NET Framework файл набора правил по умолчанию нельзя перенести или удалить из проекта.

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

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, либо с флагом RunCodeAnalysis в msbuild, вы можете сделать это с помощью анализаторов кода.

Чтобы увидеть нарушения анализатора в командной строке при сборке проекта с помощью 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
• Отправка ошибки анализатора кода
• Использование наборов правил
• Подавление нарушений анализа кода
• Параметры конфигурации для анализа кода