Bagikan melalui

CA1700: Jangan beri nama nilai enum 'Reserved'

  • Artikel
Properti Nilai
ID Aturan CA1700
Judul Jangan beri nama nilai enum 'Dicadangkan'
Golongan Penamaan
Perbaikan bersifat disruptif atau non-disruptif Merusak
Diaktifkan secara default di .NET 8 Tidak

Penyebab

Nama anggota enumerasi berisi kata "dicadangkan".

Deskripsi aturan

Aturan ini mengasumsikan bahwa anggota enumerasi yang memiliki nama yang berisi "reserved" saat ini tidak digunakan tetapi merupakan tempat penampung yang akan diganti namanya atau dihapus di versi mendatang. Mengganti nama atau menghapus anggota adalah perubahan yang melanggar. Anda tidak boleh mengharapkan pengguna mengabaikan anggota hanya karena namanya berisi "dicadangkan", Anda juga tidak dapat mengandalkan pengguna untuk membaca atau mematuhi dokumentasi. Selain itu, karena anggota yang dipesan muncul di browser objek dan lingkungan pengembangan terintegrasi yang cerdas, mereka dapat menyebabkan kebingungan tentang anggota mana yang benar-benar digunakan.

Alih-alih menggunakan anggota yang dipesan, tambahkan anggota baru ke enumerasi di versi mendatang. Dalam kebanyakan kasus penambahan anggota baru bukanlah perubahan yang melanggar, selama penambahan tidak menyebabkan nilai anggota asli berubah.

Dalam jumlah terbatas, penambahan anggota adalah perubahan yang melanggar bahkan ketika anggota asli mempertahankan nilai aslinya. Terutama, anggota baru tidak dapat dikembalikan dari jalur kode yang ada tanpa melanggar pemanggil yang menggunakan switch pernyataan (Select dalam Visual Basic) pada nilai pengembalian yang mencakup seluruh daftar anggota dan yang memunculkan pengecualian dalam kasus default. Kekhawatiran sekunder adalah bahwa kode klien mungkin tidak menangani perubahan perilaku dari metode refleksi seperti System.Enum.IsDefined. Dengan demikian, jika anggota baru harus dikembalikan dari metode yang ada atau ketidaksesuaian aplikasi yang diketahui terjadi karena penggunaan refleksi yang buruk, satu-satunya solusi yang tidak pecah adalah:

  1. Tambahkan enumerasi baru yang berisi anggota asli dan baru.

  2. Tandai enumerasi asli dengan System.ObsoleteAttribute atribut .

    Ikuti prosedur yang sama untuk setiap jenis atau anggota yang terlihat secara eksternal yang mengekspos enumerasi asli.

Cara memperbaiki pelanggaran

Untuk memperbaiki pelanggaran aturan ini, hapus atau ganti nama anggota.

Kapan harus menekan peringatan

Aman untuk menekan peringatan dari aturan ini untuk anggota yang saat ini digunakan atau untuk pustaka yang sebelumnya telah dikirim.

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 CA1700
// The code that's violating the rule is on this line.
#pragma warning restore CA1700

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

[*.{cs,vb}]
dotnet_diagnostic.CA1700.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.

Anda dapat mengonfigurasi opsi ini hanya untuk aturan ini, untuk semua aturan yang berlaku untuknya, atau untuk semua aturan dalam kategori ini (Penamaan) 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

CA2217: Jangan tandai enum dengan FlagsAttribute

CA1712: Jangan awali nilai enum dengan nama jenis

CA1028: Penyimpanan enum harus Int32

CA1008: Enum harus memiliki nilai nol

CA1027: Tandai enum dengan FlagsAttribute