Konfigurationsfiler för kodanalysregler
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å bulknivå, från att helt aktivera eller inaktivera kodanalys till regelkonfiguration 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 ett editorconfig avsnittshuvud 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
Du kan också 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.
Villkorsstyrd inkludering
Du kan använda en global konfigurationsfil för att inaktivera eller aktivera vissa kodanalysregler i olika miljöer. Du kanske till exempel vill inaktivera vissa kodanalysregler för enhetstestprojekt. För att göra det kan du ange allvarlighetsgraden för tillämpliga regler till i konfigurationsfilen, till none exempel:
# CA1861: Prefer 'static readonly' fields over constant array arguments
dotnet_diagnostic.CA1861.severity = none
Du kan sedan anpassa din version så att den endast inkluderar konfigurationsfilen i testprojekt baserat på villkor som är specifika för din version. Till exempel:
<ItemGroup Condition="'$(IsShipping)' == 'false'">
<!-- Include CodeAnalysis.test.globalconfig to override (relax) some rules from the primary configuration. -->
<GlobalAnalyzerConfigFiles Include="$(MSBuildThisFileDirectory)CodeAnalysis.test.globalconfig" />
</ItemGroup>
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 (
-nowarneller-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.
