Konfigurační soubory pro pravidla analýzy kódu
Pravidla analýzy kódu mají různé možnosti konfigurace. Tyto možnosti zadáte jako páry klíč-hodnota v jednom z následujících konfiguračních souborů analyzátoru:
- EditorConfig soubor: Možnosti konfigurace založené na souborech nebo složkách.
- Soubor Global AnalyzerConfig : Možnosti konfigurace na úrovni projektu Užitečné, když se některé soubory projektu nacházejí mimo složku projektu.
Tip
V souboru projektu můžete také nastavit vlastnosti konfigurace analýzy kódu. Tyto vlastnosti konfigurují analýzu kódu na hromadné úrovni od úplné zapnutí nebo vypnutí analýzy kódu až po konfiguraci pravidel na úrovni kategorií. Další informace naleznete v tématu EnableNETAnalyzers, AnalysisLevel, AnalysisLevel<Category> a AnalysisMode.
EditorConfig
EditorConfig soubory slouží k poskytování možností, které platí pro konkrétní zdrojové soubory nebo složky. Možnosti jsou umístěny pod záhlavími oddílů pro identifikaci příslušných souborů a složek. Přidejte položku pro každé pravidlo, které chcete nakonfigurovat, a umístěte ho do odpovídajícího oddílu přípony souboru, [*.cs]například .
[*.cs]
<option_name> = <option_value>
V předchozím příkladu je hlavička oddílu editorconfig pro [*.cs] výběr všech souborů jazyka C# s .cs příponou souboru v aktuální složce, včetně podsložek. Následující položka je <option_name> = <option_value>možnost analyzátoru, která se použije pro všechny soubory jazyka C#.
Konvence souborů můžete použít EditorConfig u složky, projektu nebo celého úložiště umístěním souboru do odpovídajícího adresáře. Tyto možnosti se použijí při provádění analýzy v době sestavení a při úpravě kódu v sadě Visual Studio.
Poznámka:
EditorConfig možnosti platí pouze pro zdrojové soubory v projektu nebo adresáři. Soubory, které jsou součástí projektu jako AdditionalFiles , se nepovažují za zdrojové soubory a EditorConfig možnosti se na tyto soubory nepoužijí. Pokud chcete použít možnost pravidla pro jiné než zdrojové soubory, zadejte možnost v globálním konfiguračním souboru.
Pokud máte existující soubor .editorconfig pro nastavení editoru, například velikost odsazení nebo jestli chcete oříznout koncové prázdné znaky, můžete možnosti konfigurace analýzy kódu umístit do stejného souboru.
Tip
Visual Studio poskytuje šablonu položky .editorconfig usnadňující přidání jednoho z těchto souborů do projektu. Další informace naleznete v tématu Přidání EditorConfig souboru do projektu.
Příklad
Následuje ukázkový EditorConfig soubor pro konfiguraci možností a závažnosti pravidla:
# 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
Global AnalyzerConfig
Můžete také nakonfigurovat možnosti analyzátoru pomocí globálních souborů AnalyzerConfig . Tyto soubory slouží k poskytování možností, které platí pro všechny zdrojové soubory v projektu bez ohledu na jejich názvy souborů nebo cesty k souborům.
Na rozdíl od EditorConfig souborů se globální konfigurační soubory nedají použít ke konfiguraci nastavení stylu editoru pro ides, jako je velikost odsazení nebo jestli se má oříznout koncové prázdné znaky. Místo toho jsou navržené čistě pro určení možností konfigurace analyzátoru na úrovni projektu.
Formát
Na rozdíl od EditorConfig souborů, které musí obsahovat hlavičky oddílů, například [*.cs], k identifikaci příslušných souborů a složek nemají globální soubory AnalyzerConfig hlavičky oddílů. Místo toho vyžadují položku nejvyšší úrovně formuláře is_global = true , aby je odlišila od běžných EditorConfig souborů. To znamená, že všechny možnosti v souboru platí pro celý projekt. Příklad:
is_global = true
<option_name> = <option_value>
Pojmenování
Na rozdíl od EditorConfig souborů, které musí být pojmenovány .editorconfig, globální konfigurační soubory nemusí mít konkrétní název nebo příponu. Pokud však tyto soubory pojmenujete jako .globalconfig, implicitně se použijí pro všechny projekty C# a Visual Basic v aktuální složce, včetně podsložek. Jinak musíte položku explicitně přidat GlobalAnalyzerConfigFiles do souboru projektu MSBuild:
<ItemGroup>
<GlobalAnalyzerConfigFiles Include="<path_to_global_analyzer_config>" />
</ItemGroup>
Zvažte následující doporučení pro pojmenování:
- Koncoví uživatelé by měli pojmenovat své globální konfigurační soubory .globalconfig.
- Tvůrci balíčků NuGet by měli pojmenovat své globální konfigurační soubory <%Package_Name%>.globalconfig.
- Nástroje MSBuild generované globální konfigurační soubory by měly mít název <%Target_Name%>_Generated.globalconfig nebo podobné.
Poznámka:
Položka is_global = true nejvyšší úrovně není vyžadována při pojmenování .globalconfigsouboru, ale doporučuje se pro přehlednost.
Podmíněné zahrnutí
Globální konfigurační soubor můžete použít k zakázání nebo povolení určitých pravidel analýzy kódu v různých prostředích. Můžete například chtít zakázat některá pravidla analýzy kódu pro projekty testování jednotek. K tomu můžete nastavit závažnost příslušných pravidel v none konfiguračním souboru, například:
# CA1861: Prefer 'static readonly' fields over constant array arguments
dotnet_diagnostic.CA1861.severity = none
Sestavení pak můžete přizpůsobit tak, aby zahrnovalo pouze konfigurační soubor do testovacích projektů na základě podmínek specifických pro sestavení. Příklad:
<ItemGroup Condition="'$(IsShipping)' == 'false'">
<!-- Include CodeAnalysis.test.globalconfig to override (relax) some rules from the primary configuration. -->
<GlobalAnalyzerConfigFiles Include="$(MSBuildThisFileDirectory)CodeAnalysis.test.globalconfig" />
</ItemGroup>
Distribuce v balíčcích NuGet
Soubory Global AnalyzerConfig je možné distribuovat s balíčky NuGet. Uděláte to tak, že do balíčku NuGet přidáte soubor .props. V souboru .props přidejte GlobalAnalyzerConfigFiles položku pod Project uzel:
<Project>
<ItemGroup>
<GlobalAnalyzerConfigFiles Include="Relative/Path/to/PackageName.globalconfig" />
</ItemGroup>
</Project>
Příklad
Následuje příklad globálního souboru AnalyzerConfig pro konfiguraci možností a závažnosti pravidla na úrovni projektu:
# 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
Pořadí podle priority
Soubory i EditorConfig globální soubory AnalyzerConfig určují dvojici klíč-hodnota pro každou možnost. Konflikty vznikají v případě, že existuje více položek se stejným klíčem, ale s různými hodnotami. K řešení konfliktů se používají následující pravidla priority.
| Konfliktní umístění položek | Pravidlo priority |
|---|---|
| Ve stejném konfiguračním souboru | Položka, která se zobrazí později v souboru, vyhraje. To platí pro konfliktní položky v rámci jednoho EditorConfig souboru a také v jednom globálním souboru AnalyzerConfig. |
| Ve dvou EditorConfig souborech | Položka v EditorConfig souboru, který je hlouběji v systému souborů, a proto má delší cestu k souboru, vyhrává. |
| Ve dvou globálních souborech AnalyzerConfig | .NET 5: Zobrazí se upozornění kompilátoru a obě položky se ignorují. .NET 6 a novější verze: Položka ze souboru s vyšší hodnotou má global_level přednost. Pokud global_level není explicitně definován a soubor má název .globalconfig, global_level výchozí hodnota je 100; pro všechny ostatní globální soubory AnalyzerConfig výchozí global_level hodnota 0. global_level Pokud jsou hodnoty konfiguračních souborů s konfliktními položkami stejné, zobrazí se upozornění kompilátoru a obě položky budou ignorovány. |
| EditorConfig V souboru a souboru Global AnalyzerConfig | Položka v EditorConfig souboru vyhrává. |
Možnosti závažnosti
Pro možnosti konfigurace závažnosti platí následující další pravidla priority:
Možnosti závažnosti zadané na příkazovém řádku jako možnosti kompilátoru (
-nowarnnebo-warnaserror) vždy přepisují možnosti konfigurace závažnosti zadané v EditorConfig souborech a globálních souborech AnalyzerConfig.Pravidla priority pro konfliktní položky závažnosti ze souboru sady pravidel a EditorConfig globální soubor AnalyzerConfig není definován.
Soubory sady pravidel jsou zastaralé ve prospěch globálních EditorConfig souborů AnalyzerConfig. Doporučujeme převést soubory sady pravidel na ekvivalentní EditorConfig soubor.
Informace o pravidlech priority pro související možnosti závažnosti s různými klíči, například pokud jsou pro jedno pravidlo zadány různé závažnosti a kategorie, do které pravidlo spadá, najdete v tématu Možnosti konfigurace pro analýzu kódu.
