Файлы конфигурации для правил анализа кода
Для правил анализа кода доступно несколько параметров конфигурации. Эти параметры указываются в виде пар "ключ-значение" в одном из следующих файлов конфигурации анализатора:
- Файл EditorConfig: параметры конфигурации на основе файлов или папок.
- Глобальный файл AnalyzerConfig: параметры конфигурации на уровне проекта. Полезно, когда некоторые файлы проекта находятся за пределами папки проекта.
Совет
Вы также можете задать свойства конфигурации анализа кода в файле своего проекта. Эти свойства настраивают анализ кода на массовом уровне, от полного включения или отключения до конфигурации на уровне категорий. Дополнительные сведения см. в разделе EnableNETAnalyzers, AnalysisLevel, AnalysisLevelCategory<> и AnalysisMode.
EditorConfig
Файлы EditorConfig используются для предоставления параметров, которые применяются к конкретным исходным файлам или папкам. Параметры размещаются под заголовками разделов, позволяя идентифицировать соответствующие файлы и папки. Добавьте запись для каждого правила, которое необходимо настроить, и разместите его в соответствующем разделе расширения имени файла, например [*.cs].
[*.cs]
<option_name> = <option_value>
В приведенном выше примере [*.cs] — это заголовок раздела editorconfig для выбора всех файлов C# с расширением имени файла .cs в текущей папке, включая вложенные папки. Последующая запись, <option_name> = <option_value>, — это параметр анализатора, который будет применяться ко всем файлам C#.
Соглашения о файлах EditorConfig можно применять к папке, проекту или всему репозиторию, помещая файл в соответствующий каталог. Эти параметры применяются при выполнении анализа во время сборки, а также при редактировании кода в Visual Studio.
Примечание
Параметры EditorConfig применяются только к исходным файлам в проекте или каталоге. Файлы, которые включены в проект как AdditionalFiles, не считаются исходными файлами, и параметры EditorConfig к ним не применяются. Чтобы применить параметр правила к файлам, не являющимся исходными, укажите параметр в глобальном файле конфигурации.
Если у вас уже есть файл .editorconfig для параметров редактора, таких как размер отступа или необходимость обрезать пробелы в конце, параметры конфигурации анализа кода можно поместить в тот же файл.
Совет
Visual Studio предоставляет шаблон элемента EDITORCONFIG, который упрощает добавление одного из этих файлов в проект. Дополнительные сведения см. в разделе Добавление файла EditorConfig в проект.
Пример
Ниже приведен пример файла EditorConfig для настройки параметров и важности правила:
# Remove the line below if you want to inherit .editorconfig settings from higher directories
root = true
# C# files
[*.cs]
#### Core EditorConfig Options ####
# Indentation and spacing
indent_size = 4
indent_style = space
tab_width = 4
#### .NET Coding Conventions ####
# this. and Me. preferences
dotnet_style_qualification_for_method = true
#### Diagnostic configuration ####
# CA1000: Do not declare static members on generic types
dotnet_diagnostic.CA1000.severity = warning
Глобальный AnalyzerConfig
Начиная с пакета SDK для .NET 5 (который поддерживается в Visual Studio 2019 версии 16.8 и более поздних версиях) можно также настроить параметры анализатора с помощью глобальных файлов AnalyzerConfig. Эти файлы используются для предоставления параметров, которые применяются ко всем исходным файлам в проекте, независимо от их имен или путей к файлам.
В отличие от файлов EditorConfig, глобальные файлы конфигурации не позволяют настраивать параметры стиля редактора в интегрированных средах разработки, например размеры отступа или обрезку конечных пробелов. Вместо этого они предназначены исключительно для указания параметров конфигурации анализатора уровня проекта.
Формат
В отличие от файлов EditorConfig, которые должны иметь заголовки разделов, например [*.cs], для обнаружения подходящих файлов и папок, глобальные файлы AnalyzerConfig не имеют заголовков разделов. Вместо этого им требуется запись верхнего уровня формы is_global = true, чтобы отличать их от обычных файлов EditorConfig. Это указывает, что все параметры в файле применяются ко всему проекту. Пример:
is_global = true
<option_name> = <option_value>
Именование
В отличие от файлов EditorConfig, которые должны называться .editorconfig, глобальные файлы конфигурации необязательно должны иметь определенное имя или расширение. Однако если давать этим файлам имена .globalconfig, они будут неявно применяться ко всем проектам C# и Visual Basic в текущей папке, включая вложенные папки. В противном случае необходимо явно добавить элемент GlobalAnalyzerConfigFiles в файл проекта MSBuild:
<ItemGroup>
<GlobalAnalyzerConfigFiles Include="<path_to_global_analyzer_config>" />
</ItemGroup>
По именованию имеются следующие рекомендации:
- Пользователям следует давать глобальным файлам конфигурации имена .globalconfig.
- NuGet создатели пакетов должны назвать свои глобальные файлы <конфигурации %Package_Name%>.globalconfig.
- MSBuild созданные средствами глобальные файлы конфигурации должны называться <%Target_Name%>_Generated.globalconfig или аналогичны.
Примечание
Запись is_global = true верхнего уровня не требуется, если файл называется .globalconfig, но рекомендуется для ясности.
Пример
Ниже приведен пример глобального файла AnalyzerConfig для настройки параметров и серьезности правил на уровне проекта:
# Top level entry required to mark this as a global AnalyzerConfig file
is_global = true
# NOTE: No section headers for configuration entries
#### .NET Coding Conventions ####
# this. and Me. preferences
dotnet_style_qualification_for_method = true:warning
#### Diagnostic configuration ####
# CA1000: Do not declare static members on generic types
dotnet_diagnostic.CA1000.severity = warning
Приоритет
Как файлы EditorConfig, так и глобальные файлы AnalyzerConfig задают пару "ключ-значение" для каждого параметра. Конфликты возникают, когда имеется несколько записей с одинаковым ключом, но разными значениями. Для разрешения конфликтов действуют следующие правила приоритета.
| Расположения конфликтующих записей | Правило приоритета |
|---|---|
| Внутри одного файла конфигурации | Приоритет имеет запись, стоящая в файле позже. Это справедливо для конфликтующих записей в одном файле EditorConfig, равно как и в одном глобальном файле AnalyzerConfig. |
| В двух файлах EditorConfig | Приоритет имеет запись в том файле EditorConfig, который находится глубже в файловой системе, то есть имеет более длинный путь. |
| В двух глобальных файлах AnalyzerConfig | .NET 5: выдается предупреждение компилятора, и обе записи игнорируются. .NET 6 и более поздние версии: приоритет имеет запись из файла с более высоким значением global_level. Если значение global_level явно не определено и файл имеет имя .globalconfig, то для него используется global_level со значением по умолчанию 100, а для всех прочих глобальных файлов AnalyzerConfig используется global_level со значением по умолчанию 0. Если файлы конфигурации с конфликтующими записями имеют одинаковое значение global_level, то выдается предупреждение компилятора и обе записи игнорируются. |
| В файле EditorConfig и глобальном файле AnalyzerConfig | Приоритет имеет запись в файле EditorConfig. |
Параметры серьезности
Для параметров конфигурации уровня серьезности действуют дополнительные правила приоритета:
Параметры серьезности, указанные в командной строке как параметры компилятора (
-nowarnили-warnaserror), всегда переопределяют параметры конфигурации серьезности, указанные в EditorConfig и глобальных файлах AnalyzerConfig.Правила приоритета для записей с конфликтующим уровнем серьезности из файла ruleset и конфигурации EditorConfig или глобального файла AnalyzerConfig не определены.
Файлы ruleset являются нерекомендуемыми. Вместо них следует использовать EditorConfig и глобальные файлы AnalyzerConfig. Рекомендуем преобразовать файлы ruleset в эквивалентный файл EditorConfig.
Сведения о правилах приоритета для связанных параметров серьезности с различными ключами, например при указании различных уровней серьезности для одного правила и категории, к которой относится правило, см. в разделе Параметры конфигурации для анализа кода.