Configuratiebestanden voor codeanalyseregels
Codeanalyseregels hebben verschillende configuratieopties. U geeft deze opties op als sleutel-waardeparen in een van de volgende analyseconfiguratiebestanden:
- EditorConfig bestand: configuratieopties op basis van bestanden of mappen.
- Global AnalyzerConfig-bestand : configuratieopties op projectniveau. Handig wanneer sommige projectbestanden zich buiten de projectmap bevinden.
Tip
U kunt ook configuratie-eigenschappen voor codeanalyse instellen in uw projectbestand. Met deze eigenschappen configureert u codeanalyse op bulkniveau, van het volledig in- of uitschakelen van codeanalyse tot de configuratie van regels op categorieniveau. Zie EnableNETAnalyzers, AnalysisLevel, AnalysisLevel<Category> en AnalysisMode voor meer informatie.
EditorConfig
EditorConfig bestanden worden gebruikt om opties te bieden die van toepassing zijn op specifieke bronbestanden of mappen. Opties worden geplaatst onder sectiekoppen om de toepasselijke bestanden en mappen te identificeren. Voeg een vermelding toe voor elke regel die u wilt configureren en plaats deze onder de bijbehorende bestandsextensiesectie, [*.cs]bijvoorbeeld.
[*.cs]
<option_name> = <option_value>
In het bovenstaande voorbeeld [*.cs] is een editorconfig sectieheader voor het selecteren van alle C#-bestanden met .cs de bestandsextensie in de huidige map, inclusief submappen. De volgende vermelding, <option_name> = <option_value>is een analyseoptie die wordt toegepast op alle C#-bestanden.
U kunt bestandsconventies toepassen EditorConfig op een map, een project of een hele opslagplaats door het bestand in de bijbehorende map te plaatsen. Deze opties worden toegepast bij het uitvoeren van de analyse tijdens het bouwen en tijdens het bewerken van code in Visual Studio.
Notitie
EditorConfig opties zijn alleen van toepassing op bronbestanden in een project of map. Bestanden die zijn opgenomen in een project als AdditionalFiles , worden niet beschouwd als bronbestanden en EditorConfig opties worden niet toegepast op deze bestanden. Als u een regeloptie wilt toepassen op niet-bronbestanden, geeft u de optie op in een globaal configuratiebestand.
Als u een bestaand .editorconfig -bestand hebt voor editorinstellingen, zoals inspringingsgrootte of het knippen van volgspaties, kunt u de configuratieopties voor codeanalyse in hetzelfde bestand plaatsen.
Tip
Visual Studio biedt een itemsjabloon .editorconfig waarmee u eenvoudig een van deze bestanden aan uw project kunt toevoegen. Zie Een bestand toevoegen EditorConfig aan een project voor meer informatie.
Opmerking
Hieronder volgt een voorbeeldbestand EditorConfig voor het configureren van opties en de ernst van regels:
# 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
U kunt ook analyseopties configureren met global AnalyzerConfig-bestanden . Deze bestanden worden gebruikt om opties te bieden die van toepassing zijn op alle bronbestanden in een project, ongeacht de bestandsnamen of bestandspaden.
In tegenstelling tot EditorConfig bestanden kunnen globale configuratiebestanden niet worden gebruikt voor het configureren van instellingen voor editorstijl voor IDE's, zoals inspringingsgrootte of om volgspaties te knippen. In plaats daarvan zijn ze alleen ontworpen voor het opgeven van configuratieopties voor analyse op projectniveau.
Notatie
In tegenstelling tot EditorConfig bestanden, die sectiekoppen moeten hebben, zoals [*.cs], om de toepasselijke bestanden en mappen te identificeren, hebben global AnalyzerConfig-bestanden geen sectieheaders. In plaats daarvan vereisen ze een vermelding op het hoogste niveau van het formulier is_global = true om ze te onderscheiden van gewone EditorConfig bestanden. Dit geeft aan dat alle opties in het bestand van toepassing zijn op het hele project. Voorbeeld:
is_global = true
<option_name> = <option_value>
Naamgeving
In tegenstelling tot EditorConfig bestanden, die een naam .editorconfigmoeten hebben, hoeven globale configuratiebestanden geen specifieke naam of extensie te hebben. Als u deze bestanden .globalconfigechter een naam krijgt, worden ze impliciet toegepast op alle C#- en Visual Basic-projecten in de huidige map, inclusief submappen. Anders moet u het item expliciet toevoegen aan uw GlobalAnalyzerConfigFiles MSBuild-projectbestand:
<ItemGroup>
<GlobalAnalyzerConfigFiles Include="<path_to_global_analyzer_config>" />
</ItemGroup>
Bekijk de volgende aanbevelingen voor naamgeving:
- Eindgebruikers moeten hun globale configuratiebestanden de naam .globalconfig noemen.
- NuGet-pakketmakers moeten hun globale configuratiebestanden <%Package_Name%>.globalconfig noemen.
- Door MSBuild-hulpprogramma's gegenereerde algemene configuratiebestanden moeten %Target_Name%_Generated.globalconfig of vergelijkbaar zijn.<>
Notitie
De vermelding is_global = true op het hoogste niveau is niet vereist wanneer het bestand de naam .globalconfigheeft, maar het wordt aanbevolen voor duidelijkheid.
Voorwaardelijke opname
U kunt een globaal configuratiebestand gebruiken om bepaalde codeanalyseregels in verschillende omgevingen uit te schakelen of in te schakelen. U kunt bijvoorbeeld enkele regels voor codeanalyse uitschakelen voor eenheidstestprojecten. Hiervoor kunt u de ernst voor de toepasselijke regels none instellen in het configuratiebestand, bijvoorbeeld:
# CA1861: Prefer 'static readonly' fields over constant array arguments
dotnet_diagnostic.CA1861.severity = none
Vervolgens kunt u uw build aanpassen om alleen het configuratiebestand in testprojecten op te nemen op basis van voorwaarden die specifiek zijn voor uw build. Voorbeeld:
<ItemGroup Condition="'$(IsShipping)' == 'false'">
<!-- Include CodeAnalysis.test.globalconfig to override (relax) some rules from the primary configuration. -->
<GlobalAnalyzerConfigFiles Include="$(MSBuildThisFileDirectory)CodeAnalysis.test.globalconfig" />
</ItemGroup>
Distributie in NuGet-pakketten
Global AnalyzerConfig-bestanden kunnen worden gedistribueerd met NuGet-pakketten. Voeg hiervoor een PROPS-bestand toe aan het NuGet-pakket . Voeg in het .props-bestand een GlobalAnalyzerConfigFiles item toe onder het Project knooppunt:
<Project>
<ItemGroup>
<GlobalAnalyzerConfigFiles Include="Relative/Path/to/PackageName.globalconfig" />
</ItemGroup>
</Project>
Opmerking
Hieronder volgt een voorbeeld van een global AnalyzerConfig-bestand voor het configureren van opties en de ernst van regels op projectniveau:
# 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
Prioriteit
Zowel EditorConfig bestanden als global AnalyzerConfig-bestanden geven voor elke optie een sleutel-waardepaar op. Conflicten ontstaan wanneer er meerdere vermeldingen met dezelfde sleutel maar verschillende waarden zijn. De volgende prioriteitsregels worden gebruikt om conflicten op te lossen.
| Conflicterende invoerlocaties | Prioriteitsregel |
|---|---|
| In hetzelfde configuratiebestand | De vermelding die later in het bestand wordt weergegeven, wint. Dit geldt voor conflicterende vermeldingen in één EditorConfig bestand en ook binnen één global AnalyzerConfig-bestand. |
| In twee EditorConfig bestanden | De vermelding in het EditorConfig bestand dat dieper in het bestandssysteem is en dus een langer bestandspad heeft, wint. |
| In twee global AnalyzerConfig-bestanden | .NET 5: Er wordt een compilerwaarschuwing gerapporteerd en beide vermeldingen worden genegeerd. .NET 6 en latere versies: de vermelding uit het bestand met een hogere waarde heeft global_level voorrang. Als global_level dit niet expliciet is gedefinieerd en het bestand de naam .globalconfig heeft, wordt de global_level waarde standaard 100ingesteld op ; voor alle andere global AnalyzerConfig-bestanden, global_level standaard ingesteld op 0. Als de global_level waarden voor de configuratiebestanden met conflicterende vermeldingen gelijk zijn, wordt een compilerwaarschuwing gerapporteerd en worden beide vermeldingen genegeerd. |
| In een EditorConfig bestand en een Global AnalyzerConfig-bestand | De vermelding in het EditorConfig bestand wint. |
Opties voor ernst
Voor opties voor ernstconfiguratie zijn de volgende aanvullende prioriteitsregels van toepassing:
Opties voor ernst die zijn opgegeven op de opdrachtregel als compileropties (
-nowarnof-warnaserror) overschrijven altijd de ernstconfiguratieopties die zijn opgegeven in EditorConfig en global AnalyzerConfig-bestanden.De prioriteitsregels voor conflicterende ernstvermeldingen uit een regelsetbestand en een EditorConfig of global AnalyzerConfig-bestand zijn niet gedefinieerd.
Regelset-bestanden worden afgeschaft ten gunste van EditorConfig en global AnalyzerConfig-bestanden. U wordt aangeraden regelsetbestanden te converteren naar een gelijkwaardig EditorConfig bestand.
Zie Configuratieopties voor codeanalyse voor informatie over prioriteitsregels voor gerelateerde ernstopties met verschillende sleutels, bijvoorbeeld wanneer verschillende ernstgroepen zijn opgegeven voor één regel en voor de categorie die regel valt onder configuratieopties voor codeanalyse.
