Bagikan melalui

CA1305: Tentukan IFormatProvider

  • Artikel
Properti Nilai
ID Aturan CA1305
Judul Tentukan IFormatProvider
Golongan Globalisasi
Perbaikan bersifat disruptif atau non-disruptif Non-disruptif
Diaktifkan secara default di .NET 8 No

Penyebab

Panggilan dilakukan ke metode yang memiliki kelebihan beban yang menerima System.IFormatProvider argumen, dan kelebihan beban tersebut tidak dipanggil.

Aturan ini mengabaikan panggilan ke metode .NET yang terdokumentasi sebagai mengabaikan parameter IFormatProvider. Aturan ini juga mengabaikan metode berikut:

Deskripsi aturan

System.Globalization.CultureInfo Ketika objek atau IFormatProvider tidak disediakan, nilai default yang disediakan oleh anggota yang kelebihan beban mungkin tidak memiliki efek yang Anda inginkan di semua lokal. Selain itu, anggota .NET memilih kultur dan pemformatan default berdasarkan asumsi yang mungkin tidak benar untuk kode Anda. Untuk memastikan bahwa kode berfungsi seperti yang diharapkan untuk skenario Anda, Anda harus menyediakan informasi khusus kultur sesuai dengan panduan berikut:

  • Jika nilai akan ditampilkan kepada pengguna, gunakan kultur saat ini. Lihat CultureInfo.CurrentCulture.

  • Jika nilai akan disimpan dan diakses oleh perangkat lunak (dipertahankan ke file atau database), gunakan kultur invarian. Lihat CultureInfo.InvariantCulture.

  • Jika Anda tidak mengetahui tujuan nilai, minta konsumen atau penyedia data menentukan budaya.

Bahkan jika perilaku default anggota yang kelebihan beban sesuai dengan kebutuhan Anda, lebih baik secara eksplisit memanggil kelebihan beban khusus budaya sehingga kode Anda mendokumentasikan sendiri dan lebih mudah dipertahankan.

Cara memperbaiki pelanggaran

Untuk memperbaiki aturan ini, gunakan overload yang mengambil argumen IFormatProvider. Atau, untuk menggunakan budaya invarian, gunakan string terinterpolasi C# dan teruskan ke String.Create(IFormatProvider, DefaultInterpolatedStringHandler) bersama dengan CultureInfo.InvariantCulture, misalnya:

string.Create(CultureInfo.InvariantCulture, $"{major}.{minor}.{build}.{revision}");

Kapan harus menekan peringatan

Aman untuk menyembunyikan peringatan dari aturan ini ketika dipastikan bahwa format default adalah pilihan yang benar, dan di mana pemeliharaan kode bukanlah prioritas pengembangan penting.

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

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

[*.{cs,vb}]
dotnet_diagnostic.CA1305.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 (Globalisasi) yang diterapkannya. Untuk informasi selengkapnya, lihat Opsi konfigurasi aturan kualitas kode.

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.

Contoh

Pada kode berikut, string example1 melanggar aturan CA1305. String example2 mematuhi aturan CA1305 dengan meneruskan CultureInfo.CurrentCulture, yang mengimplementasikan IFormatProvider, ke String.Format(IFormatProvider, String, Object). String example3 memenuhi aturan CA1305 dengan meneruskan string terinterpolasi bersama String.Create(IFormatProvider, DefaultInterpolatedStringHandler) dengan CultureInfo.InvariantCulture.

string name = "Georgette";

// Violates CA1305
string example1 = string.Format("Hello {0}", name);

// Satisfies CA1305
string example2 = string.Format(CultureInfo.CurrentCulture, "Hello {0}", name);

// Satisfies CA1305
string example3 = string.Create(CultureInfo.InvariantCulture, $"Hello {name}");

Lihat juga