CA1062: Argumente von öffentlichen Methoden validieren.

Eigenschaft	Wert
Regel-ID	CA1062
Titel	Argumente von öffentlichen Methoden validieren.
Kategorie	Design
Fix führt oder führt nicht zur Unterbrechung	Nicht unterbrechend
Standardmäßig in .NET 9 aktiviert	No

Ursache

Eine extern sichtbare Methode dereferenziert eines der zugehörigen Verweisargumente, ohne zu überprüfen, ob dieses Argument null (Nothing in Visual Basic) ist.

Sie können diese Regel so konfigurieren, dass bestimmte Typen und Parameter von der Analyse ausgeschlossen werden. Sie können auch Validierungsmethoden mit Null-Überprüfung angeben.

Regelbeschreibung

Alle an extern sichtbare Methoden übergebenen Verweisargumente sollten auf Null überprüft werden null. Lösen Sie ggf. eine ArgumentNullException aus, wenn das Argument null ist.

Wenn eine Methode von einer unbekannten Assembly aufgerufen werden kann, da sie als öffentlich oder geschützt deklariert ist, sollten Sie alle Parameter der Methode überprüfen. Wenn die Methode nur von bekannten Assemblys aufgerufen werden soll, markieren Sie die Methode internal und wenden Sie das InternalsVisibleToAttribute-Attribut auf die Assembly an, welche die Methode enthält.

Behandeln von Verstößen

Um einen Verstoß gegen diese Regel zu beheben, überprüfen Sie jedes Verweis Argument auf null.

Wann sollten Warnungen unterdrückt werden?

Sie können eine Warnung aus dieser Regel unterdrücken, wenn Sie sicher sind, dass der dereferenzierte Parameter von einem anderen Methodenaufruf in der Funktion überprüft wurde.

Unterdrücken einer Warnung

Um nur eine einzelne Verletzung zu unterdrücken, fügen Sie der Quelldatei Präprozessoranweisungen hinzu, um die Regel zu deaktivieren und dann wieder zu aktivieren.

#pragma warning disable CA1062
// The code that's violating the rule is on this line.
#pragma warning restore CA1062

Um die Regel für eine Datei, einen Ordner oder ein Projekt zu deaktivieren, legen Sie den Schweregrad in der Konfigurationsdatei auf none fest.

[*.{cs,vb}]
dotnet_diagnostic.CA1062.severity = none

Weitere Informationen finden Sie unter Vorgehensweise: Unterdrücken von Codeanalyse-Warnungen.

Konfigurieren des zu analysierenden Codes

Mit den folgenden Optionen können Sie konfigurieren, für welche Teile Ihrer Codebasis diese Regel ausgeführt werden soll.

• Einschließen bestimmter API-Oberflächen
• Ausschließen bestimmter Symbole
• Ausschließen bestimmter Typen und von diesen abgeleiteten Typen
• Auschließen der Erweiterungsmethode „dieses“ Parameters
• Null-Überprüfung der Validierungsmethoden

Diese Optionen können nur für diese Regel, für alle zutreffenden Regeln oder für alle zutreffenden Regeln in dieser Kategorie (Entwurf) konfiguriert werden. Weitere Informationen finden Sie unter Konfigurationsoptionen für die Codequalitätsregel.

Einschließen bestimmter API-Oberflächen

Sie können je nach Zugänglichkeit festlegen, für welche Bestandteile Ihrer Codebasis diese Regel ausgeführt wird. Sie können beispielsweise festlegen, dass die Regel nur für die nicht öffentliche API-Oberfläche ausgeführt werden soll, indem Sie einer EDITORCONFIG-Datei in Ihrem Projekt das folgende Schlüssel-Wert-Paar hinzufügen:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Hinweis

Diese Option wird nur für CA1062 in .NET 7 und höheren Versionen unterstützt.

Ausschließen bestimmter Symbole

Sie können bestimmte Symbole, z. B. Typen und Methoden, von der Analyse ausschließen. Sie können beispielsweise festlegen, dass die Regel nicht für Code innerhalb von Typen namens MyType ausgeführt werden soll, indem Sie einer EDITORCONFIG-Datei in Ihrem Projekt das folgende Schlüssel-Wert-Paar hinzufügen:

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

Zulässige Formate für Symbolnamen im Optionswert (durch | getrennt):

• Nur Symbolname (schließt alle Symbole mit dem Namen ein, unabhängig vom enthaltenden Typ oder Namespace)
• Vollqualifizierte Namen im Format der Dokumentations-ID des Symbols Jeder Symbolname erfordert ein Symbolartpräfix, z. B. M: für Methoden, T: für Typen und N: für Namespaces.
• .ctor für Konstruktoren und .cctor für statische Konstruktoren

Beispiele:

Optionswert	Zusammenfassung
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType	Trifft auf alle Symbole namens MyType zu
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1|MyType2	Trifft auf alle Symbole namens MyType1 oder MyType2 zu
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType)	Trifft speziell auf die Methode MyMethod mit der angegebenen vollqualifizierten Signatur zu
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType)	Trifft speziell auf die Methoden MyMethod1 und MyMethod2 mit den jeweiligen vollqualifizierten Signaturen zu

Ausschließen bestimmter Typen und von diesen abgeleiteten Typen

Sie können bestimmte Typen und von diesen abgeleitete Typen aus der Analyse ausschließen. Wenn Sie z. B. festlegen möchten, dass die Regel nicht für Methoden innerhalb von MyType-Typen und von diesen abgeleiteten Typen ausgeführt werden soll, fügen Sie einer EDITORCONFIG-Datei in Ihrem Projekt das folgende Schlüssel-Wert-Paar hinzu:

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

Zulässige Formate für Symbolnamen im Optionswert (durch | getrennt):

• Nur Typname (schließt alle Typen mit dem Namen ein, unabhängig vom enthaltenden Typ oder Namespace)
• Vollqualifizierte Namen im Dokumentations-ID-Format des Symbols mit einem optionalen Präfix T:

Beispiele:

Optionswert	Zusammenfassung
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType	Stimmt mit allen MyType-Typen und allen von diesen abgeleiteten Typen überein.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1|MyType2	Stimmt mit allen MyType1- oder MyType2-Typen und allen von diesen abgeleiteten Typen überein.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType	Stimmt mit einem bestimmten MyType-Typ mit einem angegebenen vollqualifizierten Namen und allen von diesem abgeleiteten Typen überein.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1|M:NS2.MyType2	Stimmt mit bestimmten MyType1- und MyType2-Typen mit den entsprechenden vollqualifizierten Namen und allen von diesen abgeleiteten Typen überein.

Auschließen der Erweiterungsmethode „dieses“ Parameters

Diese Regel analysiert und markiert standardmäßig den this-Parameter für Erweiterungsmethoden. Sie können die Analyse des this-Parameters für Erweiterungsmethoden ausschließen, indem Sie das folgende Schlüssel-Wert-Paar zu einer .editorconfig-Datei in Ihrem Projekt hinzufügen:

dotnet_code_quality.CA1062.exclude_extension_method_this_parameter = true

Null-Überprüfung der Validierungsmethoden

Diese Regel kann zu falsch positiven Ergebnissen führen, wenn Ihr Code spezielle Validierungsmethoden zur Überprüfung von Null-Überprüfung in referenzierten Bibliotheken oder Projekten aufruft. Sie können diese falsch positiven Ergebnisse vermeiden, indem Sie den Namen oder die Signatur von Validierungsmethoden mit Null-Überprüfung angeben. Die Analyse geht davon aus, dass die an diese Methoden übergebenen Argumente nach dem-Befehl nicht null sind. Fügen Sie beispielsweise das folgende Schlüssel-Wert-Paar in eine .editorconfig-Datei in Ihrem Projekt ein, um alle Methoden mit dem Namen Validate als Validierungs Methoden mit NullÜberprüfung zu markieren:

dotnet_code_quality.CA1062.null_check_validation_methods = Validate

Zulässige Formate für Symbolnamen im Optionswert (durch | getrennt):

• Nur Methodenname (schließt alle Methoden mit dem Namen ein, unabhängig vom enthaltenden Typ oder Namespace).
• Vollqualifizierte Namen im Dokumentations-ID-Format des Symbols mit einem optionalen Präfix M:.

Beispiele:

Optionswert	Zusammenfassung
dotnet_code_quality.CA1062.null_check_validation_methods = Validate	Entspricht allen Methoden mit dem Namen Validate in der Kompilierung
dotnet_code_quality.CA1062.null_check_validation_methods = Validate1|Validate2	Entspricht allen Methoden mit dem Namen Validate1 oder Validate2 in der Kompilierung
dotnet_code_quality.CA1062.null_check_validation_methods = NS.MyType.Validate(ParamType)	Entspricht der spezifische Methode Validate mit der angegebenen vollqualifizierten Signatur
dotnet_code_quality.CA1062.null_check_validation_methods = NS1.MyType1.Validate1(ParamType)|NS2.MyType2.Validate2(ParamType)	Entspricht spezifischen Methoden Validate1 und Validate2 mit der jeweiligen vollqualifizierten Signatur

Beispiel 1

Das folgende Beispiel zeigen eine Methode, der gegen die Regel verstößt, und eine Methode, welche die Regel erfüllt.

using System;

namespace DesignLibrary
{
    public class Test
    {
        // This method violates the rule.
        public void DoNotValidate(string input)
        {
            if (input.Length != 0)
            {
                Console.WriteLine(input);
            }
        }

        // This method satisfies the rule.
        public void Validate(string input)
        {
            if (input == null)
            {
                throw new ArgumentNullException(nameof(input));
            }
            if (input.Length != 0)
            {
                Console.WriteLine(input);
            }
        }
    }
}

Imports System

Namespace DesignLibrary

    Public Class Test

        ' This method violates the rule.
        Sub DoNotValidate(ByVal input As String)

            If input.Length <> 0 Then
                Console.WriteLine(input)
            End If

        End Sub

        ' This method satisfies the rule.
        Sub Validate(ByVal input As String)

            If input Is Nothing Then
                Throw New ArgumentNullException(NameOf(input))
            End If

            If input.Length <> 0 Then
                Console.WriteLine(input)
            End If

        End Sub

    End Class

End Namespace

Beispiel 2

Kopierkonstruktoren, die Felder oder Eigenschaften auffüllen, welche Verweisobjekte sind, können auch gegen Regel CA1062 verstoßen. Der Verstoß tritt auf, weil das kopierte Objekt, das an den Kopierkonstruktor übergeben wurde, möglicherweise null (Nothing in Visual Basic) ist. Um den Verstoß zu beheben, verwenden Sie eine Methode static (Shared in Visual Basic) Methode, um zu überprüfen, ob das kopierte Objekt nicht null ist.

Im folgenden Person-Klassenbeispiel kann das other-Objekt, das an den Person-Kopierkonstruktor übergeben wird, null sein.

public class Person
{
    public string Name { get; private set; }
    public int Age { get; private set; }

    public Person(string name, int age)
    {
        Name = name;
        Age = age;
    }

    // Copy constructor CA1062 fires because other is dereferenced
    // without being checked for null
    public Person(Person other)
        : this(other.Name, other.Age)
    {
    }
}

Beispiel 3

Im folgenden überarbeiteten Person Beispiel wird das other-Objekt, das an den Kopierkonstruktor übergeben wird, zuerst auf null in der PassThroughNonNull-Methode überprüft.

public class Person
{
    public string Name { get; private set; }
    public int Age { get; private set; }

    public Person(string name, int age)
    {
        Name = name;
        Age = age;
    }

    // Copy constructor
    public Person(Person other)
        : this(PassThroughNonNull(other).Name, other.Age)
    {
    }

    // Null check method
    private static Person PassThroughNonNull(Person person)
    {
        if (person == null)
            throw new ArgumentNullException(nameof(person));
        return person;
    }
}