CA1068: De parameters CancellationToken moeten als laatste komen

Eigenschap Waarde
Regel-id CA1068
Titel De parameters CancellationToken moeten als laatste komen
Categorie Ontwerpen
Fix kan brekend of niet-brekend zijn Onderbreking
Standaard ingeschakeld in .NET 10 Als suggestie
Toepasselijke talen C# en Visual Basic

Oorzaak

Een methode heeft een CancellationToken parameter die niet de laatste parameter is.

Deze regel analyseert standaard de hele codebasis, maar dit kan worden geconfigureerd.

Beschrijving van regel

Methoden die langlopende bewerkingen of asynchrone bewerkingen uitvoeren en die normaal gesproken kunnen worden geannuleerd, hebben een parameter voor het annuleren van tokens. Elk annuleringstoken heeft een mechanisme CancellationTokenSource dat het token aanmaakt en gebruikt voor annuleerbare berekeningen. Het is gebruikelijk om een lange keten van methodeaanroepen te hebben die het cancellationtoken doorgeven van de oproepers aan de opgeroepenen. Daarom hebben een groot aantal methoden die deelnemen aan een geannuleerde berekening uiteindelijk een annuleringstokenparameter. Het annuleringstoken zelf is echter niet relevant voor de kernfunctionaliteit van een meerderheid van deze methoden. Het wordt beschouwd als een goede API-ontwerpmethode om dergelijke parameters de laatste parameter in de lijst te laten zijn.

Speciale gevallen

Regel CA1068 wordt niet geactiveerd in de volgende speciale gevallen:

  • De methode heeft een of meer optionele parameters (optioneel in Visual Basic) na een niet-optionele annuleringstokenparameter. De compiler vereist dat alle optionele parameters worden gedefinieerd na alle niet-optionele parameters.
  • De methode heeft een of meer ref- of out-parameters (ByRef in Visual Basic) na een annuleringstokenparameter. Het is gebruikelijk om de parameters ref of out aan het einde van de lijst te plaatsen, omdat ze meestal uitvoerwaarden voor de methode aangeven.

Hoe schendingen op te lossen

Wijzig de methodehandtekening om de parameter voor het annuleringstoken naar het einde van de lijst te verplaatsen. In de volgende twee codefragmenten ziet u bijvoorbeeld een schending van de regel en hoe u deze kunt oplossen:

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

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

Wanneer waarschuwingen onderdrukken

Als de methode een extern zichtbare openbare API is die al deel uitmaakt van een verzonden bibliotheek, is het veilig om een waarschuwing van deze regel te onderdrukken om een onderbreking voor de gebruikers van de bibliotheek te voorkomen.

Een waarschuwing onderdrukken

Als u slechts één schending wilt onderdrukken, voegt u preprocessorrichtlijnen toe aan uw bronbestand om de regel uit te schakelen en vervolgens opnieuw in te schakelen.

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

Als u de regel voor een bestand, map of project wilt uitschakelen, stelt u de ernst none ervan in op het configuratiebestand.

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

Zie voor meer informatie Hoe codeanalysewaarschuwingen te onderdrukken.

Code configureren om te analyseren

Gebruik de volgende opties om te configureren op welke onderdelen van uw codebase deze regel moet worden uitgevoerd.

U kunt deze opties configureren voor alleen deze regel, voor alle regels waarop ze van toepassing zijn, of voor alle regels in deze categorie (Ontwerp) waarop ze van toepassing zijn. Zie de configuratieopties voor de codekwaliteitsregel voor meer informatie.

Specifieke API-oppervlakken opnemen

U kunt configureren op welke onderdelen van uw codebase deze regel moet worden uitgevoerd, op basis van hun toegankelijkheid, door de optie api_surface in te stellen. Als u bijvoorbeeld wilt opgeven dat de regel alleen moet worden uitgevoerd op het niet-openbare API-oppervlak, voegt u het volgende sleutel-waardepaar toe aan een .editorconfig-bestand in uw project:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Notitie

Vervang het XXXX deel van CAXXXX door de id van de toepasselijke regel.

Specifieke symbolen uitsluiten

U kunt specifieke symbolen, zoals typen en methoden, uitsluiten van analyse door de optie excluded_symbol_names in te stellen. Als u bijvoorbeeld wilt opgeven dat de regel niet mag worden uitgevoerd op code binnen benoemde MyTypetypen, voegt u het volgende sleutel-waardepaar toe aan een .editorconfig-bestand in uw project:

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

Notitie

Vervang het XXXX deel van CAXXXX door de id van de toepasselijke regel.

Toegestane formaten voor symboolnamen in de optiewaarde (gescheiden door |):

  • Alleen symboolnaam (inclusief alle symbolen met de naam, ongeacht het type of de naamruimte).
  • Volledig gekwalificeerde namen in de documentatie-ID-indeling van het symbool. Voor elke symboolnaam is een voorvoegsel van het type symbool vereist, zoals M: voor methoden, T: voor typen en N: voor naamruimten.
  • .ctor voor constructors en .cctor voor statische constructors.

Voorbeelden:

Optiewaarde Samenvatting
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType Komt overeen met alle symbolen met de naam MyType.
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1|MyType2 Komt overeen met alle symbolen met de naam MyType1 of MyType2.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType) Komt overeen met een specifieke methode MyMethod met de opgegeven volledig gekwalificeerde handtekening.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType) Komt overeen met specifieke methoden MyMethod1 en MyMethod2 met de respectieve volledig gekwalificeerde handtekeningen.

Specifieke typen en hun afgeleide typen uitsluiten

U kunt specifieke typen en hun afgeleide typen uitsluiten van analyse door de optie excluded_type_names_with_derived_types in te stellen. Als u bijvoorbeeld wilt opgeven dat de regel niet mag worden uitgevoerd op methoden binnen benoemde MyType typen en de afgeleide typen, voegt u het volgende sleutel-waardepaar toe aan een .editorconfig-bestand in uw project:

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

Notitie

Vervang het XXXX deel van CAXXXX door de id van de toepasselijke regel.

Toegestane formaten van symboolnamen in de optiewaarde (gescheiden door |):

  • Alleen de naam van het type (bevat alle typen met de naam, ongeacht het type of de naamruimte).
  • Volledig gekwalificeerde namen in de indeling van de documentatie-ID van het symbool, met een optioneel voorvoegsel.

Voorbeelden:

Optiewaarde Samenvatting
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType Komt overeen met alle typen met de naam MyType en alle afgeleide typen.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1|MyType2 Komt overeen met alle typen met de naam MyType1 of MyType2 en alle afgeleide typen.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType Komt overeen met een specifiek type MyType met een volledig gekwalificeerde naam en alle afgeleide typen.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1|M:NS2.MyType2 Komt overeen met specifieke typen MyType1 en MyType2 met hun respectieve volledig gekwalificeerde namen, en alle afgeleide typen.

Zie ook

  • Last updated on