CA1303: Jangan teruskan harfiah sebagai parameter yang dilokalkan

Artikel
04/02/2025

Properti	Nilai
ID Aturan	CA1303
Judul	Jangan meneruskan harfiah sebagai parameter yang dilokalkan
Golongan	Globalisasi
Perbaikan bersifat disruptif atau non-disruptif	Non-disruptif
Diaktifkan secara default di .NET 9	No

Penyebab

Metode meneruskan string literal sebagai parameter ke konstruktor atau metode .NET dan string tersebut harus dapat dilokalkan.

Peringatan ini dimunculkan ketika string harfiah diteruskan sebagai nilai ke parameter atau properti dan satu atau beberapa situasi berikut ini benar:

Atribut LocalizableAttribute parameter atau properti diatur ke true.
String harfiah diteruskan ke string value parameter atau string format dari Console.Write metode atau Console.WriteLine kelebihan beban.
Aturan CA1303 dikonfigurasi untuk menggunakan heuristik penamaan, dan parameter atau nama properti berisi frasa Text, , Messageatau Caption.

Secara default, aturan ini menganalisis seluruh codebase, tetapi ini dapat dikonfigurasi.

Deskripsi aturan

Literal string yang disematkan dalam kode sumber sulit untuk dilokalkan.

Cara memperbaiki pelanggaran

Untuk memperbaiki pelanggaran aturan ini, ganti string literal dengan string yang diambil melalui instans ResourceManager kelas.

Untuk metode yang tidak memerlukan string yang dilokalkan, Anda dapat menghilangkan peringatan CA1303 yang tidak perlu dengan cara berikut:

Jika opsi heuristik penamaan diaktifkan, ganti nama parameter atau properti.
LocalizableAttribute Hapus atribut pada parameter atau properti, atau atur ke false ([Localizable(false)]).

Kapan harus menekan peringatan

Aman untuk menekan peringatan dari aturan ini jika salah satu pernyataan berikut berlaku:

Pustaka kode tidak akan dilokalkan.
String tidak diekspos ke pengguna akhir atau pengembang menggunakan pustaka kode.

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

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

ini

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

Mengecualikan simbol tertentu
Mengecualikan jenis tertentu dan jenis turunannya
Gunakan heuristik penamaan

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

Anda dapat mengonfigurasi opsi ini hanya untuk aturan ini, untuk semua aturan yang berlaku, 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 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:

ini

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

ini

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

Gunakan heuristik penamaan

Anda dapat mengonfigurasi apakah parameter atau nama properti yang berisi Text, Message, atau Caption akan memicu aturan ini.

ini

dotnet_code_quality.CA1303.use_naming_heuristic = true

Contoh

Contoh berikut menunjukkan metode yang menulis ke konsol ketika salah satu dari dua argumennya berada di luar rentang. hour Untuk pemeriksaan argumen, string harfiah diteruskan ke Console.WriteLine, yang melanggar aturan ini. minute Untuk pemeriksaan argumen, string yang diambil melalui ResourceManager diteruskan ke Console.WriteLine, yang memenuhi aturan.

<Assembly: System.Resources.NeutralResourcesLanguageAttribute("en-US")>
Namespace GlobalizationLibrary

    Public Class DoNotPassLiterals

        Dim stringManager As System.Resources.ResourceManager

        Sub New()
            stringManager = New System.Resources.ResourceManager(
                "en-US", System.Reflection.Assembly.GetExecutingAssembly())
        End Sub

        Sub TimeMethod(hour As Integer, minute As Integer)

            If (hour < 0 Or hour > 23) Then
                'CA1303 fires because a literal string
                'is passed as the 'value' parameter.
                Console.WriteLine("The valid range is 0 - 23.")
            End If

            If (minute < 0 Or minute > 59) Then
                Console.WriteLine(
                    stringManager.GetString("minuteOutOfRangeMessage",
                        System.Globalization.CultureInfo.CurrentUICulture))
            End If

        End Sub

    End Class

End Namespace

public class DoNotPassLiterals
{
    ResourceManager stringManager;
    public DoNotPassLiterals()
    {
        stringManager = new ResourceManager("en-US", Assembly.GetExecutingAssembly());
    }

    public void TimeMethod(int hour, int minute)
    {
        if (hour < 0 || hour > 23)
        {
            // CA1303 fires because a literal string
            // is passed as the 'value' parameter.
            Console.WriteLine("The valid range is 0 - 23.");
        }

        if (minute < 0 || minute > 59)
        {
            Console.WriteLine(stringManager.GetString(
            "minuteOutOfRangeMessage", CultureInfo.CurrentUICulture));
        }
    }
}

Bagikan melalui