Bagikan melalui

CA1062: Memvalidasi argumen metode publik

  • Artikel
Properti Nilai
ID Aturan CA1062
Judul Validasi argumen metode publik
Golongan Desain
Perbaikan bersifat disruptif atau non-disruptif Non-disruptif
Diaktifkan secara default di .NET 8 No

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.

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

Menyertakan permukaan API tertentu

Anda dapat mengonfigurasi bagian mana dari basis kode yang akan menjalankan aturan ini, berdasarkan aksesibilitasnya. 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

Catatan

Opsi ini hanya didukung untuk CA1062 di .NET 7 dan versi yang lebih baru.

Mengecualikan simbol tertentu

Anda dapat mengecualikan simbol tertentu, seperti jenis dan metode, dari analisis. 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:

Nilai Opsi Ringkasan
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType Mencocokkan semua simbol bernama MyType.
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1|MyType2 Mencocokkan semua simbol bernama MyType1 atau MyType2.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType) Mencocokkan MyMethod metode tertentu dengan tanda tangan yang sepenuhnya memenuhi syarat yang ditentukan.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType) Mencocokkan MyMethod1 dan MyMethod2 metode tertentu dengan masing-masing tanda tangan yang sepenuhnya memenuhi syarat.

Mengecualikan jenis tertentu dan jenis turunannya

Anda dapat mengecualikan jenis tertentu dan jenis turunannya dari analisis. 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:

Nilai Opsi Ringkasan
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType Mencocokkan semua jenis bernama MyType dan semua jenis turunannya.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1|MyType2 Mencocokkan semua jenis bernama MyType1 atau MyType2 dan semua jenis turunannya.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType Mencocokkan MyType jenis tertentu dengan nama yang sepenuhnya memenuhi syarat tertentu dan semua jenis turunannya.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1|M:NS2.MyType2 Mencocokkan MyType1 dan MyType2 jenis tertentu dengan masing-masing nama yang sepenuhnya memenuhi syarat, dan semua jenis turunannya.

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:

Nilai Opsi Ringkasan
dotnet_code_quality.CA1062.null_check_validation_methods = Validate Cocok dengan semua metode yang dinamai Validate dalam kompilasi.
dotnet_code_quality.CA1062.null_check_validation_methods = Validate1|Validate2 Cocok dengan semua metode bernama baik Validate1 atau Validate2 dalam kompilasi.
dotnet_code_quality.CA1062.null_check_validation_methods = NS.MyType.Validate(ParamType) Cocok dengan metode Validate tertentu dengan tanda tangan yang sepenuhnya memenuhi syarat.
dotnet_code_quality.CA1062.null_check_validation_methods = NS1.MyType1.Validate1(ParamType)|NS2.MyType2.Validate2(ParamType) Cocok dengan metode Validate1 tertentu dan Validate2 dengan masing-masing tanda tangan yang sepenuhnya memenuhi syarat.

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