Delen via

CA1062: Argumenten van openbare methoden valideren

  • Artikel
Eigenschappen Weergegeven als
Regel-id CA1062
Titel Argumenten van openbare methoden valideren
Categorie Ontwerpen
Oplossing is brekend of niet-brekend Niet-brekend
Standaard ingeschakeld in .NET 8 Nee

Oorzaak

Een extern zichtbare methode deducteert een van de verwijzingsargumenten zonder te controleren of dat argument is null (Nothing in Visual Basic).

U kunt deze regel configureren om bepaalde typen en parameters uit te sluiten van analyse. U kunt ook validatiemethoden voor null-controles aangeven.

Beschrijving van regel

Alle verwijzingsargumenten die worden doorgegeven aan extern zichtbare methoden, moeten worden gecontroleerd op null. Indien van toepassing, genereert u een ArgumentNullException wanneer het argument is null.

Als een methode kan worden aangeroepen vanuit een onbekende assembly omdat deze openbaar of beveiligd is, moet u alle parameters van de methode valideren. Als de methode alleen door bekende assembly's moet worden aangeroepen, markeert u de methode internal en past u het InternalsVisibleToAttribute kenmerk toe op de assembly die de methode bevat.

Schendingen oplossen

Als u een schending van deze regel wilt oplossen, valideert u elk verwijzingsargument tegen null.

Wanneer waarschuwingen onderdrukken

U kunt een waarschuwing van deze regel onderdrukken als u zeker weet dat de parameter met de deductie is gevalideerd door een andere methodeaanroep in de functie.

Een waarschuwing onderdrukken

Als u slechts één schending wilt onderdrukken, voegt u preprocessorrichtlijnen toe aan uw bronbestand om de regel uit te schakelen en vervolgens opnieuw in te schakelen.

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

Als u de regel voor een bestand, map of project wilt uitschakelen, stelt u de ernst none ervan in op het configuratiebestand.

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

Zie Codeanalysewaarschuwingen onderdrukken voor meer informatie.

Code configureren om te analyseren

Gebruik de volgende opties om te configureren op welke onderdelen van uw codebase deze regel moet worden uitgevoerd.

Deze opties kunnen worden geconfigureerd voor alleen deze regel, voor alle regels waarop deze van toepassing is, of voor alle regels in deze categorie (ontwerp) waarop deze van toepassing is. Zie de configuratieopties voor de codekwaliteitsregel voor meer informatie.

Specifieke API-oppervlakken opnemen

U kunt instellen op welke onderdelen van uw codebase deze regel moet worden uitgevoerd, op basis van hun toegankelijkheid. Als u bijvoorbeeld wilt opgeven dat de regel alleen moet worden uitgevoerd op het niet-openbare API-oppervlak, voegt u het volgende sleutel-waardepaar toe aan een .editorconfig-bestand in uw project:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Notitie

Deze optie wordt alleen ondersteund voor CA1062 in .NET 7 en latere versies.

Specifieke symbolen uitsluiten

U kunt specifieke symbolen, zoals typen en methoden, uitsluiten van analyse. Als u bijvoorbeeld wilt opgeven dat de regel niet mag worden uitgevoerd op code binnen benoemde MyTypetypen, voegt u het volgende sleutel-waardepaar toe aan een .editorconfig-bestand in uw project:

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

Toegestane notaties voor symboolnamen in de optiewaarde (gescheiden door |):

  • Alleen symboolnaam (inclusief alle symbolen met de naam, ongeacht het type of de naamruimte).
  • Volledig gekwalificeerde namen in de documentatie-id-indeling van het symbool. Voor elke symboolnaam is een voorvoegsel van het type symbool vereist, zoals M: voor methoden, T: voor typen en N: voor naamruimten.
  • .ctor voor constructors en .cctor voor statische constructors.

Voorbeelden:

Optiewaarde Samenvatting
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType Komt overeen met alle symbolen met de naam MyType.
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1|MyType2 Komt overeen met alle symbolen met de naam of MyType1MyType2.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType) Komt overeen met een specifieke methode MyMethod met de opgegeven volledig gekwalificeerde handtekening.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType) Komt overeen met specifieke methoden MyMethod1 en MyMethod2 met de respectieve volledig gekwalificeerde handtekeningen.

Specifieke typen en hun afgeleide typen uitsluiten

U kunt specifieke typen en hun afgeleide typen uitsluiten van analyse. Als u bijvoorbeeld wilt opgeven dat de regel niet mag worden uitgevoerd op methoden binnen benoemde MyType typen en de afgeleide typen, voegt u het volgende sleutel-waardepaar toe aan een .editorconfig-bestand in uw project:

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

Toegestane notaties voor symboolnamen in de optiewaarde (gescheiden door |):

  • Alleen de naam van het type (bevat alle typen met de naam, ongeacht het type of de naamruimte).
  • Volledig gekwalificeerde namen in de documentatie-id-indeling van het symbool, met een optioneel T: voorvoegsel.

Voorbeelden:

Optiewaarde Samenvatting
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType Komt overeen met alle typen met de naam MyType en alle afgeleide typen.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1|MyType2 Komt overeen met alle typen met de naam MyType1 of MyType2 en alle afgeleide typen.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType Komt overeen met een specifiek type MyType met een volledig gekwalificeerde naam en alle afgeleide typen.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1|M:NS2.MyType2 Komt overeen met specifieke typen MyType1 en MyType2 met de respectieve volledig gekwalificeerde namen en alle afgeleide typen.

Extensiemethode 'this' uitsluiten

Deze regel analyseert en markeert standaard de this parameter voor extensiemethoden. U kunt analyse van de this parameter voor extensiemethoden uitsluiten door het volgende sleutel-waardepaar toe te voegen aan een .editorconfig-bestand in uw project:

dotnet_code_quality.CA1062.exclude_extension_method_this_parameter = true

Validatiemethoden voor null-controles

Deze regel kan leiden tot fout-positieven als uw code speciale validatiemethoden voor null-controle aanroept in bibliotheken of projecten waarnaar wordt verwezen. U kunt deze fout-positieven voorkomen door de naam of handtekening van validatiemethoden voor null-controles op te geven. Bij de analyse wordt ervan uitgegaan dat argumenten die aan deze methoden worden doorgegeven, niet null zijn na de aanroep. Als u bijvoorbeeld alle methoden met de naam Validate null-controlevalidatiemethoden wilt markeren, voegt u het volgende sleutel-waardepaar toe aan een .editorconfig-bestand in uw project:

dotnet_code_quality.CA1062.null_check_validation_methods = Validate

Indelingen van toegestane methodenamen in de optiewaarde (gescheiden door |):

  • Alleen de naam van de methode (bevat alle methoden met de naam, ongeacht het type of de naamruimte).
  • Volledig gekwalificeerde namen in de documentatie-id-indeling van het symbool, met een optioneel M: voorvoegsel.

Voorbeelden:

Optiewaarde Samenvatting
dotnet_code_quality.CA1062.null_check_validation_methods = Validate Komt overeen met alle methoden die in de compilatie worden genoemd Validate .
dotnet_code_quality.CA1062.null_check_validation_methods = Validate1|Validate2 Komt overeen met alle methoden met de naam of Validate1Validate2 in de compilatie.
dotnet_code_quality.CA1062.null_check_validation_methods = NS.MyType.Validate(ParamType) Komt overeen met een specifieke methode Validate met een volledig gekwalificeerde handtekening.
dotnet_code_quality.CA1062.null_check_validation_methods = NS1.MyType1.Validate1(ParamType)|NS2.MyType2.Validate2(ParamType) Komt overeen met specifieke methoden Validate1 en Validate2 met de respectieve volledig gekwalificeerde handtekening.

Voorbeeld 1

In het volgende voorbeeld ziet u een methode die de regel schendt en een methode die voldoet aan de regel.

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

Voorbeeld 2

Kopieerconstructors die velden of eigenschappen vullen die verwijzingsobjecten zijn, kunnen ook de regel CA1062 schenden. De schending treedt op omdat het gekopieerde object dat wordt doorgegeven aan de kopieerconstructor mogelijk null is (Nothing in Visual Basic). Als u de schending wilt oplossen, gebruikt u een static methode (Shared in Visual Basic) om te controleren of het gekopieerde object niet null is.

In het volgende Person klassevoorbeeld is nullhet other object dat wordt doorgegeven aan de Person kopieerconstructor mogelijk.

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

Voorbeeld 3

In het volgende herziene Person voorbeeld wordt het other object dat wordt doorgegeven aan de kopieerconstructor eerst gecontroleerd op null in de PassThroughNonNull methode.

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