CA1068: A CancellationToken paramétereknek az utolsónak kell lenniük
Tulajdonság | Érték |
---|---|
Szabályazonosító | CA1068 |
Cím | A CancellationToken paramétereknek az utolsónak kell lenniük |
Kategória | Tervez |
A javítás kompatibilitástörő vagy nem törik | Törés |
Alapértelmezés szerint engedélyezve a .NET 9-ben | Javaslatként |
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ó.
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.
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 aout
lista végén vannak, mert általában a metódus kimeneti értékeit jelzik.
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)
{
...
}
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.
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.
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.
- Adott API-felületek belefoglalása
- Adott szimbólumok kizárása
- Adott típusok és származtatott típusok kizárása
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.
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
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 MyType
tí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 ésN:
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 MyType szimbó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. |
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. |
.NET-visszajelzés
A(z) .NET egy nyílt forráskód projekt. Visszajelzés adásához válasszon egy hivatkozást: