Bagikan melalui

CA1068: Parameter CancellationToken harus menjadi yang terakhir

  • Artikel
Properti Nilai
ID Aturan CA1068
Judul Parameter CancellationToken harus menjadi yang terakhir
Golongan Desain
Perbaikan bersifat disruptif atau non-disruptif Merusak
Diaktifkan secara default di .NET 8 Sebagai saran

Penyebab

Metode memiliki CancellationToken parameter yang bukan parameter terakhir.

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

Deskripsi aturan

Metode yang melakukan operasi jangka panjang atau operasi asinkron dan dapat dibatalkan biasanya mengambil parameter token pembatalan. Setiap token pembatalan memiliki CancellationTokenSource token yang membuat token dan menggunakannya untuk komputasi yang dapat dibatalkan. Adalah praktik umum untuk memiliki rantai panggilan metode yang panjang yang meneruskan token pembatalan dari penelepon ke penelepon. Oleh karena itu, sejumlah besar metode yang mengambil bagian dalam komputasi yang dapat dibatalkan akhirnya memiliki parameter token pembatalan. Namun, token pembatalan itu sendiri biasanya tidak relevan dengan fungsionalitas inti dari sebagian besar metode ini. Ini dianggap sebagai praktik desain API yang baik untuk memiliki parameter seperti itu menjadi parameter terakhir dalam daftar.

Kasus khusus

Aturan CA1068 tidak diaktifkan dalam kasus khusus berikut:

  • Metode memiliki satu atau beberapa parameter opsional (Opsional di Visual Basic) mengikuti parameter token pembatalan non-opsional. Pengkompilasi mengharuskan semua parameter opsional didefinisikan setelah semua parameter non-opsional.
  • Metode memiliki satu atau beberapa parameter ref atau out (ByRef di Visual Basic) mengikuti parameter token pembatalan. Adalah praktik umum untuk memiliki ref parameter atau out berada di akhir daftar, karena biasanya menunjukkan nilai output untuk metode .

Cara memperbaiki pelanggaran

Ubah tanda tangan metode untuk memindahkan parameter token pembatalan ke akhir daftar. Misalnya, dua cuplikan kode berikut menunjukkan pelanggaran aturan dan cara memperbaikinya:

// Violates CA1068
public void LongRunningOperation(CancellationToken token, string usefulParameter)
{
    ...
}

// Does not violate CA1068
public void LongRunningOperation(string usefulParameter, CancellationToken token)
{
    ...
}

Kapan harus menekan peringatan

Jika metode ini adalah API publik yang terlihat secara eksternal yang sudah menjadi bagian dari pustaka yang dikirim, maka aman untuk menekan peringatan dari aturan ini untuk menghindari perubahan yang melanggar bagi konsumen pustaka.

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

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

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

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.

Lihat juga