Share via

Konfigurationsfiler för kodanalysregler

  • Artikel

Kodanalysregler har olika konfigurationsalternativ. Du anger dessa alternativ som nyckel/värde-par i någon av följande konfigurationsfiler för analysverktyg:

  • EditorConfig fil: Filbaserade eller mappbaserade konfigurationsalternativ.
  • Global AnalyzerConfig-fil : Konfigurationsalternativ på projektnivå. Användbart när vissa projektfiler finns utanför projektmappen.

Dricks

Du kan också ange konfigurationsegenskaper för kodanalys i projektfilen. Dessa egenskaper konfigurerar kodanalys på massnivå, från att helt aktivera eller inaktivera den till konfiguration på kategorinivå. Mer information finns i EnableNETAnalyzers, AnalysisLevel, AnalysisLevel<Category> och AnalysisMode.

EditorConfig

EditorConfig filer används för att tillhandahålla alternativ som gäller för specifika källfiler eller mappar. Alternativ placeras under avsnittsrubriker för att identifiera tillämpliga filer och mappar. Lägg till en post för varje regel som du vill konfigurera och placera den under motsvarande filnamnstilläggsavsnitt, [*.cs]till exempel .

[*.cs]
<option_name> = <option_value>

I exemplet ovan [*.cs] är en editorconfig-avsnittsrubrik för att välja alla C#-filer med .cs filnamnstillägg i den aktuella mappen, inklusive undermappar. Den efterföljande posten, <option_name> = <option_value>, är ett analysalternativ som ska tillämpas på alla C#-filer.

Du kan tillämpa EditorConfig filkonventioner på en mapp, ett projekt eller en hel lagringsplats genom att placera filen i motsvarande katalog. De här alternativen tillämpas när du kör analysen vid byggtiden och när du redigerar kod i Visual Studio.

Kommentar

EditorConfig -alternativ gäller endast för källfiler i ett projekt eller en katalog. Filer som ingår i ett projekt som AdditionalFiles betraktas inte som källfiler och EditorConfig alternativ tillämpas inte på dessa filer. Om du vill tillämpa ett regelalternativ på filer som inte är källfiler anger du alternativet i en global konfigurationsfil.

Om du har en befintlig .editorconfig-fil för redigeringsinställningar, till exempel indragsstorlek eller om du vill trimma avslutande blanksteg, kan du placera konfigurationsalternativen för kodanalys i samma fil.

Dricks

Visual Studio innehåller en .editorconfig-objektmall som gör det enkelt att lägga till en av dessa filer i projektet. Mer information finns i Lägga till en EditorConfig fil i ett projekt.

Exempel

Följande är en exempelfil EditorConfig för att konfigurera alternativ och regel allvarlighetsgrad:

# 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

Från och med .NET 5 SDK (som stöds i Visual Studio 2019 och senare) kan du även konfigurera analysalternativ med globala AnalyzerConfig-filer . Dessa filer används för att tillhandahålla alternativ som gäller för alla källfiler i ett projekt, oavsett filnamn eller filsökvägar.

Till skillnad från EditorConfig filer kan globala konfigurationsfiler inte användas för att konfigurera redigeringsformatinställningar för IDE:er, till exempel indragsstorlek eller om avslutande blanksteg ska trimmas. I stället är de utformade enbart för att ange konfigurationsalternativ för analysverktyg på projektnivå.

Format

Till skillnad från EditorConfig filer, som måste ha avsnittsrubriker, till exempel [*.cs], för att identifiera tillämpliga filer och mappar, har globala AnalyzerConfig-filer inte avsnittshuvuden. I stället kräver de en post på den översta nivån i formuläret is_global = true för att skilja dem från vanliga EditorConfig filer. Detta anger att alla alternativ i filen gäller för hela projektet. Till exempel:

is_global = true
<option_name> = <option_value>

Namngivning

Till skillnad från EditorConfig filer, som måste ha namnet .editorconfig, behöver globala konfigurationsfiler inte ha ett specifikt namn eller tillägg. Men om du namnger dessa filer som .globalconfig, tillämpas de implicit på alla C#- och Visual Basic-projekt i den aktuella mappen, inklusive undermappar. Annars måste du uttryckligen lägga till objektet i GlobalAnalyzerConfigFiles din MSBuild-projektfil:

<ItemGroup>
  <GlobalAnalyzerConfigFiles Include="<path_to_global_analyzer_config>" />
</ItemGroup>

Överväg följande namngivningsrekommendationer:

  • Slutanvändarna bör namnge sina globala konfigurationsfiler .globalconfig.
  • NuGet-paketskapare bör namnge sina globala konfigurationsfiler <%Package_Name%>.globalconfig.
  • MSBuild-verktygsgenererade globala konfigurationsfiler ska ha namnet <%Target_Name%>_Generated.globalconfig eller liknande.

Kommentar

Posten på den översta nivån is_global = true krävs inte när filen heter .globalconfig, men den rekommenderas för tydlighetens skull.

Distribution i NuGet-paket

Globala AnalyzerConfig-filer kan distribueras med NuGet-paket. Det gör du genom att lägga till en .props-fil i NuGet-paketet. Lägg till ett GlobalAnalyzerConfigFiles objekt under Project noden i .props-filen:

<Project>
  <ItemGroup>
    <GlobalAnalyzerConfigFiles Include="Relative/Path/to/PackageName.globalconfig" />
  </ItemGroup>
</Project>

Exempel

Följande är ett exempel på en global AnalyzerConfig-fil för att konfigurera alternativ och regel allvarlighetsgrad på projektnivå:

# 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

Prioritet

Både EditorConfig filer och globala AnalyzerConfig-filer anger ett nyckel/värde-par för varje alternativ. Konflikter uppstår när det finns flera poster med samma nyckel men olika värden. Följande prioritetsregler används för att lösa konflikter.

Inmatningsplatser i konflikt Prioritetsregel
I samma konfigurationsfil Posten som visas senare i filen vinner. Detta gäller för poster i konflikt i en enda EditorConfig fil och även i en enda global AnalyzerConfig-fil.
I två EditorConfig filer Posten i EditorConfig filen som är djupare i filsystemet och därmed har en längre filsökväg vinner.
I två globala AnalyzerConfig-filer .NET 5: En kompilatorvarning rapporteras och båda posterna ignoreras.
.NET 6 och senare versioner: Posten från filen med ett högre värde för global_level har företräde. Om global_level inte uttryckligen definieras och filen heter .globalconfig, global_level standardvärdet till 100; för alla andra globala AnalyzerConfig-filer är global_level standardvärdet 0. global_level Om värdena för konfigurationsfilerna med motstridiga poster är lika, rapporteras en kompilatorvarning och båda posterna ignoreras.
I en EditorConfig fil och en Global AnalyzerConfig-fil Posten i EditorConfig filen vinner.

Allvarlighetsalternativ

För konfigurationsalternativ för allvarlighetsgrad gäller följande ytterligare prioritetsregler:

  • Allvarlighetsgradsalternativ som anges på kommandoraden som kompilatoralternativ (-nowarn eller -warnaserror) åsidosätter alltid de konfigurationsalternativ för allvarlighetsgrad som anges i EditorConfig och globala AnalyzerConfig-filer.

  • Prioritetsreglerna för motstridiga allvarlighetsgradsposter från en regeluppsättningsfil och en eller en EditorConfig global AnalyzerConfig-fil är odefinierad.

    Ruleset-filer är inaktuella till förmån EditorConfig för och globala AnalyzerConfig-filer. Vi rekommenderar att du konverterar regeluppsättningsfiler till en motsvarande EditorConfig fil.

  • Information om prioritetsregler för relaterade allvarlighetsalternativ med olika nycklar, till exempel när olika allvarlighetsgrader anges för en enskild regel och för den kategori som regeln faller under, finns i Konfigurationsalternativ för kodanalys.

Se även