Файлы конфигурации для правил анализа кода
Для правил анализа кода доступно несколько параметров конфигурации. Эти параметры указываются в виде пар "ключ-значение" в одном из следующих файлов конфигурации анализатора:
- Файл EditorConfig: параметры конфигурации на основе файлов или папок.
- Глобальный файл AnalyzerConfig: параметры конфигурации на уровне проекта. Полезно, когда некоторые файлы проекта находятся за пределами папки проекта.
Совет
Вы также можете задать свойства конфигурации анализа кода в файле своего проекта. Эти свойства настраивают анализ кода на массовом уровне, от полного включения или отключения анализа кода до конфигурации правила уровня категорий. Дополнительные сведения см. в разделе EnableNETAnalyzers, AnalysisLevel, AnalysisLevel<Category> и AnalysisMode.
EditorConfig
Файлы EditorConfig используются для предоставления параметров, которые применяются к конкретным исходным файлам или папкам. Параметры размещаются под заголовками разделов, позволяя идентифицировать соответствующие файлы и папки. Добавьте запись для каждого правила, которое необходимо настроить, и разместите его в соответствующем разделе расширения имени файла, например [*.cs].
[*.cs]
<option_name> = <option_value>
В приведенном выше примере заголовок раздела позволяет [*.cs] editorconfig выбрать все файлы C# с .cs расширением файла в текущей папке, включая вложенные папки. Последующая запись, <option_name> = <option_value>, — это параметр анализатора, который будет применяться ко всем файлам C#.
Соглашения о файлах EditorConfig можно применять к папке, проекту или всему репозиторию, помещая файл в соответствующий каталог. Эти параметры применяются при выполнении анализа во время сборки, а также при редактировании кода в Visual Studio.
Примечание.
Параметры EditorConfig применяются только к исходным файлам в проекте или каталоге. Файлы, включенные в проект в качестве Дополнительных файлов, не считаются исходными файлами, и 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
Вы также можете настроить параметры анализатора с помощью глобальных файлов 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, но рекомендуется для ясности.
Условное включение
Глобальный файл конфигурации можно использовать для отключения или включения определенных правил анализа кода в разных средах. Например, может потребоваться отключить некоторые правила анализа кода для проектов модульного теста. Для этого можно задать уровень серьезности применимых правил none в файле конфигурации, например:
# CA1861: Prefer 'static readonly' fields over constant array arguments
dotnet_diagnostic.CA1861.severity = none
Затем можно настроить сборку, чтобы включить только файл конфигурации в тестовые проекты на основе условий, относящихся к сборке. Например:
<ItemGroup Condition="'$(IsShipping)' == 'false'">
<!-- Include CodeAnalysis.test.globalconfig to override (relax) some rules from the primary configuration. -->
<GlobalAnalyzerConfigFiles Include="$(MSBuildThisFileDirectory)CodeAnalysis.test.globalconfig" />
</ItemGroup>
Распространение в пакетах NuGet
Файлы Global AnalyzerConfig можно распространять с помощью пакетов NuGet. Для этого добавьте props-файл в пакет NuGet. В файле props добавьте GlobalAnalyzerConfigFiles элемент под Project узлом:
<Project>
<ItemGroup>
<GlobalAnalyzerConfigFiles Include="Relative/Path/to/PackageName.globalconfig" />
</ItemGroup>
</Project>
Пример
Ниже приведен пример глобального файла 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.
Сведения о правилах приоритета для связанных параметров серьезности с различными ключами, например при указании различных уровней серьезности для одного правила и категории, к которой относится правило, см. в разделе Параметры конфигурации для анализа кода.
