Konfigurační soubory pro pravidla analýzy kódu

  • Článek

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ého zapnutí nebo vypnutí konfigurace 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ů 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žek .editorconfig , která usnadňuje 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

Počínaje sadou .NET 5 SDK (která je podporována v sadě Visual Studio 2019 a novějším), můžete také nakonfigurovat možnosti analyzátoru s globálními soubory 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ženy č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, pokud je soubor pojmenován .globalconfig, ale doporučuje se pro přehlednost.

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 (-nowarn nebo -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.

Viz také