CA1062: Ověřte argumenty veřejných metod

  • Článek
Vlastnost Hodnota
ID pravidla CA1062
Název Ověřte argumenty veřejných metod
Kategorie Návrh
Oprava způsobující chybu nebo chybu způsobující chybu Nenarušující
Povoleno ve výchozím nastavení v .NET 8 No

Příčina

Externě viditelná metoda dereference jednoho z jejích referenčních argumentů bez ověření, zda je null tento argument (Nothing v jazyce Visual Basic).

Toto pravidlo můžete nakonfigurovat tak, aby z analýzy vyloučilo určité typy a parametry. Můžete také označit metody ověřování kontroly null.

Popis pravidla

Všechny referenční argumenty, které jsou předány externě viditelné metody by měly být kontrolovány proti null. V případě potřeby vyvolejte ArgumentNullException argument .null

Pokud lze volat metodu z neznámého sestavení, protože je deklarována jako veřejná nebo chráněná, měli byste ověřit všechny parametry metody. Pokud je metoda navržena tak, aby byla volána pouze známými sestaveními, označte metodu internal a použijte InternalsVisibleToAttribute atribut na sestavení, které obsahuje metodu.

Jak opravit porušení

Chcete-li opravit porušení tohoto pravidla, ověřte každý referenční argument proti null.

Kdy potlačit upozornění

Upozornění z tohoto pravidla můžete potlačit, pokud jste si jisti, že byl parametr dereferenced ověřen jiným voláním metody ve funkci.

Potlačení upozornění

Pokud chcete pouze potlačit jedno porušení, přidejte do zdrojového souboru direktivy preprocesoru, abyste pravidlo zakázali a znovu povolili.

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

Pokud chcete pravidlo pro soubor, složku nebo projekt zakázat, nastavte jeho závažnost v none konfiguračním souboru.

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

Další informace naleznete v tématu Jak potlačit upozornění analýzy kódu.

Konfigurace kódu pro analýzu

Pomocí následujících možností můžete nakonfigurovat, pro které části základu kódu se má toto pravidlo spouštět.

Tyto možnosti je možné nakonfigurovat jenom pro toto pravidlo, pro všechna pravidla, která platí, nebo pro všechna pravidla v této kategorii (návrh), na která platí. Další informace naleznete v tématu Možnosti konfigurace pravidla kvality kódu.

Zahrnutí konkrétních povrchů rozhraní API

Na základě přístupnosti můžete nakonfigurovat, na kterých částech základu kódu se má toto pravidlo spouštět. Pokud chcete například určit, že pravidlo by se mělo spouštět jenom na neveřejné ploše rozhraní API, přidejte do souboru .editorconfig v projektu následující pár klíč-hodnota:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Poznámka:

Tato možnost je podporována pouze pro CA1062 v .NET 7 a novějších verzích.

Vyloučení konkrétních symbolů

Z analýzy můžete vyloučit konkrétní symboly, jako jsou typy a metody. Pokud chcete například určit, že pravidlo by se nemělo spouštět u žádného kódu v rámci pojmenovaných MyTypetypů, přidejte do souboru .editorconfig v projektu následující dvojici klíč-hodnota:

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

Povolené formáty názvů symbolů v hodnotě možnosti (oddělené ):|

  • Pouze název symbolu (zahrnuje všechny symboly s názvem bez ohledu na typ nebo obor názvů).
  • Plně kvalifikované názvy ve formátu ID dokumentace symbolu. Každý název symbolu vyžaduje předponu typu symbolu, například M: pro metody, T: typy a N: obory názvů.
  • .ctor pro konstruktory a .cctor statické konstruktory.

Příklady:

Hodnota možnosti Shrnutí
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType Odpovídá všem symbolům s názvem MyType.
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1|MyType2 Porovná všechny symboly pojmenované buď MyType1 nebo MyType2.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType) Odpovídá konkrétní metodě MyMethod se zadaným plně kvalifikovaným podpisem.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType) Odpovídá konkrétním metodám MyMethod1 a MyMethod2 příslušným plně kvalifikovaným podpisům.

Vyloučení konkrétních typů a jejich odvozených typů

Z analýzy můžete vyloučit konkrétní typy a jejich odvozené typy. Pokud chcete například určit, že pravidlo by se nemělo spouštět u žádné metody v rámci pojmenovaných MyType typů a jejich odvozených typů, přidejte do souboru .editorconfig v projektu následující dvojici klíč-hodnota:

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

Povolené formáty názvů symbolů v hodnotě možnosti (oddělené ):|

  • Pouze název typu (zahrnuje všechny typy s názvem bez ohledu na typ nebo obor názvů).
  • Plně kvalifikované názvy ve formátu ID dokumentace symbolu s volitelnou T: předponou.

Příklady:

Hodnota možnosti Shrnutí
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType Odpovídá všem pojmenovaným MyType typům a všem jejich odvozeným typům.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1|MyType2 Odpovídá všem typům pojmenovaným buď MyType1 nebo MyType2 a všem jejich odvozeným typům.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType Odpovídá určitému typu MyType s daným plně kvalifikovaným názvem a všemi jeho odvozenými typy.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1|M:NS2.MyType2 Odpovídá konkrétním typům MyType1 a MyType2 příslušným plně kvalifikovaným názvům a všem jejich odvozeným typům.

Vyloučit metodu rozšíření this parametr

Ve výchozím nastavení toto pravidlo analyzuje a označí this parametr pro rozšiřující metody. Analýzu parametru this pro metody rozšíření můžete vyloučit přidáním následujícího páru klíč-hodnota do souboru .editorconfig v projektu:

dotnet_code_quality.CA1062.exclude_extension_method_this_parameter = true

Metody ověřování kontroly null

Toto pravidlo může vést k falešně pozitivním výsledkům, pokud váš kód volá speciální metody ověřování kontroly null v odkazovaných knihovnách nebo projektech. Těmto falešně pozitivním výsledkům se můžete vyhnout zadáním názvu nebo podpisu ověřovacích metod kontroly null. Analýza předpokládá, že argumenty předané těmto metodám po volání nejsou null. Pokud chcete například označit všechny metody pojmenované Validate jako metody ověřování null-check, přidejte do souboru .editorconfig v projektu následující dvojici klíč-hodnota:

dotnet_code_quality.CA1062.null_check_validation_methods = Validate

Povolené formáty názvů metod v hodnotě možnosti (oddělené ):|

  • Pouze název metody (zahrnuje všechny metody s názvem bez ohledu na typ nebo obor názvů).
  • Plně kvalifikované názvy ve formátu ID dokumentace symbolu s volitelnou M: předponou.

Příklady:

Hodnota možnosti Shrnutí
dotnet_code_quality.CA1062.null_check_validation_methods = Validate Odpovídá všem metodám pojmenovanými Validate v kompilaci.
dotnet_code_quality.CA1062.null_check_validation_methods = Validate1|Validate2 Porovná všechny metody pojmenované buď Validate1 nebo Validate2 v kompilaci.
dotnet_code_quality.CA1062.null_check_validation_methods = NS.MyType.Validate(ParamType) Odpovídá konkrétní metodě Validate s daným plně kvalifikovaným podpisem.
dotnet_code_quality.CA1062.null_check_validation_methods = NS1.MyType1.Validate1(ParamType)|NS2.MyType2.Validate2(ParamType) Odpovídá konkrétním metodám Validate1 a Validate2 s příslušným plně kvalifikovaným podpisem.

Příklad 1

Následující příklad ukazuje metodu, která porušuje pravidlo a metodu, která pravidlo splňuje.

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

Příklad 2

Konstruktory kopírování, které naplňují pole nebo vlastnosti, které jsou referenčními objekty, mohou také narušit pravidlo CA1062. K porušení dojde, protože zkopírovaný objekt, který je předán do konstruktoru kopírování může být null (Nothing v jazyce Visual Basic). Chcete-li vyřešit porušení, pomocí static metody (Shared v jazyce Visual Basic) zkontrolujte, zda zkopírovaný objekt není null.

V následujícím Person příkladu třídy může být nullobjekt, other který je předán do konstruktoru Person kopírování .

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)
    {
    }
}

Příklad 3

V následujícím upraveném Person příkladu other je objekt předaný konstruktoru kopírování nejprve zkontrolován null v PassThroughNonNull metodě.

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;
    }
}