Konfigurationsoptionen für die Codeanalyse

  • Artikel

Für Codeanalyseregeln gibt es verschiedene Konfigurationsoptionen. Einige dieser Optionen werden als Schlüssel-Wert-Paare in einer Analysetool-Konfigurationsdatei mithilfe der Syntax <option key> = <option value> angegeben. Andere Optionen, die die Codeanalyse als Ganzes konfigurieren, sind als MSBuild-Eigenschaften in der Projektdatei verfügbar.

Die am häufigsten konfigurierte Option ist der Schweregrad einer Regel. Sie können den Schweregrad für alle Regeln konfigurieren, einschließlich Codequalitätsregeln und Regeln für den Codestil. Wenn Sie z. B. eine Regel als Warnung aktivieren möchten, können Sie einer Analysetool-Konfigurationsdatei das folgende Schlüssel-Wert-Paar hinzufügen:

dotnet_diagnostic.<rule ID>.severity = warning

Sie können auch zusätzliche Optionen zum Anpassen des Regelverhaltens konfigurieren:

  • Codequalitätsregeln verfügen über Verhaltensoptionen, z. B. bezüglich der Methodennamen, auf die eine Regel angewendet werden soll.
  • Codeformatregeln bieten Optionen für Formateinstellungen, um z. B. anzugeben, wo neue Zeilen wünschenswert sind.
  • Analysetoolregeln von Drittanbietern können eigene Konfigurationsoptionen mit benutzerdefinierten Schlüsselnamen und Wertformaten definieren.

Allgemeine Optionen

Diese Optionen gelten für die Codeanalyse als Ganzes. Sie können nicht nur auf eine bestimmte Regel angewendet werden.

Weitere Optionen finden Sie unter Codeanalyseeigenschaften.

Analysemodus

Das .NET SDK enthält zwar alle Codeanalyseregeln, aber nur einige davon sind standardmäßig aktiviert. Der Analysemodus bestimmt, welche Regelsätze (falls vorhanden) aktiviert werden sollen. Sie können einen aggressiveren Analysemodus auswählen, in dem die meisten oder alle Regeln aktiviert sind. Oder Sie wählen einen konservativeren Analysemodus, in dem die meisten oder alle Regeln deaktiviert sind. Anschließend können Sie bei Bedarf bestimmte Regeln aktivieren. Legen Sie den Analysemodus fest, indem Sie der Projektdatei die <AnalysisMode>-MSBuild-Eigenschaft hinzufügen.

<PropertyGroup>
  <AnalysisMode>Recommended</AnalysisMode>
</PropertyGroup>

Ab .NET 6 können Sie auch eine Regelkategorie mithilfe der MSBuild-Eigenschaft <AnalysisMode<Category>> massenweise aktivieren.

Hinweis

Wenn Sie die Codeanalyse mithilfe von MSBuild-Eigenschaften wie z. B. AnalysisMode konfigurieren, werden alle Massenkonfigurationsoptionen ignoriert, die Sie in Ihrer Konfigurationsdatei festgelegt haben. Wenn Sie beispielsweise alle Regeln oder eine Regelkategorie in einer .editorconfig-Datei massenweise aktiviert haben, wird diese Konfiguration ignoriert.

Codeanalyse aktivieren

Die Codeanalyse ist für Projekte, die auf .NET 5 oder höher ausgerichtet sind, und ältere Versionen standardmäßig aktiviert. Falls Sie über .NET 5+ SDK verfügen, aber das Projekt eine andere .NET-Implementierung als Ziel verwendet, können Sie die Codeanalyse manuell aktivieren, indem Sie die EnableNETAnalyzers-Eigenschaft in Ihrer Projektdatei auf true festlegen.

<PropertyGroup>
  <EnableNETAnalyzers>true</EnableNETAnalyzers>
</PropertyGroup>

Ausschließen von generiertem Code

Warnungen des .NET Code Analysetools sind für generierte Codedateien (z. B. vom Designer generierte Dateien) nicht sinnvoll, die Benutzer nicht bearbeiten können, um Verstöße zu beheben. In den meisten Fällen überspringen Codeanalysetools generierte Codedateien und melden keine Verstöße gegen diese Dateien.

Standardmäßig werden Dateien mit bestimmten Dateierweiterungen oder automatisch generierten Dateiheadern als generierte Codedateien behandelt. Beispielsweise wird ein Dateiname, der mit .designer.cs oder .generated.cs endet, als generierter Code betrachtet. Mit dieser Konfigurationsoption können Sie zusätzliche Benennungsmuster angeben, die als generierter Code behandelt werden sollen. Sie können zusätzliche Dateien und Ordner konfigurieren, indem Sie der Konfigurationsdatei einen generated_code = true | false-Eintrag hinzufügen. Fügen Sie z. B. den folgenden Eintrag hinzu, um alle Dateien, deren Name mit .MyGenerated.cs endet, als generierten Code zu behandeln:

[*.MyGenerated.cs]
generated_code = true

Regelspezifische Optionen

Regelspezifische Optionen können auf eine einzelne Regel, einen Regelsatz oder alle Regeln angewendet werden. Zu den regelspezifische Optionen gehören:

Schweregrad

In der folgenden Tabelle werden die verschiedenen Regelschweregrade angezeigt, die Sie für alle Analysetoolregeln konfigurieren können, einschließlich Regeln für Codequalität und Codestil.

Konfigurationswert für Schweregrad Verhalten zur Buildzeit
error Verstöße werden als Buildfehler angezeigt und bewirken, dass Builds fehlschlagen.
warning Verstöße werden als Buildwarnungen angezeigt, bewirken jedoch nicht, dass Builds fehlschlagen (es sei denn, es besteht eine Option zum Behandeln von Warnungen als Fehler).
suggestion Verstöße werden als Buildmeldungen und als Vorschläge in der Visual Studio-IDE angezeigt. (In Visual Studio werden Vorschläge in Form von drei grauen Punkten unter den ersten zwei Zeichen dargestellt.)
silent Verstöße sind für den Benutzer nicht sichtbar.

Bei Codestilregeln generieren Visual Studio-Codegenerierungsfeatures jedoch weiterhin Code in diesem Stil. Diese Regeln gelten auch für Bereinigungsvorgänge und werden im Menü Schnellaktionen und Refactorings angezeigt.
none Die Regel wird vollständig unterdrückt.

Bei Codestilregeln generieren Visual Studio-Codegenerierungsfeatures jedoch weiterhin Code in diesem Stil.
default Der Standardschweregrad der Regel wird verwendet. Die Standardschweregrade für jedes .NET-Release werden im Repository roslyn-analyzers aufgeführt. In dieser Tabelle entspricht „Disabled“ (Deaktiviert) none, „Hidden“ (Ausgeblendet) silent und „Info“ suggestion.

`Scope`

  • Einzelne Regel

    Verwenden Sie die folgende Syntax, um den Regelschweregrad für eine einzelne Regel festzulegen.

    dotnet_diagnostic.<rule ID>.severity = <severity value>

  • Kategorie von Regeln

    Verwenden Sie die folgende Syntax, um den Standardregelschweregrad für eine Kategorie von Regeln festzulegen. Diese Schweregradeinstellung wirkt sich jedoch nur auf Regeln in dieser Kategorie aus, die standardmäßig aktiviert sind.

    dotnet_analyzer_diagnostic.category-<rule category>.severity = <severity value>

    Die verschiedenen Kategorien werden unter Regelkategorien aufgeführt und beschrieben. Darüber hinaus finden Sie die Kategorie für eine bestimmte Regel auf ihrer Referenzseite, z. B. CA1000.

  • Alle Regeln

    Verwenden Sie die folgende Syntax, um den Standardregelschweregrad für alle Analysetoolregeln festzulegen. Diese Schweregradeinstellung wirkt sich jedoch nur auf Regeln aus, die standardmäßig aktiviert sind.

    dotnet_analyzer_diagnostic.severity = <severity value>

Wichtig

Wenn Sie den Schweregrad für mehrere Regeln mit einem einzigen Eintrag konfigurieren (für eine Kategorie von Regeln oder für alle Regeln), gilt der Schweregrad nur für Regeln, die standardmäßig aktiviert sind. Und wenn Sie alle Regeln mithilfe der MSBuild-Eigenschaften <AnalysisMode> oder <AnalysisLevel> aktivieren, werden alle dotnet_analyzer_diagnostic-Massenoptionen ignoriert. Aus diesem Grund ist es besser, eine Regelkategorie zu aktivieren, indem Sie <AnalysisMode<Category>> auf All festlegen.

Hinweis

Das Präfix dotnet_diagnostic zum Festlegen des Schweregrads für eine einzelne Regel unterscheidet sich geringfügig vom Präfix dotnet_analyzer_diagnostic zum Konfigurieren des Schweregrads nach Kategorie oder für alle Regeln.

Rangfolge

Wenn Sie über mehrere Konfigurationseinträge für den Schweregrad verfügen, die auf dieselbe Regel-ID angewendet werden können, wird die Rangfolge in der folgenden Reihenfolge ausgewählt:

  • Ein Eintrag für eine Kategorie besitzt Vorrang vor einem Eintrag für alle Analysetoolregeln.
  • Ein Eintrag für eine einzelne Regel nach ID besitzt Vorrang vor einem Eintrag für eine Kategorie.

Sehen Sie sich das folgende Beispiel an, in dem CA1822 die Kategorie „Performance“ (Leistung) aufweist:

[*.cs]
dotnet_diagnostic.CA1822.severity = error
dotnet_analyzer_diagnostic.category-performance.severity = warning
dotnet_analyzer_diagnostic.severity = suggestion

Im Beispiel oben sind alle drei Schweregrade auf CA1822 anwendbar. Bei Verwendung der angegebenen Rangfolgeregeln besitzt der erste auf der Regel-ID basierende Eintrag Vorrang vor den nächsten Einträgen. In diesem Beispiel weist CA1822 den effektiven Schweregrad error auf. Alle anderen Regeln in der Kategorie „Performance“ (Leistung) weisen den Schweregrad warning auf.

Informationen dazu, wie der Vorrang zwischen Dateien festgelegt wird, finden Sie im Abschnitt „Vorrang“ des Artikels „Konfigurationsdateien“.