Sdílet prostřednictvím

CA1068: Parametry CancellationToken musí být poslední

  • Článek
Vlastnost Hodnota
ID pravidla CA1068
Název Parametry CancellationToken musí být poslední.
Kategorie Návrh
Oprava způsobující chybu nebo chybu způsobující chybu Narušující
Povoleno ve výchozím nastavení v .NET 9 Jako návrh

Příčina

Metoda má CancellationToken parametr, který není posledním parametrem.

Ve výchozím nastavení toto pravidlo analyzuje celý základ kódu, ale dá se nakonfigurovat.

Popis pravidla

Metody, které provádějí dlouhotrvající operace nebo asynchronní operace a dají se zrušit, obvykle zabírají parametr tokenu zrušení. Každý token zrušení má token, CancellationTokenSource který vytvoří token a použije ho k zrušitelným výpočtům. Je běžné mít dlouhý řetězec volání metody, které předávají token zrušení volajícím do volaných. Proto velký počet metod, které se účastní zrušení výpočetních prostředků, skončí mít parametr tokenu zrušení. Samotný token zrušení však není obvykle relevantní pro základní funkce většiny těchto metod. Považuje se za dobrý postup návrhu rozhraní API, aby tyto parametry byly posledním parametrem v seznamu.

Zvláštní případy

Pravidlo CA1068 se neaktivuje v následujících zvláštních případech:

  • Metoda má jeden nebo více volitelných parametrů (volitelné v jazyce Visual Basic) za parametrem ne volitelného tokenu zrušení. Kompilátor vyžaduje, aby všechny volitelné parametry byly definovány po všech nepovinných parametrech.
  • Metoda má jeden nebo více parametrů ref nebo out (ByRef v jazyce Visual Basic) za parametrem tokenu zrušení. Je běžné mít ref nebo out parametry být na konci seznamu, protože obvykle označují výstupní hodnoty pro metodu.

Jak opravit porušení

Změňte podpis metody tak, aby se parametr tokenu zrušení přesunul na konec seznamu. Například následující dva fragmenty kódu ukazují porušení pravidla a postup jeho opravy:

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

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

Kdy potlačit upozornění

Pokud je metoda externě viditelným veřejným rozhraním API, které je již součástí dodané knihovny, je bezpečné potlačit upozornění z tohoto pravidla, aby se zabránilo zásadní změně pro uživatele knihovny.

Potlačení upozornění

Pokud chcete pouze potlačit jedno porušení, přidejte do zdrojového souboru direktivy preprocesoru, abyste pravidlo zakázali a znovu povolili.

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

Pokud chcete pravidlo pro soubor, složku nebo projekt zakázat, nastavte jeho závažnost v none konfiguračním souboru.

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

Další informace naleznete v tématu Jak potlačit upozornění analýzy kódu.

Konfigurace kódu pro analýzu

Pomocí následujících možností můžete nakonfigurovat, pro které části základu kódu se má toto pravidlo spouštět.

Tyto možnosti můžete nakonfigurovat jenom pro toto pravidlo, pro všechna pravidla, která platí pro, nebo pro všechna pravidla v této kategorii (Návrh), na která se vztahují. Další informace naleznete v tématu Možnosti konfigurace pravidla kvality kódu.

Zahrnutí konkrétních povrchů rozhraní API

Nastavením možnosti api_surface můžete nakonfigurovat, na kterých částech základu kódu se má toto pravidlo spouštět na základě jejich přístupnosti. Pokud chcete například určit, že pravidlo by se mělo spouštět jenom na neveřejné ploše rozhraní API, přidejte do souboru .editorconfig v projektu následující pár klíč-hodnota:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Poznámka

Nahraďte XXXX část CAXXXX ID příslušného pravidla.

Vyloučení konkrétních symbolů

Z analýzy můžete vyloučit konkrétní symboly, jako jsou typy a metody, nastavením možnosti excluded_symbol_names. Pokud chcete například určit, že pravidlo by se nemělo spouštět u žádného kódu v rámci pojmenovaných MyTypetypů, přidejte do souboru .editorconfig v projektu následující dvojici klíč-hodnota:

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

Poznámka

Nahraďte XXXX část CAXXXX ID příslušného pravidla.

Povolené formáty názvů symbolů v hodnotě možnosti (oddělené ):|

  • Pouze název symbolu (zahrnuje všechny symboly s názvem bez ohledu na typ nebo obor názvů).
  • Plně kvalifikované názvy ve formátu ID dokumentace symbolu. Každý název symbolu vyžaduje předponu typu symbolu, například M: pro metody, T: typy a N: obory názvů.
  • .ctor pro konstruktory a .cctor statické konstruktory.

Příklady:

Hodnota možnosti Shrnutí
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType Odpovídá všem symbolům s názvem MyType.
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1|MyType2 Porovná všechny symboly pojmenované buď MyType1 nebo MyType2.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType) Odpovídá konkrétní metodě MyMethod se zadaným plně kvalifikovaným podpisem.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType) Odpovídá konkrétním metodám MyMethod1 a MyMethod2 příslušným plně kvalifikovaným podpisům.

Vyloučení konkrétních typů a jejich odvozených typů

Konkrétní typy a jejich odvozené typy můžete vyloučit z analýzy nastavením možnosti excluded_type_names_with_derived_types. Pokud chcete například určit, že pravidlo by se nemělo spouštět u žádné metody v rámci pojmenovaných MyType typů a jejich odvozených typů, přidejte do souboru .editorconfig v projektu následující dvojici klíč-hodnota:

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

Poznámka

Nahraďte XXXX část CAXXXX ID příslušného pravidla.

Povolené formáty názvů symbolů v hodnotě možnosti (oddělené ):|

  • Pouze název typu (zahrnuje všechny typy s názvem bez ohledu na typ nebo obor názvů).
  • Plně kvalifikované názvy ve formátu ID dokumentace symbolu s volitelnou T: předponou.

Příklady:

Hodnota možnosti Shrnutí
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType Odpovídá všem pojmenovaným MyType typům a všem jejich odvozeným typům.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1|MyType2 Odpovídá všem typům pojmenovaným buď MyType1 nebo MyType2 a všem jejich odvozeným typům.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType Odpovídá určitému typu MyType s daným plně kvalifikovaným názvem a všemi jeho odvozenými typy.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1|M:NS2.MyType2 Odpovídá konkrétním typům MyType1 a MyType2 příslušným plně kvalifikovaným názvům a všem jejich odvozeným typům.

Viz také