CA1062: Validasi argumen metode publik

Properti Nilai
ID Aturan CA1062
Judul Validasi argumen metode publik
Kategori Desain
Perbaikan bersifat merusak atau tidak merusak Tidak terputus
Diaktifkan secara default di .NET 10 Tidak
Bahasa yang berlaku C# dan Visual Basic

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 menentukan metode validasi pengecekan untuk nilai 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.

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

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

Catatan

Ganti bagian XXXXCAXXXX dengan ID aturan yang berlaku.

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

Catatan

Ganti bagian XXXXCAXXXX dengan ID aturan yang berlaku.

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 metode tertentu MyMethod dengan tanda tangan memenuhi syarat penuh yang ditentukan.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType) Mencocokkan metode tertentu MyMethod1 dan MyMethod2 dengan tanda tangan lengkap masing-masing.

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

Catatan

Ganti bagian XXXXCAXXXX dengan ID aturan yang berlaku.

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 dikualifikasi dalam format ID dokumentasi simbol, dengan awalan T: yang bersifat 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 jenis tertentu MyType dengan nama lengkap yang diberikan dan semua jenis turunannya.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1|M:NS2.MyType2 Mencocokkan jenis tertentu MyType1 dan MyType2 dengan nama lengkap yang memenuhi syarat, serta semua jenis turunannya.

Mengecualikan parameter `this` pada 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 null check

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 tidak 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 |):

  • Nama metode saja (termasuk semua metode dengan nama tersebut, terlepas dari tipe atau namespace yang berisi).
  • Nama yang sepenuhnya dikualifikasi dalam format ID dokumentasi simbol, dengan awalan M: yang bersifat 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 Mencocokkan semua metode yang bernama entah 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 lengkap yang memenuhi syarat.
dotnet_code_quality.CA1062.null_check_validation_methods = NS1.MyType1.Validate1(ParamType)|NS2.MyType2.Validate2(ParamType) Mencocokkan metode tertentu Validate1 dan Validate2 dengan tanda tangan yang sesuai sepenuhnya.

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

Konstruktor salinan yang menginisialisasi 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;
    }
}
  • Last updated on