CA1068: CancellationToken parametreleri en son gelmelidir

Özellik Değer
Kural Kimliği CA1068
Başlık CancellationToken parametreleri en sonda olmalıdır
Kategori Tasarım
Düzeltme bozucu ya da bozmayan olabilir Son Dakika
.NET 10'da varsayılan olarak etkin Öneri olarak
Geçerli diller C# ve Visual Basic

Neden

Yöntemin, son parametre olmayan bir CancellationToken parametresi vardır.

Varsayılan olarak, bu kural tüm kod tabanını analiz eder, ancak bu yapılandırılabilir.

Kural açıklaması

Uzun süre çalışan işlemler veya zaman uyumsuz işlemler gerçekleştiren ve normalde iptal edilebilen yöntemler bir iptal belirteci parametresi alır. Her iptal belirtecinin, belirtecin oluşturulmasını sağlayan ve iptal edilebilir hesaplamalarda kullanılan bir CancellationTokenSource vardır. Çağıranlardan çağrılanlara iptal belirtecini aktaran uzun bir yöntem çağrıları zincirine sahip olmak yaygın bir uygulamadır. Bu nedenle, iptal edilebilir bir hesaplamada yer alan çok sayıda yöntem, bir iptal belirteci parametresine sahip olur. Ancak iptal belirtecinin kendisi genellikle bu yöntemlerin çoğunluğunun temel işlevselliğiyle ilgili değildir. Bu tür parametrelerin listedeki son parametre olması iyi bir API tasarım uygulaması olarak kabul edilir.

Özel durumlar

CA1068 kuralı aşağıdaki özel durumlarda etkinleştirilmez:

  • Yöntem, isteğe bağlı olmayan bir iptal belirteci parametresinin ardından bir veya daha fazla isteğe bağlı parametre (Visual Basic'te İsteğe Bağlı) içerir. Derleyici, isteğe bağlı olmayan tüm parametrelerden sonra tüm isteğe bağlı parametrelerin tanımlanmasını gerektirir.
  • Yöntem, bir iptal belirteci parametresini izleyen bir veya daha fazla ref veya out parametresine (Visual Basic'te ByRef) sahiptir. Genellikle yöntemin ref çıkış değerlerini gösterdiğinden veya out parametrelerinin listenin sonunda olması yaygın bir uygulamadır.

İhlalleri düzeltme

İptal belirteci parametresini listenin sonuna taşımak için yöntem imzasını değiştirin. Örneğin, aşağıdaki iki kod parçacığı kuralın ihlalini ve nasıl düzeltileceğini gösterir:

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

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

Uyarıların ne zaman bastırılması gerekiyor?

Eğer yöntem, halihazırda yayımlanmış bir kütüphanenin parçası olan dışarıdan görünür bir public API ise, kütüphane kullanıcıları için geri uyumsuzluğa yol açan bir değişikliği önlemek amacıyla bu kuraldan gelen bir uyarıyı bastırmak güvenlidir.

Uyarıyı gizleme

Yalnızca tek bir ihlali engellemek istiyorsanız, kuralı devre dışı bırakmak ve sonra yeniden etkinleştirmek için kaynak dosyanıza ön işlemci yönergeleri ekleyin.

#pragma warning disable CA1068
// The code that's violating the rule is on this line.
#pragma warning restore CA1068

Bir dosya, klasör veya projenin kuralını devre dışı bırakmak için, yapılandırma dosyasındaki önem derecesini noneolarak ayarlayın.

[*.{cs,vb}]
dotnet_diagnostic.CA1068.severity = none

Daha fazla bilgi için bkz . Kod analizi uyarılarını gizleme.

Kod çözümleme için konfigüre et

Bu kuralın kod tabanınızın hangi bölümlerinde çalıştırılacaklarını yapılandırmak için aşağıdaki seçenekleri kullanın.

Bu seçenekleri yalnızca bu kural için, uyguladıkları tüm kurallar için veya bu kategorideki tüm kurallar için (Tasarım) yapılandırabilirsiniz. Daha fazla bilgi için bkz . Kod kalitesi kuralı yapılandırma seçenekleri.

Belirli API yüzeylerini ekleme

api_surface seçeneğini ayarlayarak, bu kuralın erişilebilirliği temelinde kod tabanınızın hangi bölümlerinde çalıştırılacaklarını yapılandırabilirsiniz. Örneğin, kuralın yalnızca genel olmayan API yüzeyinde çalıştırılması gerektiğini belirtmek için projenizdeki bir .editorconfig dosyasına aşağıdaki anahtar-değer çiftini ekleyin:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Not

XXXX CAXXXX bölümünü geçerli kuralın kimliğiyle değiştirin.

Belirli simgeleri hariç tutma

excluded_symbol_names seçeneğini ayarlayarak türler ve yöntemler gibi belirli simgeleri analizden hariç tutabilirsiniz. Örneğin, kuralın adlı MyTypetürlerdeki herhangi bir kodda çalışmaması gerektiğini belirtmek için, projenizdeki bir .editorconfig dosyasına aşağıdaki anahtar-değer çiftini ekleyin:

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

Not

XXXX CAXXXX bölümünü geçerli kuralın kimliğiyle değiştirin.

Seçenek değerinde izin verilen simge adı biçimleri (ile |ayrılmış):

  • Yalnızca sembol adı (içerildiği tür veya ad alanından bağımsız olarak ada sahip tüm simgeleri içerir).
  • Simgelerin dökümantasyon kimliği formatındaki tam adlar. Her sembol adı için, yöntemler için M:, türler için T:, ve ad alanları için N: gibi bir sembol türü ön eki gerekir.
  • .ctor oluşturucular ve .cctor statik oluşturucular için.

Örnekler:

Seçenek Değeri Özet
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType adlı MyTypetüm simgelerle eşleşir.
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1|MyType2 MyType1 veya MyType2 adlı tüm simgelerle eşleşir.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType) Belirtilen tam imza ile belirli bir yöntemi MyMethod eşleştirir.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType) Belirli yöntemlerle MyMethod1 ve MyMethod2 ilgili tam imzalarla eşleşir.

Belirli türleri ve türetilmiş türlerini dışlama

excluded_type_names_with_derived_types seçeneğini ayarlayarak belirli türleri ve türetilmiş türlerini analizden dışlayabilirsiniz. Örneğin, kuralın adlı MyType ve türetilmiş türleri içindeki hiçbir yöntemde çalışmaması gerektiğini belirtmek için, projenizdeki bir .editorconfig dosyasına aşağıdaki anahtar-değer çiftini ekleyin:

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

Not

XXXX CAXXXX bölümünü geçerli kuralın kimliğiyle değiştirin.

Seçenek değerinde izin verilen simge adı biçimleri (ile |ayrılmış):

  • Yalnızca tür adı (içeren tür veya ad alanına bakılmaksızın adı olan tüm türleri içerir).
  • Simgenin belge kimliği biçiminde, isteğe bağlı T: ön ek içeren tam adlar.

Örnekler:

Seçenek değeri Özet
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType Adı MyType olan tüm türleri ve türevlerini eşleştirir.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1|MyType2 MyType1 veya MyType2 adlı tüm türleri ve bunların türetilmiş türlerinin tamamını eşleştirir.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType Belirli bir türü MyType verilen tam adla ve türetilmiş tüm türleriyle eşleştirir.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1|M:NS2.MyType2 Belirli türler MyType1 ve MyType2 ile bunların türetilmiş tüm türleri, ilgili tam adlarla eşleşir.

Ayrıca bkz.

  • Last updated on