CA1062: Verifiera argument för offentliga metoder

Artikel
09/06/2023

Property	Värde
Regel-ID	CA1062
Title	Verifiera argument för offentliga metoder
Kategori	Designa
Korrigeringen är icke-bakåtkompatibel	Icke-icke-bryta
Aktiverad som standard i .NET 8	Nej

Orsak

En externt synlig metod avrefererar ett av dess referensargument utan att verifiera om argumentet är null (Nothing i Visual Basic).

Du kan konfigurera den här regeln för att undanta vissa typer och parametrar från analys. Du kan också ange valideringsmetoder för null-check.

Regelbeskrivning

Alla referensargument som skickas till externt synliga metoder ska kontrolleras mot null. Om det är lämpligt genererar du en ArgumentNullException när argumentet är null.

Om en metod kan anropas från en okänd sammansättning eftersom den deklareras som offentlig eller skyddad bör du verifiera alla parametrar för metoden. Om metoden är utformad för att anropas endast av kända sammansättningar markerar du metoden internal och tillämpar InternalsVisibleToAttribute attributet på den sammansättning som innehåller metoden.

Så här åtgärdar du överträdelser

Om du vill åtgärda ett brott mot den här regeln verifierar du varje referensargument mot null.

När du ska ignorera varningar

Du kan ignorera en varning från den här regeln om du är säker på att den avrefererade parametern har verifierats av ett annat metodanrop i funktionen.

Ignorera en varning

Om du bara vill förhindra en enda överträdelse lägger du till förprocessordirektiv i källfilen för att inaktivera och aktiverar sedan regeln igen.

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

Om du vill inaktivera regeln för en fil, mapp eller ett projekt anger du dess allvarlighetsgrad till none i konfigurationsfilen.

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

Mer information finns i Så här utelämnar du kodanalysvarningar.

Konfigurera kod för analys

Använd följande alternativ för att konfigurera vilka delar av kodbasen som regeln ska köras på.

Inkludera specifika API-ytor
Exkludera specifika symboler
Exkludera specifika typer och deras härledda typer
Exkludera tilläggsmetoden "den här" parametern
Valideringsmetoder för null-kontroll

Dessa alternativ kan konfigureras för just den här regeln, för alla regler som den gäller för eller för alla regler i den här kategorin (design) som den gäller för. Mer information finns i Konfigurationsalternativ för kodkvalitetsregel.

Inkludera specifika API-ytor

Du kan konfigurera vilka delar av kodbasen som ska köras med den här regeln baserat på deras tillgänglighet. Om du till exempel vill ange att regeln endast ska köras mot den icke-offentliga API-ytan lägger du till följande nyckel/värde-par i en .editorconfig-fil i projektet:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Kommentar

Det här alternativet stöds endast för CA1062 i .NET 7 och senare versioner.

Exkludera specifika symboler

Du kan exkludera specifika symboler, till exempel typer och metoder, från analys. Om du till exempel vill ange att regeln inte ska köras på någon kod inom typer med namnet MyTypelägger du till följande nyckel/värde-par i en .editorconfig-fil i projektet:

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

Tillåtna symbolnamnformat i alternativvärdet (avgränsade med |):

Endast symbolnamn (innehåller alla symboler med namnet, oavsett vilken typ eller namnrymd som innehåller).
Fullständigt kvalificerade namn i symbolens dokumentations-ID-format. Varje symbolnamn kräver ett symboltypprefix, till exempel M: för metoder, T: för typer och N: för namnområden.
.ctor för konstruktorer och .cctor statiska konstruktorer.

Exempel:

Alternativvärde	Sammanfattning
`dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType`	Matchar alla symboler med namnet `MyType`.
`dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1\|MyType2`	Matchar alla symboler med namnet antingen `MyType1` eller `MyType2`.
`dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType)`	Matchar en specifik metod `MyMethod` med den angivna fullständigt kvalificerade signaturen.
`dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)\|M:NS2.MyType2.MyMethod2(ParamType)`	Matchar specifika metoder `MyMethod1` och `MyMethod2` med respektive fullständigt kvalificerade signaturer.

Exkludera specifika typer och deras härledda typer

Du kan exkludera specifika typer och deras härledda typer från analys. Om du till exempel vill ange att regeln inte ska köras på några metoder inom typer som heter MyType och deras härledda typer lägger du till följande nyckel/värde-par i en .editorconfig-fil i projektet:

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

Tillåtna symbolnamnformat i alternativvärdet (avgränsade med |):

Skriv endast namn (innehåller alla typer med namnet, oavsett vilken typ eller namnrymd som innehåller).
Fullständigt kvalificerade namn i symbolens dokumentations-ID-format, med ett valfritt T: prefix.

Exempel:

Alternativvärde	Sammanfattning
`dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType`	Matchar alla typer med namnet `MyType` och alla deras härledda typer.
`dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1\|MyType2`	Matchar alla typer med namnet antingen `MyType1` eller `MyType2` och alla deras härledda typer.
`dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType`	Matchar en specifik typ `MyType` med ett angivet fullständigt kvalificerat namn och alla dess härledda typer.
`dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1\|M:NS2.MyType2`	Matchar specifika typer `MyType1` och `MyType2` med respektive fullständigt kvalificerade namn och alla deras härledda typer.

Exkludera tilläggsmetoden "den här" parametern

Som standard analyserar och flaggar den här regeln parametern this för tilläggsmetoder. Du kan undanta analys av parametern this för tilläggsmetoder genom att lägga till följande nyckel/värde-par i en .editorconfig-fil i projektet:

dotnet_code_quality.CA1062.exclude_extension_method_this_parameter = true

Valideringsmetoder för null-kontroll

Den här regeln kan leda till falska positiva identifieringar om koden anropar särskilda valideringsmetoder för null-check i refererade bibliotek eller projekt. Du kan undvika dessa falska positiva identifieringar genom att ange namn eller signatur för valideringsmetoder med null-kontroll. Analysen förutsätter att argument som skickas till dessa metoder inte är null efter anropet. Om du till exempel vill markera alla metoder med namnet Validate null-check-valideringsmetoder lägger du till följande nyckel/värde-par i en .editorconfig-fil i projektet:

dotnet_code_quality.CA1062.null_check_validation_methods = Validate

Tillåtna metodnamnformat i alternativvärdet (avgränsade med |):

Endast metodnamn (innehåller alla metoder med namnet, oavsett vilken typ eller namnrymd som finns).
Fullständigt kvalificerade namn i symbolens dokumentations-ID-format, med ett valfritt M: prefix.

Exempel:

Alternativvärde	Sammanfattning
`dotnet_code_quality.CA1062.null_check_validation_methods = Validate`	Matchar alla metoder med namnet `Validate` i kompilering.
`dotnet_code_quality.CA1062.null_check_validation_methods = Validate1\|Validate2`	Matchar alla metoder med namnet antingen `Validate1` eller `Validate2` i kompilering.
`dotnet_code_quality.CA1062.null_check_validation_methods = NS.MyType.Validate(ParamType)`	Matchar en specifik metod `Validate` med en given fullständigt kvalificerad signatur.
`dotnet_code_quality.CA1062.null_check_validation_methods = NS1.MyType1.Validate1(ParamType)\|NS2.MyType2.Validate2(ParamType)`	Matchar specifika metoder `Validate1` och `Validate2` med respektive fullständigt kvalificerade signatur.

Exempel 1

I följande exempel visas en metod som bryter mot regeln och en metod som uppfyller regeln.

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

Exempel 2

Kopieringskonstruktorer som fyller i fält eller egenskaper som är referensobjekt kan också bryta mot regeln CA1062. Överträdelsen beror på att det kopierade objektet som skickas till kopieringskonstruktorn kan vara null (Nothing i Visual Basic). Lös överträdelsen genom att använda metoden static (Shared i Visual Basic) för att kontrollera att det kopierade objektet inte är null.

I följande Person klassexempel kan objektet other som skickas till Person kopieringskonstruktorn vara null.

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

Exempel 3

I följande ändrade Person exempel kontrolleras först objektet other som skickas till kopieringskonstruktorn för null i PassThroughNonNull metoden.

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

Dela via

CA1062: Verifiera argument för offentliga metoder

Orsak

Regelbeskrivning

Så här åtgärdar du överträdelser

När du ska ignorera varningar

Ignorera en varning

Konfigurera kod för analys

Inkludera specifika API-ytor

Exkludera specifika symboler

Exkludera specifika typer och deras härledda typer

Exkludera tilläggsmetoden "den här" parametern

Valideringsmetoder för null-kontroll

Exempel 1

Exempel 2

Exempel 3

Ytterligare resurser