Bagikan melalui

CA1027: Tandai enum dengan FlagsAttribute

  • Artikel
Properti Nilai
ID Aturan CA1027
Judul Tandai enum dengan FlagsAttribute
Golongan Desain
Perbaikan bersifat disruptif atau non-disruptif Non-disruptif
Diaktifkan secara default di .NET 8 Tidak

Penyebab

Nilai enumerasi adalah kekuatan dua atau merupakan kombinasi dari nilai lain yang ditentukan dalam enumerasi, dan System.FlagsAttribute atribut tidak ada. Untuk mengurangi positif palsu, aturan ini tidak melaporkan pelanggaran untuk enumerasi yang memiliki nilai yang berdekatan.

Secara default, aturan ini hanya melihat enumerasi yang terlihat secara eksternal, tetapi ini dapat dikonfigurasi.

Deskripsi aturan

Enumerasi adalah jenis nilai yang menentukan sekumpulan konstanta bernama terkait. Terapkan FlagsAttribute ke enumerasi ketika konstanta bernama dapat digabungkan secara bermakna. Misalnya, pertimbangkan enumerasi hari dalam seminggu dalam aplikasi yang melacak sumber daya hari mana yang tersedia. Jika ketersediaan setiap sumber daya dikodekan dengan menggunakan enumerasi yang ada FlagsAttribute , kombinasi hari apa pun dapat diwakili. Tanpa atribut , hanya satu hari dalam seminggu yang dapat diwakili.

Untuk bidang yang menyimpan enumerasi yang dapat dikombinasikan, nilai enumerasi individu diperlakukan sebagai grup bit di bidang . Oleh karena itu, bidang seperti itu kadang-kadang disebut sebagai bidang bit. Untuk menggabungkan nilai enumerasi untuk penyimpanan di bidang bit, gunakan operator bersyarat Boolean. Untuk menguji bidang bit untuk menentukan apakah nilai enumerasi tertentu ada, gunakan operator logis Boolean. Agar bidang bit menyimpan dan mengambil nilai enumerasi gabungan dengan benar, setiap nilai yang ditentukan dalam enumerasi harus berupa kekuatan dua. Kecuali demikian, operator logis Boolean tidak akan dapat mengekstrak nilai enumerasi individu yang disimpan di bidang .

Cara memperbaiki pelanggaran

Untuk memperbaiki pelanggaran aturan ini, tambahkan FlagsAttribute ke enumerasi.

Kapan harus menekan peringatan

Tekan peringatan dari aturan ini jika Anda tidak ingin nilai enumerasi dapat dikombinasikan.

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

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

[*.{cs,vb}]
dotnet_diagnostic.CA1027.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 (Desain) yang berlaku untuk aturan ini. 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

Contoh

Dalam contoh berikut, DaysEnumNeedsFlags adalah enumerasi yang memenuhi persyaratan untuk digunakan FlagsAttribute tetapi tidak memilikinya. Enumerasi ColorEnumShouldNotHaveFlag tidak memiliki nilai yang merupakan kekuatan dari dua tetapi salah menentukan FlagsAttribute. Ini melanggar aturan CA2217: Jangan menandai enum dengan FlagsAttribute.

// Violates rule: MarkEnumsWithFlags.
public enum DaysEnumNeedsFlags
{
    None = 0,
    Monday = 1,
    Tuesday = 2,
    Wednesday = 4,
    Thursday = 8,
    Friday = 16,
    All = Monday | Tuesday | Wednesday | Thursday | Friday
}

// Violates rule: DoNotMarkEnumsWithFlags.
[FlagsAttribute]
public enum ColorEnumShouldNotHaveFlag
{
    None = 0,
    Red = 1,
    Orange = 3,
    Yellow = 4
}

Baca juga