Anpassen von Roslyn-Analyseregeln

Jede Regel oder Diagnose des Roslyn-Analysetools weist einen Standardstatus bezüglich Schweregrad und Unterdrückung auf, den Sie für Ihr Projekt anpassen können. In diesem Artikel werden das Festlegen von Schweregraden des Analysetools und das Unterdrücken von Verstößen im Analysetool behandelt.

Schweregrade

In Visual Studio 2019, Version 16.3 und neuer, können Sie den Schweregrad von Analysetoolregeln in einer EditorConfig-Datei über das Fehlerbehebungsmenü (Glühbirne) und über das Fenster Fehlerliste konfigurieren.

In der folgenden Tabelle sind die verschiedenen Schweregradoptionen aufgeführt, die Sie für eine Diagnose konfigurieren können:

Schweregrad (Projektmappen-Explorer)	Schweregrad (EditorConfig-Datei)	Verhalten zur Buildzeit	Editor-Verhalten
Fehler	error	Verstöße werden in der Registerkarte Fehler im Fenster Fehlerliste und in der Befehlszeilen-Buildausgabe angezeigt und bewirken, dass Builds fehlschlagen.	Der betreffende Code wird mit einer roten Wellenlinie unterstrichen und in der Scrollleiste durch ein kleines rotes Feld markiert.
Warnung	warning	Verstöße werden in der Registerkarte Warnung im Fenster Fehlerliste und in der Befehlszeilen-Buildausgabe angezeigt, führen aber nicht dazu, dass Builds fehlschlagen.	Der betreffende Code wird mit einer grünen Wellenlinie unterstrichen und in der Scrollleiste durch ein kleines grünes Feld markiert.
Vorschlag	suggestion	Verstöße werden in der Registerkarte Meldung im Fenster Fehlerliste angezeigt, aber in der Befehlszeilen-Buildausgabe nicht.	Der betreffende Code wird mit einer grauen Wellenlinie unterstrichen und in der Scrollleiste durch ein kleines graues Feld markiert.
Silent	silent	Für den Benutzer unsichtbar.	Unsichtbar für den Benutzer, aber die Diagnose wird an das IDE-Diagnosemodul gemeldet.
Keine	none	Vollständig unterdrückt.	Vollständig unterdrückt.
Standard	default	Entspricht dem Standardschweregrad der Regel. Um den Standardwert für eine Regel zu ermitteln, zeigen Sie ihr Eigenschaftenfenster an.	Entspricht dem Standardschweregrad der Regel.

Anzeigen von Regelverstößen

Wenn ein Analyzer Regelverstöße findet, meldet er sie im Fenster Fehlerliste und im Code-Editor.

Der folgende Screenshot zeigt Regelverstöße, die im Fenster Fehlerliste gemeldet wurden. Die in der Fehlerliste gemeldeten vom Analysetool gefundenen Verstöße stimmen mit der Einstellung für den Schweregrad der Regel überein:

Außerdem werden die Analysetool-Regelverstöße auch im Code-Editor als Wellenlinie unter dem fehlerhaften Code angezeigt. In dem folgenden Screenshot werden zum Beispiel drei Verstöße angezeigt ein Fehler (rote Wellenlinie), eine Warnung (grüne Wellenlinie) und ein Vorschlag (drei graue Punkte):

Viele Diagnosen verfügen über mindestens einen Codefix, den Sie zur Korrektur von Regelverstößen anwenden können. Codekorrekturen werden zusammen mit anderen schnellen Aktionen im Fehlerbehebungsmenü (Glühbirnensymbol) angezeigt. Weitere Informationen zu Codefixen siehe Häufige schnelle Aktionen.

Konfigurieren von Schweregraden

Sie können den Regelschweregrad mit einer der folgenden Methoden festlegen:

• EditorConfig
• Fehlerbehebungsmenü
• Fehlerliste (Fenster)
• Projektmappen-Explorer

Unbeaufsichtigter Schweregrad im Vergleich zu keinem Schweregrad

Silent-Schweregradregeln, die standardmäßig aktiviert sind, unterscheiden sich von deaktivierten Regeln bzw. None-Schweregradregeln:

• Wenn eine Codekorrektur für eine Silent-Schweregradregel registriert ist, bietet Visual Studio die Codekorrektur als Refactoring-Aktion im Fehlerbehebungsmenü (Glühbirne) an, selbst wenn die ausgeblendete Diagnose für den Benutzer nicht sichtbar ist. Wenn die Schweregradregel als None deaktiviert ist, wird die Codekorrektur nicht angeboten, .
• Einträge, die den Regelschweregrad mehrerer Analysetoolregeln gleichzeitig in einer EditorConfig-Datei festlegen, können Silent-Sicherheitsregeln massenweise konfigurieren. None-Schweregradregeln können nicht auf diese Weise konfiguriert werden. Stattdessen müssen sie über Einträge konfiguriert werden, die den Schweregrad in einer EditorConfig-Datei für jede Regel-ID festlegen.

Festlegen des Regelschweregrads in einer EditorConfig-Datei

EditorConfig-Dateien sind in Visual Studio 2019, Version 16.3 und höher, verfügbar.

Das Festlegen des Schweregrads einer Regel in einer EditorConfig-Datei besitzt Vorrang vor einem Schweregrad, der in einem Regelsatz oder im Projektmappen-Explorer festgelegt ist. Sie können den Schweregrad in einer EditorConfig-Datei entweder manuell oder automatisch über die Glühbirne konfigurieren, die neben einem Verstoß angezeigt wird.

Manuelles Konfigurieren des Regelschweregrads in einer EditorConfig-Datei

Gehen Sie folgendermaßen vor, um den Regelschweregrad zu konfigurieren:

1. Fügen Sie eine EditorConfig-Datei für Ihr Projekt hinzu, wenn Sie noch nicht über eine verfügen.

2. Fügen Sie unter der entsprechenden Dateierweiterung einen Eintrag für jede Regel hinzu, die Sie konfigurieren möchten.

   Damit der Eintrag den Schweregrad für CA1822 beispielsweise auf error für C#-Dateien festlegt, gehen Sie folgendermaßen vor:

   [*.cs]
   dotnet_diagnostic.CA1822.severity = error
   

3. Sie können den Regelschweregrad für jede Diagnoseregel-ID in einer EditorConfig-Datei mit der folgenden Syntax festlegen:

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

4. Bei Analysetools im IDE-Codestil kann die Konfiguration ebenfalls in einer EditorConfig-Datei erfolgen, indem eine andere Syntax verwendet wird.

   Beispiel: dotnet_style_qualification_for_field = false:suggestion. Wenn Sie jedoch einen Schweregrad mit der dotnet_diagnostic-Syntax festlegen, besitzt dieser Vorrang. Weitere Informationen finden Sie unter Sprachkonventionen für EditorConfig.

Legen Sie den Regelschweregrad für mehrere Analysetoolregeln in einer EditorConfig-Datei gleichzeitig fest

Die Möglichkeit zum gleichzeitigen Festlegen mehrerer Analyseregeln in einer EditorConfig-Datei ist in Visual Studio 2019, Version 16.5 und höher, verfügbar.

Sie können den Schweregrad für eine bestimmte Kategorie von Analysetoolregeln oder für alle Analysetoolregeln mit einem einzelnen Eintrag in einer EditorConfig-Datei festlegen:

• Festlegen des Regelschweregrads für eine Kategorie von Analysetoolregeln:

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

• Festlegen des Regelschweregrads für alle Analysetoolregeln:

  dotnet_analyzer_diagnostic.severity = <severity>

Einträge, die mehrerer Analysetoolregeln gleichzeitigen konfigurieren, gelten nur für Regeln, die standardmäßig aktiviert sind. Analysetoolregeln, die im Analysetoolpaket standardmäßig als deaktiviert gekennzeichnet sind, müssen über explizite dotnet_diagnostic.<rule ID>.severity = <severity>-Einträge aktiviert werden.

Wenn Sie über mehrere Einträge verfügen, die auf eine bestimmte Regel-ID anwendbar sind, hält sich die Rangfolge für den anwendbaren Eintrag an folgende Reihenfolge:

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

Sehen Sie sich das folgende EditorConfig-Beispiel an, wo CA1822 eine Leistungsregel ist:

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

In diesem Beispiel gelten alle drei Einträge für die Leistungsregel CA1822. Bei Verwendung der angegebenen Rangfolgeregeln hat der erste auf der Regel-ID basierende Schweregradeintrag jedoch Vorrang vor den nächsten Einträgen. In diesem Beispiel weist CA1822 den effektiven Schweregrad error auf. Die verbleibenden Leistungsregeln haben einen Schweregrad von warning. Die Analyseregeln, die keine Leistungsregeln sind, weisen einen Schweregrad von suggestion auf.

Festlegen des Regelschweregrads über das Fehlerbehebungsmenü (Glühbirne)

Visual Studio bietet eine bequeme Möglichkeit, den Schweregrad einer Regel über das Fehlerbehebungsmenü Schnelle Aktionen zu konfigurieren. Führen Sie folgende Schritte aus:

1. Nachdem ein Verstoß aufgetreten ist, Zeigen Sie im Editor mit dem Mauszeiger auf Verstoßwellenlinie und wählen Potenzielle Korrekturen anzeigen aus, um das Fehlerbehebungsmenü (Glühbirne) zu öffnen. Oder Sie platzieren den Cursor in der Zeile und drücken STRG+. (Punkt).

2. Bewegen Sie den Mauszeiger im Glühbirnenmenü über einen Schweregrad, um eine Vorschau der Änderung zu erhalten, und konfigurieren Sie den Schweregrad dann entsprechend den folgenden Optionen:

   • Konfigurieren sie den Schweregrad der <Regel-ID>. Legen Sie den Schweregrad für die bestimmte Regel fest.

   • Konfigurieren Sie den Schweregrad für alle <Stil>-Analysetools. Legen Sie den Schweregrad für alle Regeln in der bestimmten Regelkategorie fest.

   • Konfigurieren Sie den Schweregrad für alle Analysetools. Legen Sie den Schweregrad für alle Kategorien von Analysetool-Regeln fest.

     Wählen Sie im folgenden Beispiel Probleme unterdrücken oder konfigurieren>Konfigurieren <-Regel-ID>-Schweregrad aus.

     

3. Wählen Sie eine der Optionen für den Schweregrad aus.

   

   Visual Studio fügt der EditorConfig-Datei einen Eintrag hinzu, um die Regel auf das angeforderte Schweregradlevel zu konfigurieren, wie im Vorschaufeld angezeigt.

   Wenn Sie noch nicht über eine EditorConfig-Datei im Projekt verfügen, erstellt Visual Studio eine solche Datei für Sie.

Festlegen des Regelschweregrads über das Fenster „Fehlerliste“

Visual Studio bietet auch eine bequeme Möglichkeit zum Konfigurieren des Schweregrads einer Regel über das Kontextmenü der „Fehlerliste“. Führen Sie folgende Schritte aus:

1. Wenn ein Verstoß auftritt, klicken Sie mit der rechten Maustaste auf den Diagnoseeintrag in der Fehlerliste.

2. Wählen Sie im Kontextmenü Schweregrad festlegen und dann eine der Schweregradoptionen aus.

   

   Visual Studio fügt der EditorConfig-Datei einen Eintrag hinzu, um die Regel auf der angeforderten Ebene zu konfigurieren.

   Wenn Sie noch nicht über eine EditorConfig-Datei im Projekt verfügen, erstellt Visual Studio eine solche Datei für Sie.

Festlegen des Regelschweregrads im Projektmappen-Explorer

Führen Sie die folgenden Schritte aus, um den Regelschweregrad von Projektmappen-Explorer festzulegen:

1. Erweitern Sie im Projektmappen-Explorer Verweise>Analysetools (oder Abhängigkeiten>Analysetools für .NET Core-Projekte).

2. Erweitern Sie die Assembly, die die Regel enthält, für die Sie den Schweregrad festlegen möchten.

3. Klicken Sie mit der rechten Maustaste auf die Regel, und wählen Sie Schweregrad festlegen aus. Wählen Sie im Kontextmenü eine der Schweregradoptionen aus.

   Visual Studio fügt der EditorConfig-Datei einen Eintrag hinzu, um die Regel auf der angeforderten Ebene zu konfigurieren. Wenn Ihr Projekt eine Regelsatzdatei anstelle einer EditorConfig-Datei verwendet, wird der Eintrag für den Schweregrad der Regelsatzdatei hinzugefügt.

   Wenn Sie noch keine EditorConfig-Datei oder Regelsatzdatei im Projekt haben, erstellt Visual Studio eine neue EditorConfig-Datei für Sie.

Anzeigen von Analysetools und Diagnosen aus Projektmappen-Explorer

Sie können einen Großteil der Anpassung der Analysetooldiagnosen im Projektmappen-Explorer ausführen. Wenn Sie ein Analysetools als NuGet-Paket installieren, wird ein Knoten Analysetools unter dem Knoten Verweise (oder dem Knoten Abhängigkeiten für .NET-Knotenprojekte) im Projektmappen-Explorer angezeigt. Führen Sie die folgenden Schritte aus, um die Analysetools und Diagnosen anzuzeigen:

1. Erweitern Sie in Projektmappen-Explorer Ihr Projekt, erweitern Sie Verweise oder Abhängigkeiten, und erweitern Sie dann Analysetools. Erweitern Sie eine der Analysetool-Assemblies, um die Diagnose in der Assembly anzuzeigen.

   Das Symbol neben den einzelnen Diagnosen gibt die Schweregrad an:

   • Das x in einem Kreis zeigt den Schweregrad Fehler an.
   • Das ! in einem Dreieck zeigt den Schweregrad Warnung an.
   • i in einem durchgezogenen Kreis zeigt den Schweregrad des Vorschlags an.
   • i in einem gepunkteten Kreis zeigt den Schweregrad von Lautlos an
   • Nach unten zeigender Pfeil in einem durchgezogenen Kreis zeigt den Schweregrad Kein an.

   

2. Um die Eigenschaften einer Diagnose, einschließlich ihrer Beschreibung und ihres Standardschweregrads, anzuzeigen, klicken Sie mit der rechten Maustaste auf die Diagnose und wählen Sie dann Eigenschaften. Oder wählen Sie die Diagnose aus, und drücken Sie dann die Alt+Eingabetaste.

   Das Fenster Eigenschaften wird angezeigt.

   

3. Um Eigenschaften für Codeformatregeln (IDE-Präfix) wie z. B. Standardschweregrad im Fenster Eigenschaften anzuzeigen, legen Sie die EnforceCodeStyleInBuild-Eigenschaft auf true fest.

4. Für eine Onlinedokumentation für eine Diagnose klicken Sie mit der rechten Maustaste auf die Diagnose, und wählen Sie dann Hilfe anzeigen aus.

Konvertieren einer vorhandenen Regelsatzdatei in eine EditorConfig-Datei

In Visual Studio 2019, Version 16.5 und neuer wurden Regelsatzdateien zugunsten von EditorConfig-Dateien für die Analysetoolkonfiguration für verwalteten Code eingestellt. Mit EditorConfig-Dateien sind flexibler, und Sie können sowohl Schweregrade von Analysetoolregeln als auch Analysetooloptionen konfigurieren, einschließlich Visual Studio-IDE-Codestiloptionen. Da die Visual Studio-Tools für die Schweregradkonfiguration von Analysetool-Regeln jetzt für die Arbeit mit EditorConfig-Dateien und nicht für Regelsätze optimiert sind, empfiehlt es sich, vorhandene Projekte zu konvertieren, die weiterhin Regelsatzdateien verwenden.

Wenn Sie die vorhandene Regelsatzdatei in eine EditorConfig-Datei konvertieren, speichern Sie sie im Stammverzeichnis Ihres Repositorys oder im Lösungsordner. Dadurch wird sichergestellt, dass die Schweregradeinstellungen dieser Datei automatisch auf das gesamte Repository bzw. die gesamte Lösung angewendet werden.

Sie können eine vorhandene Regelsatzdatei in eine EditorConfig-Datei konvertieren, indem Sie entweder den Regelsatz-Editor oder die Befehlszeile verwenden.

Hinweis

.NET Core- und .NET Standard-Projekte unterstützen die Menübefehle für Regelsätze im Projektmappen-Explorer nicht (etwa Aktiven Regelsatz öffnen). Wenn Sie einen nicht standardmäßigen Regelsatz für ein .NET Core- oder .NET Standard-Projekt angeben möchten, fügen Sie der Projektdatei manuell die Eigenschaft CodeAnalysisRuleSet hinzu. Sie können die Regeln im Regelsatz weiterhin im Regelsatz-Editor konfigurieren.

Führen Sie die folgenden Schritte aus, um den Regelsatz-Editor zu verwenden. Wenn Ihr Projekt bereits eine bestimmte Regelsatzdatei für seinen CodeAnalysisRuleSet-Eigenschaftswert verwendet, können Sie sie im Regelsatz-Editor in eine entsprechende EditorConfig-Datei konvertieren:

1. Doppelklicken Sie im Projektmappen-Explorer auf die Regelsatzdatei.

   Die Regelsatzdatei wird im Regelsatz-Editor mit einer klickbaren Infoleiste oben geöffnet.

   

2. Wählen Sie den Link Infoleiste aus, um die Regelsatz-Editordatei zu migrieren.

3. Wählen Sie im Dialogfeld Speichern unter das Verzeichnis aus, in dem Sie die EditorConfig-Datei generieren möchten, und wählen Sie dann "Speichern aus.

   Die generierte EditorConfig-Datei öffnet sich im Editor. Darüber hinaus wird die MSBuild-Eigenschaft CodeAnalysisRuleSet in der Projektdatei so aktualisiert, dass sie nicht mehr auf die ursprüngliche Regelsatzdatei verweist.

führen Sie diese Schritte aus, um die Befehlszeile zu verwenden:

1. Installieren Sie das NuGet-Paket Microsoft.CodeAnalysis.RulesetToEditorconfigConverter.

2. Führen Sie RulesetToEditorconfigConverter.exe aus dem installierten Paket mit Pfaden zur Regelsatzdatei und zur EditorConfig-Datei als Befehlszeilenargumenten aus.

   Zum Beispiel:

   Usage: RulesetToEditorconfigConverter.exe <%ruleset_file%> [<%path_to_editorconfig%>]
   

Das folgende Beispiel zeigt eine Regelsatzdatei, die in eine EditorConfig-Datei konvertiert werden soll:

<?xml version="1.0" encoding="utf-8"?>
<RuleSet Name="Rules for ConsoleApp" Description="Code analysis rules for ConsoleApp.csproj." ToolsVersion="16.0">
  <Rules AnalyzerId="Microsoft.Analyzers.ManagedCodeAnalysis" RuleNamespace="Microsoft.Rules.Managed">
    <Rule Id="CA1001" Action="Warning" />
    <Rule Id="CA1821" Action="Warning" />
    <Rule Id="CA2213" Action="Warning" />
    <Rule Id="CA2231" Action="Warning" />
  </Rules>
</RuleSet>

Das folgende Beispiel zeigt die resultierende EditorConfig-Datei nach der Konvertierung:

# NOTE: Requires **VS2019 16.3** or later

# Rules for ConsoleApp
# Description: Code analysis rules for ConsoleApp.csproj.

# Code files
[*.{cs,vb}]

dotnet_diagnostic.CA1001.severity = warning
dotnet_diagnostic.CA1821.severity = warning
dotnet_diagnostic.CA2213.severity = warning
dotnet_diagnostic.CA2231.severity = warning

Konfigurieren von generiertem Code

Analysetools werden für Quelldateien in einem Projekt ausgeführt und melden alle Verstöße, die sie finden. Diese Verstöße sind jedoch für vom System generierte Dateien nicht hilfreich. Beispiele sind generierte Codedateien, wie z. B. vom Designer generierte Codedateien, vom Buildsystem generierte temporäre Quelldateien usw. Für diese Art von Dateien können Benutzer die Dateien nicht manuell bearbeiten und haben nichts mit der Korrektur von Verstößen zu tun.

Standardmäßig untersucht der Analysetooltreiber daher nur Dateien mit bestimmten Namen, Dateierweiterungen oder automatisch generierten Dateiheadern als generierte Codedateien. Beispielsweise wird ein Dateiname, der auf .designer.cs oder .generated.cs endet, als generierter Code betrachtet. Diese Heuristiken können sind jedoch möglicherweise nicht in der Lage, alle benutzerdefinierten generierten Codedateien im Quellcode des Benutzers zu identifizieren.

In Visual Studio 2019, Version 16.5 und neuer können Endbenutzer bestimmte Dateien und Ordner konfigurieren, die als generierter Code in einer EditorConfig-Datei behandelt werden sollen.

Um eine solche Konfiguration hinzuzufügen, führen Sie die folgenden Schritte aus:

1. Wenn Sie noch nicht über eine EditorConfig-Datei für Ihr Projekt verfügen, fügen Sie eine solche Datei hinzu.

2. Fügen Sie den generated_code = true | false-Eintrag für bestimmte Dateien und Ordner hinzu. Verwenden Sie z. B. diesen Eintrag, um alle Dateien, deren Name mit .MyGenerated.cs endet, als generierten Code zu behandeln:

   [*.MyGenerated.cs]
   generated_code = true
   

Unterdrücken von Verstößen

Sie können Regelverstöße mit verschiedenen Methoden unterdrücken. Informationen finden Sie unter Unterdrücken von Verstößen bei der Codeanalyse.

Befehlszeilensyntax

Wenn Sie das Projekt über die Befehlszeile erstellen, werden Regelverstöße in der Buildausgabe angezeigt, wenn die folgenden Bedingungen erfüllt sind:

• Die Analysetools werden mit dem .NET SDK oder als NuGet-Paket installiert, nicht als .vsix-Erweiterung.

  Für Analysetools, die mit dem .NET SDK installiert werden, müssen Sie möglicherweise die Analysetools aktivieren. Bei Codestilen können Sie auch Codestile für Builds erzwingen, indem Sie eine MSBuild-Eigenschaft festlegen.

• Mindestens eine Regel wird im Code des Projekts verletzt.

• Der Schweregradlevel einer verletzten Regel ist auf Warnung (in diesem Fall bewirken Verstöße nicht, dass der Build fehlschlägt) oder auf Fehler festgelegt (in diesem Fall verursachen Verstöße, dass der Build fehlschlägt).

Die Ausführlichkeit der Buildausgabe wirkt sich nicht darauf aus, ob Regelverstöße angezeigt werden. Selbst bei der Ausführlichkeit quiet werden Regelverstöße in der Buildausgabe angezeigt.

Wenn Sie daran gewöhnt sind, Legacyanalysen über die Befehlszeile auszuführen (mit FxCopCmd.exe oder über MSBuild mit dem RunCodeAnalysis-Flag), können Sie das stattdessen mit Codeanalysetools machen.

Um Analysetoolverstöße in der Befehlszeile anzuzeigen, wenn Sie das Projekt mithilfe von MSBuild erstellen, führen Sie einen Befehl wie den folgenden aus:

msbuild myproject.csproj /target:rebuild /verbosity:minimal

Der folgende Screenshot zeigt die Befehlszeilen-Buildausgabe vom Erstellen eines Projekts an, das einen Analysetool-Regelverstoß enthält:

Abhängige Projekte

Wenn Sie in einem .NET Core-Projekt einen Verweis auf ein Projekt hinzufügen, das über NuGet-Analysetools verfügt, fügt Visual Studio diese Analysetools automatisch dem abhängigen Projekt hinzu. Um dieses Verhalten zu deaktivieren (z. B. wenn das abhängige Projekt ein Komponententestprojekt ist), markieren Sie das NuGet-Paket als privat, indem Sie das PrivateAssets-Attribut in der .csproj oder .vbproj-Datei des referenzierten Projekts festlegen:

<PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="5.0.0" PrivateAssets="all" />

Zugehöriger Inhalt

• Verwenden von Codeanalysetools in Visual Studio: Übersicht
• Übermitteln eines Codeanalysefehlers
• Verwenden von Regelsätzen
• Unterdrücken von Codeanalyseverletzungen
• Konfigurationsoptionen für die Codeanalyse