Unterdrücken von Codeanalyseverletzungen

Wenn Sie beim Erstellen von Code mit Ihrem Team zusammenarbeiten, ist es häufig hilfreich, darauf hinzuweisen, dass eine Warnung nicht anwendbar ist. Das Unterdrücken von Verstößen bei der Codeanalyse zeigt Teammitgliedern, dass der Code überprüft wurde, und dass die Warnung unterdrückt werden kann. In den folgenden Abschnitten werden die verschiedenen Möglichkeiten beschrieben, wie Verstöße bei der Codeanalyse mithilfe der Visual Studio-IDE unterdrückt werden können.

Unterdrücken von Verstößen mithilfe der „EditorConfig“-Datei

Fügen Sie in der EditorConfig-Datei für Ihre Lösung oder Ihr Projekt einen Eintrag für jede Regel hinzu, die Sie konfigurieren möchten, und legen Sie den Schweregrad auf none fest. Beispiel: dotnet_diagnostic.CA1822.severity = none. Weitere Informationen finden Sie unter Manuelles festlegen des Regelschweregrads in einer EditorConfig-Datei. Informationen zum Hinzufügen einer „EditorConfig“-Datei finden Sie unter Hinzufügen einer „EditorConfig“-Datei zu einem Projekt.

Unterdrücken von Verstößen in der Quelle

Sie können Verstöße im Quellcode mithilfe einer Präprozessordirektive unterdrücken, die Verstöße für eine bestimmte Codezeile unterdrückt:

• C#: #pragma warning
• Visual Basic: Warnung deaktivieren

Sie können auch das SuppressMessageAttribute-Attribut verwenden, um eine Warnung in Ihrem C#- und Visual Basic-Code zu unterdrücken.

Unterdrücken von Verstößen mithilfe des Code-Editors

Führen Sie die folgenden Schritte aus, um Verstöße mithilfe des Code-Editors zu unterdrücken:

1. Platzieren Sie den Cursor in der Codezeile mit dem Verstoß, und drücken Sie Ctrl+Punkt (.) oder Alt+Enter, um das Menü Schnelle Aktionen zu öffnen.

2. Wählen Sie Unterdrücken oder Konfigurieren von Problemen>Unterdrücken der <Regelnummer> aus, und wählen Sie dann entweder in Quelle oder in Quelle (Attribut) aus.

   • Wenn Sie In Quelle auswählen, wird eine Vorschau der Präprozessoranweisung angezeigt, die Ihrem Code hinzugefügt wurde.

     

   • Wenn Sie In Quelle (Attribut) auswählen, wird eine Vorschau des SuppressMessageAttribute-Attributs angezeigt, das Ihrem Code hinzugefügt wurde.

     

Unterdrücken von Verstößen mithilfe der Fehlerliste

Führen Sie die folgenden Schritte aus, um Verstöße mithilfe des Fensters Fehlerliste zu unterdrücken:

1. Wählen Sie im Fenster Fehlerliste die Regeln aus, die Sie unterdrücken möchten.

2. Klicken Sie mit der rechten Maustaste und wählen Sie dann Unterdrücken>In Quelle aus.

   Das Dialogfeld Vorschau der Änderungen öffnet sich und eine Vorschau der C#-Anweisung #pragma warning oder der Anweisung #Disable warning von Visual Basic angezeigt, die dem Quellcode hinzugefügt wurde.

   

3. Wählen Sie Anwenden aus, um die Änderungen an Ihrm Feld zu speichern.

Fehlerlisten-Build-Diagnose ausschließen

Wenn die Menüoption Unterdrücken im Fenster Fehlerliste nicht angezeigt wird, stammt der Verstoß wahrscheinlich vom Build und nicht von der Liveanalyse. Im Fenster Fehlerliste werden Diagnosen (oder Regelverstöße) aus der Livecodeanalyse und Builds angezeigt. Weil Builddiagnose veraltet sein kann, wenn Sie den Code beispielsweise zum Beheben des Verstoßes bearbeitet, den Build aber nicht neu erstellt haben, können Sie diese Diagnosen nicht immer aus der Fehlerliste unterdrücken.

Diagnosedaten aus der Liveanalyse oder aus IntelliSense sind immer auf dem neuesten Stand mit aktuellen Quellen und können aus der Fehlerliste immer unterdrückt werden. Führen Sie die folgenden Schritte aus, um Build-Diagnose aus Ihrer Auswahl auszuschließen:

1. Ändern Sie in der Dropdownliste Fehlerlisten-Quellenfilter die Auswahl von Build + IntelliSense in Nur IntelliSense.

   

2. Wählen Sie die Diagnosen aus, die Sie unterdrücken möchten, und fahren Sie wie zuvor beschrieben fort.

Unterdrücken von Verstößen mithilfe einer globalen Unterdrückungsdatei

Die globale Unterdrückungsdatei verwendet das SuppressMessageAttribute-Attribut, um Code-Verstöße zu unterdrücken.

Verwenden einer globalen Unterdrückungsdatei aus dem Code-Editor

Führen Sie die folgenden Schritte aus, um Verstöße mit einer globalen Unterdrückungsdatei mithilfe des Code-Editors zu unterdrücken:

1. Platzieren Sie im Code-Editor den Cursor in die Codezeile mit dem Verstoß und drücken Sie Ctrl+Period (.) oder Alt+Enter, um das Menü Schnelle Aktionen zu öffnen.

2. Wählen Sie Unterdrücken <Regelnummer> und dann In Unterdrückungsdatei aus.

   Visual Studio erstellt eine Registerkarte im Code-Editor, die die neue globale Unterdrückungsdatei enthält.

Verwenden einer globalen Unterdrückungsdatei aus der Fehlerliste

Führen Sie die folgenden Schritte aus, um Verstöße mit einer globalen Unterdrückungsdatei mithilfe des Fensters Fehlerliste zu unterdrücken:

1. Wählen Sie im Fenster Fehlerliste die Regeln aus, die Sie unterdrücken möchten.

2. Klicken Sie mit der rechten Maustaste und wählen Sie dann UnterdrückenIn Unterdrückungsdatei> aus.

   Das Dialogfeld Vorschau der Änderungen wird geöffnet, und es wird eine Vorschau des SuppressMessageAttribute-Attributs angezeigt, das der globalen Unterdrückungsdatei hinzugefügt wurde.

   

3. Wählen Sie Übernehmen aus, um die globale Unterdrückungsdatei zu speichern.

Alle aktuellen Verstöße unterdrücken

Das Unterdrücken aller aktuellen Verstöße wird manchmal als Baselining bezeichnet. Führen Sie die folgenden Schritte aus, um alle aktuellen Verstöße in einer Lösung oder einem Projekt zu unterdrücken:

1. Wählen Sie in der Visual Studio-Menüleiste Analysieren>Build und aktive Probleme unterdrücken aus.

2. Wählen Sie Zur Lösung aus, um Verstöße für die gesamte Lösung zu unterdrücken, oder wählen Sie Für <Projektname> aus, um Verstöße nur für Ihr Projekt zu unterdrücken.

Unterdrücken von Verstößen mithilfe von Projekteinstellungen

Führen Sie die folgenden Schritte aus, um Verstöße mithilfe von Projektmappen-Explorer Projekteinstellungen zu unterdrücken:

1. Wählen Sie aus dem Projektmappen-Explorer Ihr Projekt aus.

2. Klicken Sie mit der rechten Maustaste, und wählen Sie dann Eigenschaften aus (oder drücken Sie ALT+EINGABETASTE).

3. Wählen Sie im Fenster Eigenschaften Codeanalyse im linken Bereich die Option Ergebnisse unterdrücken aus dem generierten Code aus.

Unterdrückung in der Quelle und das „SuppressMessageAttribute“-Attribut

Die Unterdrückung in der Quelle (In-Source Suppression, ISS) verwendet das SuppressMessageAttribute-Attribut, um eine Warnung zu unterdrücken. Sie können das SuppressMessageAttribute-Attribut der Quelldatei in der Nähe des Codesegments hinzufügen, das die Warnung generiert hat.

Sie können das Attribut entweder manuell im Code-Editor eingeben oder das Attribut automatisch wie folgt hinzufügen:

1. Platzieren Sie im Code-Editor den Cursor in die Codezeile mit dem Verstoß und drücken Sie Ctrl+Period (.) oder Alt+Enter, um das Menü Schnelle Aktionen zu öffnen.

2. Wählen Sie Probleme unterdrücken oder konfigurieren>Unterdrücken <Regelnummer> aus dem Menü Schnelle Aktionen aus.

3. Führen Sie einen der folgenden Schritte aus:

   • Wählen Sie in Source (Attribut) aus.

     Visual Studio fügt Ihrem Code ein SuppressMessageAttribute-Attribut hinzu.

   • Wählen Sie in Unterdrückungsdatei aus.

     Visual Studio erstellt eine Registerkarte im Code-Editor, die eine neue globale Unterdrückungsdatei mit SuppressMessageAttribute-Attributen enthält.

Das SuppressMessageAttribute-Attribut ist ein bedingtes Attribut, das in den Metadaten Ihrer verwalteten Codeassembly enthalten ist. Dieses Attribut ist nur enthalten, wenn das CODE_ANALYSIS-Kompilierungssymbol zur Kompilierzeit definiert wird.

Verwenden Sie nur in C++ und CLI-Code die Makros CA_SUPPRESS_MESSAGE oder CA_GLOBAL_SUPPRESS_MESSAGE in der Headerdatei, um das Attribut hinzuzufügen.

Wenn Sie ein Projekt zur neusten Version von Visual Studio migrieren, werden Sie möglicherweise plötzlich mit einer großen Anzahl von Codeanalysewarnungen sehen. Wenn Sie nicht bereit sind, die Warnungen zu beheben, können Sie alle unterdrücken, indem Sie Analysieren>Erstellen und aktive Probleme unterdrücken auswählen.

SuppressMessageAttribute-Attributformat

Das SuppressMessageAttribute-Attribut hat folgendes Format:

[Scope:SuppressMessage("Rule Category", "Rule Id", Justification = "Justification", MessageId = "MessageId", Scope = "Scope", Target = "Target")]

<Scope:SuppressMessage("Rule Category", "Rule Id", Justification = "Justification", MessageId = "MessageId", Scope = "Scope", Target = "Target")>

Die Eigenschaften des Attributs umfassen:

• Category: Die Kategorie der Regel. Weitere Informationen zu Codeanalyseregel-Kategorien finden Sie unter Code-Qualitätsregeln.

• CheckId: Der Bezeichner der Regel. Die Unterstützung umfasst sowohl einen Kurznamen als auch einen langen Namen für den Regelbezeichner. Der Kurzname lautet CAXXXX, der lange Name CAXXXX:FriendlyTypeName.

• Justification: Der Text, der verwendet wird, um den Grund für die Unterdrückung der Meldung zu dokumentieren.

• MessageId: Der eindeutige Bezeichner des Problems für jede Meldung.

• Scope: Das Ziel, für das die Warnung unterdrückt wird. Wenn das Ziel nicht angegeben wird, legt das System es auf das Ziel des Attributs fest. Folgende Bereiche werden u. a. unterstützt:

  • module: Dieser Bereich unterdrückt Warnungen für eine Assembly. Es handelt sich um eine globale Unterdrückung, die für das gesamte Projekt gilt.

  • resource: (Nur Legacy FxCop) Dieser Bereich unterdrückt Warnungen in Diagnoseinformationen, die in Ressourcendateien geschrieben werden, die Teil des Moduls (der Assembly) sind. Dieser Bereich wird in C#/VB-Compilern für die Roslyn-Analysetooldiagnose, die nur Quelldateien analysieren, weder gelesen noch beachtet.

  • type: Dieser Bereich unterdrückt Warnungen für einen Typ.

  • member: Dieser Bereich unterdrückt Warnungen für einen Member.

  • namespace: Dieser Bereich unterdrückt Warnungen für den Namespace selbst. Warnungen für Typen innerhalb des Namespace werden nicht unterdrückt.

  • namespaceanddescendants: (erfordert Compilerversion 3.x oder höher und Visual Studio 2019 oder neuer) Dieser Bereich unterdrückt Warnungen in einem Namespace und allen zugehörigen nachfolgenden Symbolen. Legacy-Analyse ignoriert den namespaceanddescendants-Wert.

• Target: Ein Bezeichner, der das Ziel angibt, für das die Warnung unterdrückt wird. Er muss einen vollqualifizierten Komponentennamen enthalten.

Wenn Warnungen in Visual Studio angezeigt werden, können Sie Beispiele von SuppressMessageAttribute anzeigen, indem Sie der globalen Unterdrückungsdatei eine Unterdrückung hinzufügen. Das Unterdrückungsattribut und seine erforderlichen Eigenschaften werden in einem Vorschaufenster angezeigt.

SuppressMessageAttribute-Nutzung

Codeanalysewarnungen werden auf der Ebene unterdrückt, auf die das SuppressMessageAttribute-Attribut angewendet wird. Beispielsweise kann das Attribut auf Assembly-, Modul-, Typ-, Member- oder Parameterebene angewendet werden. Der Zweck der Anwendung dieses Attributs besteht darin, die Unterdrückungsinformationen eng mit dem Code zu verknüpfen, in dem der Verstoß auftritt.

Die allgemeine Form der Unterdrückung umfasst die Regelkategorie und einen Regelbezeichner, der eine optionale, für Menschen lesbare Darstellung des Regelnamens enthält. Zum Beispiel:

[SuppressMessage("Microsoft.Design", "CA1039:ListsAreStrongTyped")]

Wenn es strikte Leistungsgründe für die Minimierung von Metadaten der Unterdrückung in der Quelle gibt, kann der Regelname weggelassen werden. Die Regelkategorie und ihre Regel-ID bilden zusammen einen ausreichend eindeutigen Regelbezeichner. Zum Beispiel:

[SuppressMessage("Microsoft.Design", "CA1039")]

Aus Gründen der Verwaltbarkeit wird das Weglassen des Regelnamens nicht empfohlen.

Unterdrücken selektiver Verstöße innerhalb eines Methodenkörpers

Unterdrückungsattribute können auf eine Methode angewendet, können aber nicht in einen Methodenkörper eingebettet werden. Alle Verstöße gegen eine bestimmte Regel werden unterdrückt, wenn Sie der Methode das SuppressMessageAttribute-Attribut hinzufügen.

In einigen Fällen können Sie eine bestimmte Instanz des Verstoßes unterdrücken. Erwägen Sie das Beispiel, in dem zukünftiger Code nicht automatisch von der Codeanalyseregel ausgenommen wird. Mit bestimmten Codeanalyseregeln können Sie eine bestimmte Instanz des Verstoßes unterdrücken, indem Sie die MessageId-Eigenschaft des SuppressMessageAttribute-Attributs verwenden. Im Allgemeinen berücksichtigen Legacyregeln für Verstöße gegen ein bestimmtes Symbol (eine lokale Variable oder einen lokalen Parameter) die MessageId-Eigenschaft. CA1500:VariableNamesShouldNotMatchFieldNames ist ein Beispiel für eine solche Regel. Legacyregeln für Verstöße gegen ausführbaren Code (kein Symbol) berücksichtigen die MessageId-Eigenschaft jedoch nicht. Auch berücksichtigen .NET Compiler Platform-Analysetools („Roslyn“) die MessageId-Eigenschaft nicht.

Um einen bestimmten Symbolverstoß gegen eine Regel zu unterdrücken, geben Sie den Symbolnamen für die MessageId-Eigenschaft des SuppressMessageAttribute-Attributs an. Das folgende Beispiel zeigt Code mit zwei Verstößen gegen CA1500:VariableNamesShouldNotMatchFieldNames: einen für die name-Variable und einen weiteren Verstoß für die age-Variable. Nur der Verstoß für das age-Symbol wird unterdrückt.

public class Animal
{
    int age;
    string name;

    [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Maintainability", "CA1500:VariableNamesShouldNotMatchFieldNames", MessageId = "age")]
    private void PrintInfo()
    {
        int age = 5;
        string name = "Charlie";

        Console.WriteLine($"Age {age}, Name {name}");
    }
}

Public Class Animal
    Dim age As Integer
    Dim name As String

    <CodeAnalysis.SuppressMessage("Microsoft.Maintainability", "CA1500:VariableNamesShouldNotMatchFieldNames", MessageId:="age")>
    Sub PrintInfo()
        Dim age As Integer = 5
        Dim name As String = "Charlie"

        Console.WriteLine("Age {0}, Name {1}", age, name)
    End Sub

End Class

Unterdrückungen auf globaler Ebene

Das Analysetool für verwalteten Code untersucht die SuppressMessageAttribute-Attribute, die auf Assembly-, Modul-, Typ-, Member- oder Parameterebene angewendet werden. Es übermittelt außerdem Verstöße gegen Ressourcen und Namespaces. Diese Verstöße müssen auf globaler Ebene angewendet werden und beziehen sich auf einen Bereich und ein Ziel. Die folgende Meldung unterdrückt beispielsweise einen Namespaceverstoß:

[module: SuppressMessage("Microsoft.Design", "CA1020:AvoidNamespacesWithFewTypes", Scope = "namespace", Target = "MyNamespace")]

Für Unterdrückungen auf globaler Ebene:

• Wenn Sie eine Warnung mit einem namespace-Bereich unterdrücken, wird die Warnung für den Namespace selbst unterdrückt. Warnungen für Typen innerhalb des Namespace werden nicht unterdrückt.

• Target enthält immer den vollqualifizierten Elementnamen.

• Jede Unterdrückung kann durch Angabe eines expliziten Bereichs ausgedrückt werden. Diese Unterdrückungen müssen auf globaler Ebene stattfinden. Sie können keine Unterdrückung auf Memberebene angeben, indem Sie einen Typ ändern.

• Unterdrückungen auf globaler Ebene sind die einzige Möglichkeit, um Meldungen zu unterdrücken, die sich auf vom Compiler generierten Code beziehen, der sich nicht der explizit bereitgestellten Benutzerquelle zuordnen lässt. Der folgende Code unterdrückt z. B. einen Verstoß gegen einen vom Compiler ausgegebenen Konstruktor:

  [module: SuppressMessage("Microsoft.Design", "CA1055:AbstractTypesDoNotHavePublicConstructors", Scope="member", Target="Microsoft.Tools.FxCop.Type..ctor()")]

Globale Unterdrückungsdatei

In der globalen Unterdrückungsdatei werden Unterdrückungen verwaltet, bei denen es sich entweder um Unterdrückungen auf globaler Ebene handelt, oder um Unterdrückungen, die kein Ziel angeben. Beispielsweise werden Unterdrückungen für Verstöße auf Assemblyebene in dieser Datei gespeichert. Darüber hinaus werden einige ASP.NET-Unterdrückungen in dieser Datei gespeichert, weil Einstellungen auf Projektebene für Code hinter einem Formular nicht verfügbar sind. Visual Studio erstellt und fügt eine globale Unterdrückungsdatei ihrem Projekt hinzu, wenn Sie zum ersten Mal im Fenster Fehlerliste die Option In Projektunterdrückungsdatei des Befehls Unterdrücken auswählen.

Unterdrückungsbereich „Modul“

Sie können Codequalitätsverstöße für die gesamte Assembly unterdrücken, indem Sie den Bereich module verwenden.

Das folgende Attribut in Ihrer GlobalSuppressions-Projektdatei unterdrückt beispielsweise den „ConfigureAwait“-Verstoß für ein ASP.NET Core-Projekt:

[assembly: System.Diagnostics.CodeAnalysis.SuppressMessage("Reliability", "CA2007:Consider calling ConfigureAwait on the awaited task", Justification = "ASP.NET Core doesn't use thread context to store request context.", Scope = "module")]

Generierter Code

Verwaltete Codecompiler und generierter Code von externen Tools, um die schnelle Codeentwicklung zu fördern. Der vom Compiler generierte Code, der in Quelldateien angezeigt wird, wird mit dem GeneratedCodeAttribute-Attribut gekennzeichnet.

Bei der Quellcodeanalyse können Sie Meldungen in generiertem Code in einer .editorconfig-Datei unterdrücken. Weitere Informationen finden Sie unter Ausschließen von generiertem Code.

Bei der Legacycodeanalyse können Sie auswählen, ob Codeanalysewarnungen und -fehler für generierten Code unterdrückt werden sollen. Informationen, wie Sie solche Warnungen und Fehler unterdrücken, finden Sie unter Unterdrücken von Code Analysis-Warnungen für generierten Code.

Zugehöriger Inhalt

• Scope
• System.Diagnostics.CodeAnalysis
• Anpassen von Roslyn-Analyseregeln