Konfigurationsdateien für Codeanalyseregeln
Für Codeanalyseregeln gibt es verschiedene Konfigurationsoptionen. Sie geben diese Optionen als Schlüssel-Wert-Paare in einer der folgenden Analysetool-Konfigurationsdateien an:
- EditorConfig-Datei: Datei- oder ordnerbasierte Konfigurationsoptionen.
- Globale AnalyzerConfig-Datei: Konfigurationsoptionen auf Projektebene. Ist hilfreich, wenn sich einige Projektdateien außerhalb des Projektordners befinden.
Tipp
Sie können auch Konfigurationseigenschaften für die Codeanalyse in Ihrer Projektdatei festlegen. Diese Eigenschaften konfigurieren die Codeanalyse auf Massenebene – vom vollständigen Ein- oder Ausschalten bis hin zur Konfiguration auf Kategorieebene. Weitere Informationen finden Sie unter EnableNETAnalyzers,, AnalysisLevel, AnalysisLevel<Category> und AnalysisMode.
EditorConfig
EditorConfig-Dateien werden zum Bereitstellen von Optionen verwendet, die für bestimmte Dateien oder Ordner gelten. Optionen werden unter Abschnittsüberschriften angeordnet, um die relevanten Dateien und Ordner zu identifizieren. Fügen Sie einen Eintrag für jede Regel hinzu, die Sie konfigurieren möchten, und legen Sie diesen im entsprechenden Abschnitt mit der Dateierweiterung ab, z. B. [*.cs].
[*.cs]
<option_name> = <option_value>
Im obigen Beispiel ist [*.cs] eine editorconfig-Abschnittsüberschrift, über die alle C#-Dateien mit der Dateierweiterung .cs im aktuellen Ordner, einschließlich Unterordner, ausgewählt werden. Beim nachfolgenden Eintrag <option_name> = <option_value> handelt es sich um eine Analysetooloption, die auf alle C#-Dateien angewendet wird.
Sie können EditorConfig-Dateikonventionen auf einen Ordner, ein Projekt oder ein gesamtes Repository anwenden, indem Sie die Datei im entsprechenden Verzeichnis ablegen. Diese Optionen werden bei der Durchführung der Analyse zur Buildzeit und beim Bearbeiten von Code in Visual Studio angewendet.
Hinweis
EditorConfigOptionen gelten nur für Source-Dateien in einem Projekt oder Verzeichnis. Dateien, die als AdditionalFiles in ein Projekt aufgenommen werden, gelten nicht als Quelldateien, und EditorConfig-Optionen werden nicht auf diese Dateien angewendet. Um eine Regeloption auf Nicht-Quelldateien anzuwenden, geben Sie die Option in einer globalen Konfigurationsdatei an.
Falls Sie über eine vorhandene .editorconfig-Datei für Editoreinstellungen verfügen, z. B. zur Einzugsgröße oder zum Kürzen von nachgestellten Leerzeichen, können Sie Ihre Konfigurationsoptionen für die Codeanalyse in dieselbe Datei einfügen.
Tipp
Visual Studio enthält eine .editorconfig-Elementvorlage, mit der Sie diese Dateien ganz einfach zu Ihrem Projekt hinzufügen können. Weitere Informationen finden Sie unter Hinzufügen einer EditorConfig-Datei zu einem Projekt.
Beispiel
Hier ist ein Beispiel für eine EditorConfig-Datei angegeben, mit der Sie Optionen und den Schweregrad von Regeln konfigurieren können:
# 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
Globale AnalyzerConfig-Datei
Sie können auch Analyseoptionen mit globalen AnalyzerConfig-Dateien konfigurieren. Mit diesen Dateien werden Optionen bereitgestellt, die für alle Quelldateien eines Projekts gelten, und zwar unabhängig von den Dateinamen oder -pfaden.
Im Gegensatz zu EditorConfig-Dateien können globale Konfigurationsdateien nicht verwendet werden, um Editorformateinstellungen für IDEs, z. B. Einzugsgröße oder Kürzung von nachgestellten Leerzeichen, zu konfigurieren. Stattdessen sind sie ausschließlich zum Angeben von Analysetool-Konfigurationsoptionen auf Projektebene konzipiert.
Format
Im Gegensatz zu EditorConfig-Dateien, die zum Identifizieren der relevanten Dateien und Ordner über Abschnittsüberschriften (z. B. [*.cs]) verfügen müssen, werden in globalen AnalyzerConfig-Dateien keine Abschnittsüberschriften verwendet. Stattdessen benötigen Sie einen Eintrag der obersten Ebene im Format is_global = true, um die Unterscheidung von regulären EditorConfig-Dateien zu ermöglichen. Dies ist ein Hinweis darauf, dass alle Optionen in der Datei für das gesamte Projekt gelten. Beispiel:
is_global = true
<option_name> = <option_value>
Benennung
Im Gegensatz zu EditorConfig-Dateien, die den Namen .editorconfig aufweisen müssen, wird für globale Konfigurationsdateien kein bestimmter Name und keine besondere Erweiterung benötigt. Wenn Sie diesen Dateien aber den Namen .globalconfig geben, werden sie implizit auf alle C#- und Visual Basic-Projekte des aktuellen Ordners angewendet, einschließlich auf alle Unterordner. Andernfalls müssen Sie das Element GlobalAnalyzerConfigFiles explizit Ihrer MSBuild-Projektdatei hinzufügen:
<ItemGroup>
<GlobalAnalyzerConfigFiles Include="<path_to_global_analyzer_config>" />
</ItemGroup>
Beachten Sie die folgenden Empfehlungen zur Benennung:
- Endbenutzer sollten ihren globalen Konfigurationsdateien den Namen .globalconfig geben.
- NuGet-Paketersteller sollte ihre globalen Konfigurationsdateien <%Package_Name%>.globalconfig nennen.
- Mithilfe von MSBuild-Tools generierte globale Konfigurationsdateien sollten <%Target_Name%>_Generated.globalconfig oder ähnlich genannt werden.
Hinweis
Der is_global = true-Eintrag auf oberster Ebene ist nicht erforderlich, wenn die Datei den Namen .globalconfig erhält, wird jedoch aus Gründen der Klarheit empfohlen.
Bedingte Inklusion
Sie können eine globale Konfigurationsdatei verwenden, um bestimmte Codeanalyseregeln in verschiedenen Umgebungen zu deaktivieren oder zu aktivieren. Sie möchten z. B. einige Codeanalyseregeln für Komponententestprojekte deaktivieren. Dazu können Sie den Schweregrad für die anwendbaren Regeln in der Konfigurationsdatei auf none festlegen, z. B.:
# CA1861: Prefer 'static readonly' fields over constant array arguments
dotnet_diagnostic.CA1861.severity = none
Anschließend können Sie den Build so anpassen, dass er nur die Konfigurationsdatei in Testprojekte einschließt, basierend auf den für den Build spezifischen Bedingungen. Zum Beispiel:
<ItemGroup Condition="'$(IsShipping)' == 'false'">
<!-- Include CodeAnalysis.test.globalconfig to override (relax) some rules from the primary configuration. -->
<GlobalAnalyzerConfigFiles Include="$(MSBuildThisFileDirectory)CodeAnalysis.test.globalconfig" />
</ItemGroup>
Verteilung in NuGet-Paketen
Globale AnalyzerConfig-Dateien können mit NuGet-Paketen verteilt werden. Fügen Sie dazu eine PROPS-Datei zum NuGet-Paket hinzu. Fügen Sie in der PROPS-Datei ein GlobalAnalyzerConfigFiles-Element unter dem Project-Knoten hinzu:
<Project>
<ItemGroup>
<GlobalAnalyzerConfigFiles Include="Relative/Path/to/PackageName.globalconfig" />
</ItemGroup>
</Project>
Beispiel
Hier ist ein Beispiel für eine globale AnalyzerConfig-Datei angegeben, mit der Optionen und der Schweregrad von Regeln auf Projektebene konfiguriert wird:
# 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
Rangfolge
Sowohl bei EditorConfig-Dateien als auch bei globalen AnalyzerConfig-Dateien wird für jede Option ein Schlüssel-Wert-Paar angegeben. Es kommt zu Konflikten, wenn mehrere Einträge mit dem gleichen Schlüssel vorhanden sind, die aber unterschiedliche Werte aufweisen. Die folgenden Rangfolgenregeln werden zum Beheben von Konflikten verwenden.
| In Konflikt stehende Einstiegspunkte | Rangfolgeregel |
|---|---|
| In derselben Konfigurationsdatei | Der Eintrag, der weiter unten in der Datei vorkommt, erhält Vorrang. Dies gilt für in Konflikt stehende Einträge sowohl in einer einzelnen EditorConfig-Datei als auch in einer einzelnen globalen AnalyzerConfig-Datei. |
| In zwei EditorConfig-Dateien | Der Eintrag in der EditorConfig-Datei, der tiefer in das Dateisystem eingebettet ist und deshalb über den längeren Pfad verfügt, erhält Vorrang. |
| In zwei globalen AnalyzerConfig-Dateien | .NET 5: Es wird eine Compilerwarnung gemeldet, und beide Einträge werden ignoriert. .NET 6 und höhere Versionen: Der Eintrag aus der Datei mit einem höheren Wert für global_level hat Vorrang. Wenn global_level nicht explizit definiert ist und die Datei den Namen .globalconfig hat, wird der global_level-Wert standardmäßig auf 100 festgelegt. Für alle anderen globalen AnalyzerConfig-Dateien wird global_level standardmäßig auf 0 festgelegt. Wenn die global_level-Werte für die Konfigurationsdateien mit in Konflikt stehenden Einträgen gleich sind, wird eine Compilerwarnung gemeldet, und beide Einträge werden ignoriert. |
| In einer EditorConfig-Datei und einer globalen AnalyzerConfig-Datei | Der Eintrag in der EditorConfig-Datei gewinnt. |
Optionen zum Schweregrad
Für Optionen zum Konfigurieren des Schweregrads gelten die folgenden zusätzlichen Rangfolgeregeln:
Optionen zum Schweregrad, die in der Befehlszeile als Compileroptionen angegeben werden (
-nowarnoder-warnaserror), haben immer Vorrang vor Optionen für die Konfiguration des Schweregrads, die in EditorConfig- und globalen AnalyzerConfig-Dateien angegeben werden.Die Rangfolgeregeln für in Konflikt stehende Einträge zum Schweregrad aus einer Regelsatzdatei und aus EditorConfig- oder globalen AnalyzerConfig-Dateien ist nicht definiert.
Regelsatzdateien wurden als veraltet eingestuft und werden durch EditorConfig- und globale AnalyzerConfig-Dateien ersetzt. Es wird empfohlen, Regelsatzdateien in eine äquivalente EditorConfig-Datei zu konvertieren.
Informationen zu den Rangfolgeregeln für verwandte Schweregradoptionen mit unterschiedlichen Schlüsseln (z. B. wenn für eine Regel und die Kategorie dieser Regel unterschiedliche Schweregrade angegeben werden) finden Sie unter Konfigurationsoptionen für die Codeanalyse.
