Параметры конфигурации для анализа кода
Для правил анализа кода доступно несколько параметров конфигурации. Некоторые из этих параметров указываются в файле конфигурации анализатора в формате пар "ключ — значение" с использованием синтаксиса <option key> = <option value>. Другие параметры, которые настраивают анализ кода в целом, доступны как свойства MSBuild в файле проекта.
Чаще всего вам придется настраивать такой параметр, как серьезность правила. Уровень серьезности можно настроить отдельно для любого правила, включая правила качества кода и правила стиля кода. Например, чтобы включить правило в качестве предупреждения, добавьте следующую пару "ключ-значение" в файл конфигурации анализатора:
dotnet_diagnostic.<rule ID>.severity = warning
Кроме того, можно настроить поведение правила с помощью дополнительных параметров:
- Правила качества кода имеют параметры поведения, например имена методов, к которым должно применяться правило.
- Правила стиля кода имеют параметры стиля, например, где желательны новые строки.
- Правила анализатора от сторонних поставщиков могут включать определения собственных параметров конфигурации с произвольными именами ключей и форматами значений.
Общие параметры
Эти параметры применяются к анализу кода в целом. Они не могут применяться только к определенному правилу.
Дополнительные параметры см. в разделе Свойства анализа кода.
Режим анализа
Хотя пакет SDK для .NET включает все правила анализа кода, по умолчанию включены только некоторые из них. Режим анализа определяет, какой набор правил необходимо включить. Вы можете выбрать более агрессивный режим анализа, где большинство или все правила включены. Или вы можете выбрать более консервативный режим анализа, где большинство или все правила отключены, и при необходимости вы можете принять участие в определенных правилах. Задайте режим анализа, добавив <свойство AnalysisMode> MSBuild в файл проекта.
<PropertyGroup>
<AnalysisMode>Recommended</AnalysisMode>
</PropertyGroup>
Начиная с .NET 6, можно также массово включить категорию правил с помощью свойства MSBuild категории>> AnalysisMode<.<
Примечание.
Если вы настраиваете анализ кода с помощью свойств MSBuild, например AnalysisMode, все параметры массовой конфигурации, заданные в файле конфигурации, игнорируются. Например, если вы включили все правила или категорию правил в файле .editorconfig , эта конфигурация игнорируется.
Включение анализа кода
Для проектов, предназначенных для .NET 5 и более поздних версий анализ кода включен по умолчанию. Если вы используете пакет SDK для .NET 5 или более поздней версии, но ваш проект предназначен для другой реализации .NET, необходимо вручную включить анализ кода, установив для свойства EnableNETAnalyzers значение true.
<PropertyGroup>
<EnableNETAnalyzers>true</EnableNETAnalyzers>
</PropertyGroup>
Исключение созданного кода
Предупреждения анализатора кода .NET бесполезны для файлов созданного кода, например создаваемых конструктором файлов, так как пользователи не смогут изменить их для устранения обнаруженных нарушений. В большинстве случаев анализаторы кода пропускают файлы созданного кода и не сообщают о нарушениях в них.
По умолчанию файлы с определенными расширениями или автоматически создаваемыми заголовками обрабатываются как файлы созданного кода. Например, файл с постфиксом .designer.cs или .generated.cs считается содержащим созданный код. Этот параметр конфигурации позволяет указать дополнительные шаблоны именования, которые будут обрабатываться как созданный код. Настройте дополнительные файлы и папки, добавив запись generated_code = true | false в файл конфигурации. Например, чтобы считать все файлы, имена которых оканчиваются на .MyGenerated.cs, содержащими созданный код, добавьте следующую запись:
[*.MyGenerated.cs]
generated_code = true
Параметры для конкретных правил
Параметры для конкретных правил могут применяться к одному правилу, к набору правил или ко всем правилам. Доступны следующие параметры для конкретных правил:
Уровень серьезности
В следующей таблице представлены разные уровни серьезности правил, которые можно настроить для всех правил анализатора, включая правила качества кода и стиля кода.
| Значение конфигурации серьезности | Поведение при сборке |
|---|---|
error |
Нарушения отображаются как ошибки при сборке, которые аварийно завершают ее. |
warning |
Нарушения отображаются как предупреждения сборки, но не приводят к аварийному завершению, если вы не настроили параметр, требующий обрабатывать предупреждения как ошибки. |
suggestion |
Нарушения отображаются как сообщения сборки и предложения в интегрированной среде разработки Visual Studio. (В Visual Studio предложения отображаются как три серые точки под первыми двумя символами.) |
silent |
Нарушения не видны пользователю. Однако для правил стиля кода функции создания кода Visual Studio по-прежнему создают код в этом стиле. Эти правила также участвуют в очистке и отображаются в меню быстрых действий и рефакторингов в Visual Studio. |
none |
Правило подавляется полностью. Однако для правил стиля кода функции создания кода Visual Studio по-прежнему создают код в этом стиле. |
default |
Используется серьезность правила по умолчанию. Уровни серьезности по умолчанию для каждого выпуска .NET приведены в репозитории roslyn-analyzers. В этой таблице "Disabled" соответствует none, "Hidden" соответствует silent, а "info" соответствует suggestion. |
Область
Одно правило
Чтобы задать серьезность правила для одного правила, используйте следующий синтаксис.
dotnet_diagnostic.<rule ID>.severity = <severity value>Категория правил
Чтобы задать серьезность по умолчанию для категории правил, используйте следующий синтаксис. Однако этот параметр серьезности влияет только на правила в этой категории, которые включены по умолчанию.
dotnet_analyzer_diagnostic.category-<rule category>.severity = <severity value>Разные категории перечислены и описаны в статье Категории правил. Кроме того, можно найти категорию для определенного правила на странице справочных материалов, например CA1000.
Все правила
Чтобы задать серьезность правила по умолчанию для всех правил анализатора, используйте следующий синтаксис. Однако этот параметр серьезности влияет только на правила, включенные по умолчанию.
dotnet_analyzer_diagnostic.severity = <severity value>
Внимание
Если вы задаете уровень серьезности одной записью для нескольких правил, то есть для категории правил или для всех правил, этот уровень серьезности применяется только к тем правилам, которые включены по умолчанию. Если включить все правила с помощью свойств <MSBuild AnalysisMode> или< AnalysisLevel>, все массовые dotnet_analyzer_diagnostic параметры игнорируются. По этой причине лучше включить категорию правил, установив <для параметра AnalysisMode<Category>> Allзначение .
Примечание.
Префикс для задания серьезности для одного правила немного dotnet_diagnosticотличается от префикса настройки серьезности с помощью категории или для всех правил dotnet_analyzer_diagnostic.
Приоритет
Если к одному идентификатору правила могут применяться несколько записей конфигурации серьезности, приоритет определяется следующим образом:
- Запись для категории имеет приоритет над записью для всех правил анализатора.
- Запись для конкретного идентификатора правила имеет приоритет над записью для категории.
Рассмотрим следующий пример с правилом CA1822, которое имеет категорию Performance (Производительность):
[*.cs]
dotnet_diagnostic.CA1822.severity = error
dotnet_analyzer_diagnostic.category-performance.severity = warning
dotnet_analyzer_diagnostic.severity = suggestion
В примере выше к правилу CA1822 применимы все три записи серьезности. Но применение указанных правил приоритета приводит к тому, что первая запись с идентификатором правила "опережает" все остальные записи. Следовательно, в этом примере для CA1822 будет применяться уровень серьезности error. Все остальные правила в категории Performance (Производительность) будут иметь серьезность warning.
Сведения о распределении приоритетов между файлами см. в разделе "Приоритет" статьи о файлах конфигурации.
