CA1062: Nyilvános metódusok argumentumainak ellenőrzése

Tulajdonság	Érték
Szabályazonosító	CA1062
Cím	Nyilvános metódusok argumentumainak érvényesítése
Kategória	Design
A javítás kompatibilitástörő vagy nem törik	Nem törés
Alapértelmezés szerint engedélyezve a .NET 8-ban	Nem

Ok

A külsőleg látható metódusok nem ellenőrzik, hogy az argumentum (Nothinga Visual Basicben) szerepel-e null .

Ezt a szabályt úgy konfigurálhatja, hogy bizonyos típusokat és paramétereket kizárjon az elemzésből. A null-ellenőrző érvényesítési módszereket is megjelölheti.

Szabály leírása

A külsőleg látható metódusoknak átadott összes hivatkozási argumentumot nullellenőrizni kell. Ha szükséges, dobjon egy ArgumentNullException értéket, ha az argumentum értéke .null

Ha egy metódus meghívható egy ismeretlen szerelvényből, mert nyilvánosnak vagy védettnek nyilvánították, ellenőrizze a metódus összes paraméterét. Ha a metódust úgy tervezték, hogy csak ismert szerelvények hívják meg, jelölje meg a metódust internal , és alkalmazza az InternalsVisibleToAttribute attribútumot a metódust tartalmazó szerelvényre.

Szabálysértések kijavítása

A szabály megsértésének kijavításához ellenőrizze az egyes hivatkozási argumentumokat null.

Mikor kell letiltani a figyelmeztetéseket?

A szabály figyelmeztetését letilthatja, ha biztos abban, hogy a dereferenced paramétert a függvény egy másik metódushívása érvényesítette.

Figyelmeztetés mellőzése

Ha csak egyetlen szabálysértést szeretne letiltani, adjon hozzá előfeldolgozási irányelveket a forrásfájlhoz a szabály letiltásához és újbóli engedélyezéséhez.

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

Ha le szeretné tiltani egy fájl, mappa vagy projekt szabályát, állítsa annak súlyosságát none a konfigurációs fájlban.

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

További információ: Kódelemzési figyelmeztetések letiltása.

Kód konfigurálása elemzéshez

A következő beállítások segítségével konfigurálhatja, hogy a kódbázis mely részein futtassa ezt a szabályt.

• Adott API-felületek belefoglalása
• Adott szimbólumok kizárása
• Adott típusok és származtatott típusok kizárása
• Az "ez" paraméter bővítménymetódus kizárása
• Null ellenőrzési ellenőrzési módszerek

Ezek a beállítások konfigurálhatók csak ehhez a szabályhoz, az összes szabályhoz, vagy az ebben a kategóriában (Tervezés) szereplő összes szabályhoz, amelyekre vonatkozik. További információ: Kódminőségi szabály konfigurációs beállításai.

Adott API-felületek belefoglalása

A kódbázis azon részeit konfigurálhatja, amelyeken futtathatja ezt a szabályt az akadálymentességük alapján. Ha például meg szeretné adni, hogy a szabály csak a nem nyilvános API-felületen fusson, adja hozzá a következő kulcs-érték párot a projekt egyik .editorconfig fájljához:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Feljegyzés

Ez a beállítás csak a .NET 7-es és újabb verzióiban támogatott CA1062 esetén.

Adott szimbólumok kizárása

Bizonyos szimbólumokat, például típusokat és metódusokat kizárhat az elemzésből. Ha például meg szeretné adni, hogy a szabály ne fusson a nevesített MyTypetípusok egyikén sem, adja hozzá a következő kulcs-érték párot a projekt egyik .editorconfig fájljához:

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

Engedélyezett szimbólumnévformátumok a beállításértékben (a következővel |elválasztva):

• Csak szimbólumnév (a névvel ellátott összes szimbólumot tartalmazza, függetlenül attól, hogy milyen típusú vagy névtérrel rendelkezik).
• A szimbólum dokumentációazonosító-formátumában szereplő teljes nevek. Minden szimbólumnévhez szimbólum típusú előtag szükséges, például M: metódusokhoz, T: típusokhoz és N: névterekhez.
• .ctor konstruktorok és .cctor statikus konstruktorok számára.

Példák:

Beállítás értéke	Összegzés
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType	Megegyezik az összes elnevezett MyTypeszimbólummal.
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1|MyType2	Megegyezik az összes elnevezett MyType1 szimbólummal vagy MyType2.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType)	Megfelel a megadott metódusnak MyMethod a megadott teljes jogosultsággal rendelkező aláírással.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType)	Egyezik az adott metódusokkal MyMethod1 és MyMethod2 a megfelelő, teljes mértékben minősített aláírásokkal.

Adott típusok és származtatott típusok kizárása

Bizonyos típusokat és azok származtatott típusait kizárhatja az elemzésből. Ha például meg szeretné adni, hogy a szabály ne fusson a nevesített MyType és származtatott típusok egyik metódusán sem, adja hozzá a következő kulcs-érték párot a projekt egyik .editorconfig fájljához:

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

Engedélyezett szimbólumnévformátumok a beállításértékben (a következővel |elválasztva):

• Csak típusnév (a névvel rendelkező összes típust tartalmazza, függetlenül attól, hogy milyen típust vagy névteret tartalmaz).
• A szimbólum dokumentációazonosító-formátumában szereplő teljes nevek opcionális T: előtaggal.

Példák:

Beállítás értéke	Összegzés
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType	Megfelel az összes névvel ellátott MyType típusnak és az összes származtatott típusnak.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1|MyType2	Megfelel az összes névvel ellátott MyType1 típusnak, vagy MyType2 az összes származtatott típusnak.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType	Egyezik MyType a megadott teljes névvel és az összes származtatott típusával.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1|M:NS2.MyType2	Egyezik az adott típusokkal MyType1 és MyType2 a megfelelő teljes névvel, valamint az összes származtatott típussal.

Az "ez" paraméter bővítménymetódus kizárása

Ez a szabály alapértelmezés szerint elemzi és megjelöli a this bővítménymetelyek paraméterét. Kizárhatja a this bővítménymetelyek paraméterének elemzését, ha hozzáadja a következő kulcs-érték párot egy .editorconfig fájlhoz a projektben:

dotnet_code_quality.CA1062.exclude_extension_method_this_parameter = true

Null ellenőrzési ellenőrzési módszerek

Ez a szabály hamis pozitív eredményhez vezethet, ha a kód speciális null-ellenőrzési ellenőrzési módszereket hív meg a hivatkozott kódtárakban vagy projektekben. Ezeket a hamis pozitív értékeket elkerülheti a null-ellenőrző érvényesítési módszerek nevének vagy aláírásának megadásával. Az elemzés feltételezi, hogy a metódusoknak átadott argumentumok nem null értékűek a hívás után. Ha például az összes metódust Validate null-ellenőrző érvényesítési metódusként szeretné megjelölni, adja hozzá a következő kulcs-érték párot a projekt egyik .editorconfig fájljához:

dotnet_code_quality.CA1062.null_check_validation_methods = Validate

Engedélyezett metódusnévformátumok a beállításértékben (a következővel |elválasztva):

• Csak a metódus neve (a névvel rendelkező összes metódust tartalmazza, függetlenül a nevet tartalmazó típustól vagy névtértől).
• A szimbólum dokumentációazonosító-formátumában szereplő teljes nevek opcionális M: előtaggal.

Példák:

Beállítás értéke	Összegzés
dotnet_code_quality.CA1062.null_check_validation_methods = Validate	Megfelel a fordításban elnevezett Validate összes metódusnak.
dotnet_code_quality.CA1062.null_check_validation_methods = Validate1|Validate2	Megfelel a fordításban vagy Validate2 a Validate1 fordításban szereplő összes metódusnak.
dotnet_code_quality.CA1062.null_check_validation_methods = NS.MyType.Validate(ParamType)	Megfelel a megadott metódusnak Validate a megadott teljes aláírással.
dotnet_code_quality.CA1062.null_check_validation_methods = NS1.MyType1.Validate1(ParamType)|NS2.MyType2.Validate2(ParamType)	Egyezik a megadott metódusokkal Validate1 és Validate2 a megfelelő teljes aláírással.

1. példa

Az alábbi példa egy olyan metódust mutat be, amely megsérti a szabályt, és egy olyan metódust, amely megfelel a szabálynak.

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

2. példa

A referenciaobjektumokat tartalmazó mezőket vagy tulajdonságokat felépítő konstruktorok másolása a CA1062 szabályt is sértheti. A szabálysértés azért fordul elő, mert a másolási konstruktornak átadott másolt objektum lehet null (Nothing a Visual Basicben). A szabálysértés elhárításához használjon (staticSharedVisual Basic) metódust annak ellenőrzéséhez, hogy a másolt objektum nem null értékű-e.

Az alábbi Person osztály példában a other másolási konstruktornak átadott objektum lehetnull.Person

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

3. példa

A következő módosított Person példában a other másolási konstruktornak átadott objektum először null értékre van bejelölve a PassThroughNonNull metódusban.

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