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.

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.

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.

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.

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.

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

Siehe auch

• EditorConfig- und globale AnalyzerConfig-Datei: Entwurfsproblem