CA1062: Memvalidasi argumen metode publik

Penyebab

Metode yang terlihat secara eksternal mendereferensikan salah satu argumen referensinya tanpa memverifikasi apakah argumen tersebut merupakan null (Nothing di Visual Basic).

Anda dapat mengonfigurasi aturan ini untuk mengecualikan jenis dan parameter tertentu dari analisis. Anda juga dapat menunjukkan metode validasi pemeriksaan null.

Deskripsi aturan

Semua argumen referensi yang diteruskan ke metode yang terlihat secara eksternal harus diperiksa terhadap null. Jika sesuai, lemparkan ArgumentNullException ketika argumen adalah null.

Jika metode dapat dipanggil dari rakitan yang tidak diketahui karena dinyatakan publik atau dilindungi, Anda harus memvalidasi semua parameter metode. Jika metode dirancang untuk dipanggil hanya oleh rakitan yang diketahui, tandai metode internal dan terapkan atribut InternalsVisibleToAttribute ke rakitan yang berisi metode.

Cara memperbaiki pelanggaran

Untuk memperbaiki pelanggaran aturan ini, validasi setiap argumen referensi terhadap null.

Kapan harus menekan peringatan

Anda dapat menyembunyikan peringatan dari aturan ini jika yakin bahwa parameter dereferensi telah divalidasi oleh panggilan metode lain dalam fungsi.

Menyembunyikan peringatan

Jika Anda hanya ingin menyembunyikan satu pelanggaran, tambahkan arahan praprosedur ke file sumber Anda untuk dinonaktifkan lalu aktifkan kembali aturannya.

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

Untuk menonaktifkan aturan untuk file, folder, atau proyek, atur tingkat keparahannya ke none dalam file konfigurasi.

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

Untuk informasi selengkapnya, lihat Cara menyembunyikan peringatan analisis kode.

Mengonfigurasi kode yang akan dianalisis

Gunakan opsi berikut untuk mengonfigurasi bagian mana dari codebase Anda yang akan menjalankan aturan ini.

• Menyertakan permukaan API tertentu
• Mengecualikan simbol tertentu
• Mengecualikan jenis tertentu dan jenis turunannya
• Mengecualikan parameter 'this' metode ekstensi
• Metode validasi pemeriksaan null

Selain itu, opsi terkait analisis aliran data lainnya berikut berlaku untuk aturan ini:

• interprocedural_analysis_kind
• max_interprocedural_lambda_or_local_function_call_chain
• max_interprocedural_method_call_chain
• points_to_analysis_kind
• copy_analysis
• sufficient_IterationCount_for_weak_KDF_algorithm

Opsi ini dapat dikonfigurasi hanya untuk aturan ini, untuk semua aturan yang berlaku, atau untuk semua aturan dalam kategori ini (Desain) yang berlaku. Untuk informasi selengkapnya, lihat Opsi konfigurasi aturan kualitas kode.

Menyertakan permukaan API tertentu

Anda dapat mengonfigurasi bagian basis kode mana yang akan dijalankan aturan ini, berdasarkan aksesibilitasnya, dengan mengatur opsi api_surface. Misalnya, untuk menentukan bahwa aturan hanya boleh dijalankan pada permukaan API non-publik, tambahkan pasangan kunci-nilai berikut ke file .editorconfig di proyek Anda:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Mengecualikan simbol tertentu

Anda dapat mengecualikan simbol tertentu, seperti jenis dan metode, dari analisis dengan mengatur opsi excluded_symbol_names. Misalnya, untuk menentukan bahwa aturan tidak boleh berjalan pada kode apa pun dalam jenis bernama MyType, tambahkan pasangan kunci-nilai berikut ke file .editorconfig di proyek Anda:

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

Format nama simbol yang diizinkan pada nilai opsi (dipisahkan oleh |):

• Nama simbol saja (menyertakan semua simbol dengan nama, terlepas dari jenis atau namespace yang memuatnya).
• Nama yang sepenuhnya memenuhi syarat dalam format ID dokumentasi simbol. Setiap nama simbol memerlukan awalan jenis simbol, seperti M: untuk metode, T: untuk jenis, dan N: untuk namespace.
• .ctor untuk konstruktor dan .cctor untuk konstruktor statik.

Contoh:

Mengecualikan jenis tertentu dan jenis turunannya

Anda dapat mengecualikan jenis tertentu dan jenis turunannya dari analisis dengan mengatur opsi excluded_type_names_with_derived_types. Misalnya, untuk menentukan bahwa aturan tidak boleh dijalankan pada metode apa pun dalam jenis bernama MyType dan jenis turunannya, tambahkan pasangan kunci-nilai berikut ke file .editorconfig di proyek Anda:

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

Format nama simbol yang diizinkan pada nilai opsi (dipisahkan oleh |):

• Nama jenis saja (mencakup semua jenis dengan nama, terlepas dari jenis atau namespace yang memuatnya).
• Nama yang sepenuhnya memenuhi syarat dalam format ID dokumentasi simbol, dengan awalan T: opsional.

Contoh:

Mengecualikan parameter 'this' metode ekstensi

Secara default, aturan ini menganalisis dan menandai parameter this untuk metode ekstensi. Anda dapat mengecualikan analisis parameter this untuk metode ekstensi dengan menambahkan pasangan kunci-nilai berikut ke file .editorconfig dalam proyek Anda:

dotnet_code_quality.CA1062.exclude_extension_method_this_parameter = true

Metode validasi pemeriksaan null

Aturan ini dapat menyebabkan positif palsu jika kode Anda memanggil metode validasi pemeriksaan null khusus di pustaka atau proyek yang direferensikan. Anda dapat menghindari positif palsu ini dengan menentukan nama atau tanda tangan metode validasi pemeriksaan null. Analisis mengasumsikan bahwa argumen yang diteruskan ke metode ini bukanlah null setelah dipanggil. Misalnya, untuk menandai semua metode bernama Validate sebagai metode validasi pemeriksaan null, tambahkan pasangan kunci-nilai berikut ke file .editorconfig dalam proyek Anda:

dotnet_code_quality.CA1062.null_check_validation_methods = Validate

Format nama metode yang diizinkan pada nilai opsi (dipisahkan oleh |):

• Khusus nama metode (termasuk semua metode dengan nama, terlepas dari namespace layanan atau jenis yang berisi).
• Nama yang sepenuhnya memenuhi syarat dalam format ID dokumentasi simbol, dengan awalan M: opsional.

Contoh:

Contoh 1

Contoh berikut menunjukkan metode yang melanggar aturan dan metode yang memenuhi aturan.

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

Contoh 2

Menyalin konstruktor yang mengisi bidang atau properti yang merupakan objek referensi juga dapat melanggar aturan CA1062. Pelanggaran terjadi karena objek yang disalin yang diteruskan ke konstruktor salinan mungkin null (Nothing di Visual Basic). Untuk mengatasi pelanggaran, gunakan metode static (Shared di Visual Basic) untuk memeriksa apakah objek yang disalin bukan null.

Dalam contoh kelas Person berikut, objek other yang diteruskan ke konstruktor salinan Person mungkin 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)
    {
    }
}

Contoh 3

Dalam contoh Person direvisi berikut, objek other yang diteruskan ke konstruktor salin diperiksa terlebih dahulu terhadap null dalam metode PassThroughNonNull.

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