Share via

CA1068: A CancellationToken paramétereknek az utolsónak kell lenniük

  • Cikk
Tulajdonság Érték
Szabályazonosító CA1068
Cím A CancellationToken paramétereknek az utolsónak kell lenniük
Kategória Design
A javítás kompatibilitástörő vagy nem törik Törés
Alapértelmezés szerint engedélyezve a .NET 8-ban Javaslatként

Ok

A metódus olyan paraméterrel CancellationToken rendelkezik, amely nem az utolsó paraméter.

Ez a szabály alapértelmezés szerint a teljes kódbázist elemzi, de ez konfigurálható.

Szabály leírása

Azok a metódusok, amelyek hosszú ideig futó műveleteket vagy aszinkron műveleteket hajtanak végre, és amelyek megszakíthatók, általában a lemondási jogkivonat paraméterét veszik igénybe. Minden lemondási jogkivonat rendelkezik egy CancellationTokenSource olyan jogkivonattal, amely létrehozza a jogkivonatot, és visszavonható számításokhoz használja. Gyakori gyakorlat, hogy a metódushívások hosszú lánca áthalad a lemondási jogkivonaton a hívóktól a hívókig. Ezért számos olyan metódus, amely részt vesz egy lemondható számításban, a végén egy lemondási jogkivonat paramétere lesz. A lemondási jogkivonat azonban általában nem releváns ezen módszerek többségének alapvető funkciói szempontjából. Jó API-tervezési gyakorlatnak számít, hogy az ilyen paraméterek a lista utolsó paramétere.

Különleges esetek

A CA1068 szabály nem aktiválódik a következő különleges esetekben:

  • A metódus egy vagy több választható paraméterrel rendelkezik (a Visual Basicben nem kötelező) egy nem választható lemondási jogkivonat-paramétert követve. A fordítóhoz az összes választható paramétert meg kell határoznia az összes nem választható paraméter után.
  • A metódus egy vagy több ref vagy out paraméterrel rendelkezik (ByRef a Visual Basicben) a lemondási jogkivonat paraméterét követve. Gyakori eljárás, hogy ref a paraméterek a out lista végén vannak, mert általában a metódus kimeneti értékeit jelzik.

Szabálysértések kijavítása

Módosítsa a metódus-aláírást a lemondási jogkivonat paraméterének a lista végére való áthelyezéséhez. A következő két kódrészlet például a szabály megsértését és a hiba elhárítását mutatja be:

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

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

Mikor kell letiltani a figyelmeztetéseket?

Ha a metódus egy külsőleg látható nyilvános API, amely már része egy szállított kódtárnak, akkor nyugodtan letilthatja a szabály figyelmeztetését, hogy elkerülje a kódtár felhasználóinak kompatibilitástörő változását.

Figyelmeztetés mellőzése

Ha csak egyetlen szabálysértést szeretne letiltani, adjon hozzá előfeldolgozási irányelveket a forrásfájlhoz a szabály letiltásához és újbóli engedélyezéséhez.

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

Ha le szeretné tiltani egy fájl, mappa vagy projekt szabályát, állítsa annak súlyosságát none a konfigurációs fájlban.

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

További információ: Kódelemzési figyelmeztetések letiltása.

Kód konfigurálása elemzéshez

A következő beállítások segítségével konfigurálhatja, hogy a kódbázis mely részein futtassa ezt a szabályt.

Ezeket a beállításokat konfigurálhatja csak erre a szabályra, az összes szabályra, vagy az ebben a kategóriában (Tervezés) érvényes összes szabályra. További információ: Kódminőségi szabály konfigurációs beállításai.

Adott API-felületek belefoglalása

A kódbázis azon részeit konfigurálhatja, amelyeken futtathatja ezt a szabályt az akadálymentességük alapján. Ha például meg szeretné adni, hogy a szabály csak a nem nyilvános API-felületen fusson, adja hozzá a következő kulcs-érték párot a projekt egyik .editorconfig fájljához:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Adott szimbólumok kizárása

Bizonyos szimbólumokat, például típusokat és metódusokat kizárhat az elemzésből. Ha például meg szeretné adni, hogy a szabály ne fusson a nevesített MyTypetípusok egyikén sem, adja hozzá a következő kulcs-érték párot a projekt egyik .editorconfig fájljához:

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

Engedélyezett szimbólumnévformátumok a beállításértékben (a következővel |elválasztva):

  • Csak szimbólumnév (a névvel ellátott összes szimbólumot tartalmazza, függetlenül attól, hogy milyen típusú vagy névtérrel rendelkezik).
  • A szimbólum dokumentációazonosító-formátumában szereplő teljes nevek. Minden szimbólumnévhez szimbólum típusú előtag szükséges, például M: metódusokhoz, T: típusokhoz és N: névterekhez.
  • .ctor konstruktorok és .cctor statikus konstruktorok számára.

Példák:

Beállítás értéke Összegzés
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType Megegyezik az összes elnevezett MyTypeszimbólummal.
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1|MyType2 Megegyezik az összes elnevezett MyType1 szimbólummal vagy MyType2.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType) Megfelel a megadott metódusnak MyMethod a megadott teljes jogosultsággal rendelkező aláírással.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType) Egyezik az adott metódusokkal MyMethod1 és MyMethod2 a megfelelő, teljes mértékben minősített aláírásokkal.

Adott típusok és származtatott típusok kizárása

Bizonyos típusokat és azok származtatott típusait kizárhatja az elemzésből. Ha például meg szeretné adni, hogy a szabály ne fusson a nevesített MyType és származtatott típusok egyik metódusán sem, adja hozzá a következő kulcs-érték párot a projekt egyik .editorconfig fájljához:

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

Engedélyezett szimbólumnévformátumok a beállításértékben (a következővel |elválasztva):

  • Csak típusnév (a névvel rendelkező összes típust tartalmazza, függetlenül attól, hogy milyen típust vagy névteret tartalmaz).
  • A szimbólum dokumentációazonosító-formátumában szereplő teljes nevek opcionális T: előtaggal.

Példák:

Beállítás értéke Összegzés
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType Megfelel az összes névvel ellátott MyType típusnak és az összes származtatott típusnak.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1|MyType2 Megfelel az összes névvel ellátott MyType1 típusnak, vagy MyType2 az összes származtatott típusnak.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType Egyezik MyType a megadott teljes névvel és az összes származtatott típusával.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1|M:NS2.MyType2 Egyezik az adott típusokkal MyType1 és MyType2 a megfelelő teljes névvel, valamint az összes származtatott típussal.

Lásd még