Übersicht
Gilt für:Visual Studio
Visual Studio für Mac
Visual Studio Code
Jede Diagnose oder Regel des Roslyn-Analysetools weist einen Standardstatus bezüglich Schweregrad und Unterdrückung auf, der für Ihr Projekt überschrieben werden kann. In diesem Artikel werden das Festlegen von Schweregraden des Analysetools und das Unterdrücken von Verstößen im Analysetool behandelt.
Konfigurieren von Schweregraden
Ab Visual Studio 2019, Version 16.3, können Sie den Schweregrad von Analysetoolregeln oder Diagnosen in einer EditorConfig-Datei über das Fehlerbehebungsmenü (Glühbirne) und die Fehlerliste konfigurieren.
Die folgende Tabelle enthält die verschiedenen Schweregradoptionen:
Schweregrad (Projektmappen-Explorer) | Schweregrad (EditorConfig-Datei) | Verhalten zur Buildzeit | Editor-Verhalten |
---|---|---|---|
Fehler | error |
Verstöße werden als Fehler in der 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 als Warnungen in der 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. |
Info | suggestion |
Verstöße werden als Meldungen in der Fehlerliste angezeigt, in der Befehlszeilen-Buildausgabe hingegen gar nicht. | Der betreffende Code wird mit einer grauen Wellenlinie unterstrichen und in der Scrollleiste durch ein kleines graues Feld markiert. |
Ausgeblendet | silent |
Für den Benutzer nicht sichtbar. | Für den Benutzer nicht sichtbar. Die Diagnose wird jedoch der IDE-Diagnose-Engine 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, ziehen Sie in der Eigenschaftenfenster zu Rate. | Entspricht dem Standardschweregrad der Regel. |
Vom Analysetool gefundene Regelverstöße werden im Code-Editor (als Wellenlinie unter dem fehlerhaften Code) und im Fenster „Fehlerliste“ angezeigt.
Die in der Fehlerliste gemeldeten vom Analysetool gefundenen Verstöße stimmen mit der Einstellung für den Schweregrad der Regel überein. Außerdem werden vom Analysetool gemeldete Verstöße auch im Code-Editor als Wellenlinie unter dem fehlerhaften Code angezeigt. In der folgenden Abbildung werden drei Verstöße angezeigt: ein Fehler (rote Wellenlinie), eine Warnung (grüne Wellenlinie) und ein Vorschlag (drei graue Punkte):
Der folgende Screenshot zeigt dieselben drei Verstöße, die in der Fehlerliste angezeigt werden:
Viele Analysetoolregeln oder -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 diesen Codefixen finden Sie unter Häufige schnelle Aktionen.
Schweregrad „Ausgeblendet“ im Vergleich zum Schweregrad „Keiner“"
Hidden
-Schweregradregeln, die standardmäßig aktiviert sind, unterscheiden sich in bestimmten Aspekten von deaktivierten Regeln bzw. None
-Schweregradregeln.
- Wenn eine Codekorrektur für eine
Hidden
-Schweregradregel registriert ist, bietet Visual Studio die Korrektur als Refactoring-Aktion im Fehlerbehebungsmenü (Glühbirne) an, selbst wenn die ausgeblendete Diagnose für den Benutzer nicht sichtbar ist. Die Korrektur wird nicht angeboten, wenn die Schweregradregel alsNone
deaktiviert ist. Hidden
-Schweregradregeln können mit Einträgen massenhaft konfiguriert werden, die den Regelschweregrad mehrerer Analysetoolregeln gleichzeitig in einer EditorConfig-Datei festlegen.None
-Schweregradregeln können nicht auf diese Weise konfiguriert werden. Stattdessen müssen sie über Einträge konfiguriert werden, die den Regelschweregrad in einer EditorConfig-Datei für jede Regel-ID festlegen.
Festlegen des Regelschweregrads in einer EditorConfig-Datei
(Visual Studio 2019, Version 16.3 und höher)
Sie können den Schweregrad für Compilerwarnungen oder Analysetoolregeln in einer EditorConfig-Datei mit der folgenden Syntax festlegen:
dotnet_diagnostic.<rule ID>.severity = <severity>
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 manuell in einer EditorConfig-Datei oder automatisch über die Glühbirne konfigurieren, die neben einem Verstoß angezeigt wird.
Gleichzeitiges Festlegen des Regelschweregrads für mehrere Analysetoolregeln in einer EditorConfig-Datei
(Visual Studio 2019, Version 16.5 und höher)
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>
Hinweis
Einträge zum gleichzeitigen Konfigurieren mehrerer Analysetoolregeln 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, 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 vorherigen Beispiel gelten alle drei Einträge für 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 „Fehler“ auf. Die verbleibenden Regeln mit der Kategorie „Performance“ (Leistung) weisen den Schweregrad „Warnung“ auf, und die Analysetoolregeln, die nicht die Kategorie „Performance“ aufweisen, haben den Schweregrad „Vorschlag“.
Manuelles Konfigurieren des Regelschweregrads in einer EditorConfig-Datei
Wenn Sie noch nicht über eine EditorConfig-Datei für Ihr Projekt verfügen, fügen Sie eine solche Datei hinzu.
Fügen Sie unter der entsprechenden Dateierweiterung einen Eintrag für jede Regel hinzu, die Sie konfigurieren möchten. Um den Schweregrad für CA1822 beispielsweise auf
error
für C#-Dateien festzulegen, sieht der Eintrag wie folgt aus:[*.cs] dotnet_diagnostic.CA1822.severity = error
Hinweis
Bei Analysetools im IDE-Codestil kann die Konfiguration ebenfalls in einer EditorConfig-Datei erfolgen, indem eine andere Syntax verwendet wird, z. B. 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.
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.
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).
Zeigen Sie im Fehlerbehebungsmenü (Glühbirne) mit dem Mauszeiger auf einen Schweregrad, um eine Vorschau der Änderung anzuzeigen, und wählen Sie dann eine Option zum Konfigurieren des Schweregrads aus:
- Konfigurieren des <Regel-ID>-Schweregrads: Festlegen des Schweregrads für eine bestimmte Regel.
- Konfigurieren des Schweregrads für alle <Stil>analysetools: Festlegen des Schweregrads für alle Regeln in der spezifischen Regelkategorie.
- Konfigurieren des Schweregrads für alle Analysetools: Festlegen des Schweregrads für alle Kategorien von Analysetoolregeln.
Wählen Sie im folgenden Beispiel Probleme konfigurieren oder unterdrücken>Konfigurieren<Regel-ID>-Schweregradaus.
Wählen Sie dort eine der Optionen für den Schweregrad aus.
Visual Studio fügt der EditorConfig-Datei einen Eintrag hinzu, um die Regel auf der angeforderten Ebene zu konfigurieren, wie im Vorschaufeld angezeigt.
Tipp
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“.
Wenn ein Verstoß auftritt, klicken Sie mit der rechten Maustaste auf den Diagnoseeintrag in der Fehlerliste.
Wählen Sie im Kontextmenü Schweregrad festlegen aus.
Wählen Sie dort eine der Optionen für den Schweregrad aus.
Visual Studio fügt der EditorConfig-Datei einen Eintrag hinzu, um die Regel auf der angeforderten Ebene zu konfigurieren.
Tipp
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
Sie können einen Großteil der Anpassung der Analysetooldiagnosen im Projektmappen-Explorer ausführen. Wenn Sie Analysetools als NuGet-Paket installieren, wird ein Knoten Analysetools unter dem Knoten Verweise oder Abhängigkeiten im Projektmappen-Explorer angezeigt. Wenn Sie Analysetools erweitern und dann eine der Analysetoolassemblys erweitern, werden alle Diagnosen in der Assembly angezeigt.
Im Fenster Eigenschaften können Sie die Eigenschaften einer Diagnose einschließlich der Beschreibung und des Standardschweregrads anzeigen. Um Eigenschaften anzuzeigen, klicken Sie mit der rechten Maustaste auf die Regel, und wählen Sie Eigenschaftenaus, oder wählen Sie die Regel aus, und drücken Sie dann ALT+EINGABETASTE.
Um die Onlinedokumentation für eine Diagnose anzuzeigen, klicken Sie mit der rechten Maustaste auf die Diagnose, und wählen Sie Hilfe anzeigen aus.
Die Symbole neben den einzelnen Diagnosen im Projektmappen-Explorer entsprechen den Symbolen, die im Regelsatz angezeigt werden, wenn Sie ihn im Editor öffnen:
- Das „x“ in einem Kreis zeigt den Schweregrad „Fehler“ an.
- Das „!“ in einem Dreieck zeigt den Schweregrad „Warnung“ an.
- Das „i“ in einem Kreis zeigt den Schweregrad „Information“ an.
- Das „i“ in einem Kreis vor einem hellen Hintergrund zeigt den Schweregrad „Ausgeblendet“ an.
- Der nach unten zeigende Pfeil in einem Kreis zeigt an, dass die Diagnose unterdrückt ist.
Konvertieren einer vorhandenen Regelsatzdatei in eine EditorConfig-Datei
Ab Visual Studio 2019, Version 16.5, wurden Regelsatzdateien zugunsten der EditorConfig-Datei für die Analysetoolkonfiguration für verwalteten Code eingestellt. Die meisten Visual Studio-Tools für die Konfiguration des Schweregrads von Analysetoolregeln wurden so aktualisiert, dass sie mit EditorConfig-Dateien anstelle von Regelsatzdateien arbeiten. Mit EditorConfig-Dateien können Sie sowohl Schweregrade von Analysetoolregeln als auch Analysetooloptionen konfigurieren, einschließlich Visual Studio-IDE-Codestiloptionen. Es wird empfohlen, Ihre vorhandene Regelsatzdatei in eine EditorConfig-Datei zu konvertieren. Speichern Sie außerdem die EditorConfig-Datei im Stamm Ihres Repositorys oder im Projektmappenordner. Indem Sie den Stamm Ihres Repositorys oder den Projektmappenordner verwenden, stellen Sie sicher, dass die Schweregradeinstellungen aus dieser Datei automatisch für das gesamte Repository bzw. die gesamte Projektmappe gelten.
Es gibt mehrere Möglichkeiten, eine vorhandene Regelsatzdatei in eine EditorConfig-Datei zu konvertieren:
Im Regelsatz-Editor in Visual Studio (erfordert Visual Studio 2019, Version 16.5 oder höher). Wenn Ihr Projekt bereits eine bestimmte Regelsatzdatei als
CodeAnalysisRuleSet
verwendet, können Sie sie im Regelsatz-Editor in Visual Studio in eine entsprechende EditorConfig-Datei konvertieren.Doppelklicken Sie im Projektmappen-Explorer auf die Regelsatzdatei.
Die Regelsatzdatei sollte im Regelsatz-Editor geöffnet werden. Am oberen Rand des Regelsatz-Editors sollte eine anklickbare Infoleiste angezeigt werden.
Wählen Sie den Infoleistenlink aus.
Die Aktion sollte ein Dialogfeld Speichern unter öffnen, in dem Sie das Verzeichnis auswählen können, in dem die EditorConfig-Datei generiert werden soll.
Wählen Sie die Schaltfläche Speichern aus, um die EditorConfig-Datei zu generieren.
Die generierte EditorConfig-Datei sollte im Editor geöffnet werden. Darüber hinaus wird die MSBuild-Eigenschaft
CodeAnalysisRuleSet
in der Projektdatei so aktualisiert, dass sie nicht mehr auf die ursprüngliche Regelsatzdatei verweist.
Über die Befehlszeile:
Installieren Sie das NuGet-Paket Microsoft.CodeAnalysis.RulesetToEditorconfigConverter.
Führen Sie
RulesetToEditorconfigConverter.exe
aus dem installierten Paket mit Pfaden zur Regelsatzdatei und zur EditorConfig-Datei als Befehlszeilenargumenten aus.
Usage: RulesetToEditorconfigConverter.exe <%ruleset_file%> [<%path_to_editorconfig%>]
Im Folgenden finden Sie eine zu konvertierende Regelsatzbeispieldatei:
<?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>
Im Folgenden sehen Sie die konvertierte EditorConfig-Datei:
# 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
Festlegen des Regelschweregrads im Projektmappen-Explorer
Erweitern Sie im Projektmappen-Explorer Verweise>Analysetools (oder Abhängigkeiten>Analysetools für .NET Core-Projekte).
Erweitern Sie die Assembly, die die Regel enthält, für die Sie den Schweregrad festlegen möchten.
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.
Tipp
Wenn Sie noch keine EditorConfig-Datei oder Regelsatzdatei im Projekt haben, erstellt Visual Studio eine neue EditorConfig-Datei für Sie.
Festlegen des Regelschweregrads in der Regelsatzdatei
Öffnen Sie die aktive Regelsatzdatei auf eine der folgenden Arten:
Doppelklicken Sie im Projektmappen-Explorer auf die Datei, klicken Sie mit der rechten Maustaste auf den Knoten Verweise>Analysetools, und wählen Sie Aktiven Regelsatz öffnen aus.
Wählen Sie auf der Eigenschaftenseite der Codeanalyse für das Projekt Öffnen aus.
Wenn Sie den Regelsatz zum ersten Mal bearbeiten, erstellt Visual Studio eine Kopie der Standardregelsatzdatei, nennt diese <Projektname>.ruleset, und fügt sie Ihrem Projekt hinzu. Dieser benutzerdefinierte Regelsatz wird auch zum aktiven Regelsatz für Ihr Projekt.
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 in der Benutzeroberfläche des Regelsatz-Editors von Visual Studio konfigurieren.
Navigieren Sie zu der Regel, indem Sie die zugehörige Assembly erweitern.
Wählen Sie in der Spalte Aktion den Wert aus, um eine Dropdownliste zu öffnen, und wählen Sie den gewünschten Schweregrad aus der Liste aus.
Konfigurieren von generiertem Code
Analysetools werden für alle Quelldateien in einem Projekt ausgeführt und melden dort vorgefundene Verstöße. Die Verstöße sind jedoch bei generierten Codedateien nicht hilfreich, z. B. vom Designer generierte Codedateien, vom Buildsystem generierte temporäre Quelldateien usw. Benutzer können die Dateien nicht manuell bearbeiten und haben nichts mit der Korrektur von Verstößen in von Tools generierten Dateien zu tun.
Standardmäßig behandelt der Analysetooltreiber, der Analysetools ausführt, die 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.
Ab Visual Studio 2019, Version 16.5, können Endbenutzer bestimmte Dateien und/oder Ordner konfigurieren, die als generierter Code in einer EditorConfig-Datei behandelt werden sollen. Führen Sie die folgenden Schritte aus, um eine solche Konfiguration hinzuzufügen:
Wenn Sie noch nicht über eine EditorConfig-Datei für Ihr Projekt verfügen, fügen Sie eine solche Datei hinzu.
Fügen Sie den
generated_code = true | false
-Eintrag für bestimmte Dateien und/oder Ordner hinzu. Um beispielsweise alle Dateien, deren Name auf.MyGenerated.cs
endet, als generierten Code zu behandeln, sähe der Eintrag wie folgt aus:[*.MyGenerated.cs] generated_code = true
Unterdrücken von Verstößen
Sie können Regelverstöße mit verschiedenen Methoden unterdrücken. Weitere 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 den Build erzwingen, indem Sie eine MSBuild-Eigenschaft festlegen.
Mindestens eine Regel wird im Code des Projekts verletzt.
Der Schweregrad 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.
Tipp
Wenn Sie daran gewöhnt sind, Legacyanalysen über die Befehlszeile auszuführen (mit FxCopCmd.exe oder über MSBuild mit dem RunCodeAnalysis-Flag), gehen Sie wie folgt vor, um zu diesem Zweck die Codeanalysetools zu verwenden.
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 Regelverstoß des Analysetools 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, werden diese Analysetools dem abhängigen Projekt ebenfalls automatisch hinzugefügt. Um dieses Verhalten zu deaktivieren (z. B. wenn das abhängige Projekt ein Komponententestprojekt ist), markieren Sie das NuGet-Paket in der CSPROJ- oder VBPROJ-Datei des referenzierten Projekts als privat, indem Sie das Attribut PrivateAssets festlegen:
<PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="5.0.0" PrivateAssets="all" />