Bagikan melalui

CA1008: Enum harus memiliki nilai nol

  • Artikel
Properti Nilai
ID Aturan CA1008
Judul Enum harus memiliki nilai nol
Golongan Desain
Perbaikan bersifat disruptif atau non-disruptif Tidak melanggar - Saat Anda diminta untuk menambahkan None nilai ke enumerasi non-bendera. Melanggar - Saat Anda diminta untuk mengganti nama atau menghapus nilai enumerasi apa pun.
Diaktifkan secara default di .NET 8 No

Penyebab

Enumerasi tanpa diterapkan System.FlagsAttribute tidak menentukan anggota yang memiliki nilai nol. Atau, enumerasi yang memiliki penerapan FlagsAttribute mendefinisikan anggota yang memiliki nilai nol tetapi namanya bukan 'Tidak Ada'. Atau, enumerasi menentukan beberapa anggota bernilai nol.

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

Deskripsi aturan

Nilai default enumerasi yang tidak diinisialisasi, sama seperti jenis nilai lainnya, adalah nol. Enumerasi yang tidak diatribusikan bendera harus menentukan anggota yang memiliki nilai nol sehingga nilai default adalah nilai enumerasi yang valid. Jika sesuai, beri nama anggota 'Tidak Ada' (atau salah satu nama tambahan yang diizinkan). Jika tidak, tetapkan nol ke anggota yang paling sering digunakan. Secara default, jika nilai anggota enumerasi pertama tidak diatur dalam deklarasi, nilainya adalah nol.

Jika enumerasi yang telah FlagsAttribute diterapkan menentukan anggota bernilai nol, namanya harus 'Tidak Ada' (atau salah satu nama tambahan yang diizinkan) untuk menunjukkan bahwa tidak ada nilai yang ditetapkan dalam enumerasi. Menggunakan anggota bernilai nol untuk tujuan lain bertentangan dengan penggunaan FlagsAttributeAND operator bitwise dan OR tidak berguna dengan anggota. Ini menyiratkan bahwa hanya satu anggota yang harus diberi nilai nol. Jika beberapa anggota yang memiliki nilai nol terjadi dalam enumerasi yang diatribusikan bendera, Enum.ToString() mengembalikan hasil yang salah untuk anggota yang bukan nol.

Cara memperbaiki pelanggaran

Untuk memperbaiki pelanggaran aturan ini untuk enumerasi yang tidak dikaitkan dengan bendera, tentukan anggota yang memiliki nilai nol; ini adalah perubahan yang tidak melanggar. Untuk enumerasi yang diatribusikan bendera yang menentukan anggota bernilai nol, beri nama anggota ini 'Tidak Ada' dan hapus anggota lain yang memiliki nilai nol; ini adalah perubahan yang melanggar.

Kapan harus menekan peringatan

Jangan menekan peringatan dari aturan ini kecuali untuk enumerasi yang diatribusikan bendera yang sebelumnya telah dikirimkan.

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

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

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

Nama bidang nilai nol tambahan

Di .NET 7 dan versi yang lebih baru, Anda dapat mengonfigurasi nama lain yang diizinkan untuk bidang enumerasi nilai nol, selain None. Pisahkan beberapa nama menurut | karakter. Tabel berikut ini memperlihatkan beberapa contoh.

Nilai opsi Ringkasan
dotnet_code_quality.CA1008.additional_enum_none_names = Never Mengizinkan dan NoneNever
dotnet_code_quality.CA1008.additional_enum_none_names = Never|Nothing Memungkinkan None, Never, dan Nothing

Contoh

Contoh berikut menunjukkan dua enumerasi yang memenuhi aturan dan enumerasi, BadTraceOptions, yang melanggar aturan.

using System;

namespace ca1008
{
    public enum TraceLevel
    {
        Off = 0,
        Error = 1,
        Warning = 2,
        Info = 3,
        Verbose = 4
    }

    [Flags]
    public enum TraceOptions
    {
        None = 0,
        CallStack = 0x01,
        LogicalStack = 0x02,
        DateTime = 0x04,
        Timestamp = 0x08,
    }

    [Flags]
    public enum BadTraceOptions
    {
        CallStack = 0,
        LogicalStack = 0x01,
        DateTime = 0x02,
        Timestamp = 0x04,
    }

    class UseBadTraceOptions
    {
        static void MainTrace()
        {
            // Set the flags.
            BadTraceOptions badOptions =
               BadTraceOptions.LogicalStack | BadTraceOptions.Timestamp;

            // Check whether CallStack is set.
            if ((badOptions & BadTraceOptions.CallStack) ==
                BadTraceOptions.CallStack)
            {
                // This 'if' statement is always true.
            }
        }
    }
}

Imports System

Namespace ca1008

    Public Enum TraceLevel
        Off = 0
        AnError = 1
        Warning = 2
        Info = 3
        Verbose = 4
    End Enum

    <Flags>
    Public Enum TraceOptions
        None = 0
        CallStack = &H1
        LogicalStack = &H2
        DateTime = &H4
        Timestamp = &H8
    End Enum

    <Flags>
    Public Enum BadTraceOptions
        CallStack = 0
        LogicalStack = &H1
        DateTime = &H2
        Timestamp = &H4
    End Enum

    Class UseBadTraceOptions

        Shared Sub Main1008()

            ' Set the flags.
            Dim badOptions As BadTraceOptions =
            BadTraceOptions.LogicalStack Or BadTraceOptions.Timestamp

            ' Check whether CallStack is set.
            If ((badOptions And BadTraceOptions.CallStack) =
             BadTraceOptions.CallStack) Then
                ' This 'If' statement is always true.
            End If

        End Sub

    End Class

End Namespace

Baca juga