Dela via

CA1068: AnnulleringToken-parametrar måste komma sist

  • Artikel
Property Värde
Regel-ID CA1068
Title CancellationToken-parametrar måste komma sist
Kategori Designa
Korrigeringen är icke-bakåtkompatibel Brott
Aktiverad som standard i .NET 9 Som förslag

Orsak

En metod har en CancellationToken parameter som inte är den sista parametern.

Som standard analyserar den här regeln hela kodbasen, men detta kan konfigureras.

Regelbeskrivning

Metoder som utför långvariga åtgärder eller asynkrona åtgärder och som kan avbrytas tar normalt en parameter för annulleringstoken. Varje annulleringstoken har en CancellationTokenSource som skapar token och använder den för avbrutna beräkningar. Det är vanligt att ha en lång kedja av metodanrop som passerar runt annulleringstoken från anroparna till anroparna. Därför får ett stort antal metoder som deltar i en avbruten beräkning en parameter för annulleringstoken. Själva annulleringstoken är dock vanligtvis inte relevant för kärnfunktionerna i en majoritet av dessa metoder. Det anses vara en bra API-designmetod att ha sådana parametrar som den sista parametern i listan.

Särskilda fall

Regel CA1068 utlöses inte i följande specialfall:

  • Metoden har en eller flera valfria parametrar (valfritt i Visual Basic) efter en icke-valfri parameter för annulleringstoken. Kompilatorn kräver att alla valfria parametrar definieras efter alla icke-valfria parametrar.
  • Metoden har en eller flera referens- eller utdataparametrar (ByRef i Visual Basic) efter en parameter för annulleringstoken. Det är vanligt att ha ref eller out parametrar i slutet av listan, eftersom de vanligtvis anger utdatavärden för metoden.

Så här åtgärdar du överträdelser

Ändra metodsignaturen för att flytta parametern för annulleringstoken till slutet av listan. Följande två kodfragment visar till exempel ett brott mot regeln och hur du åtgärdar den:

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

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

När du ska ignorera varningar

Om metoden är ett externt synligt offentligt API som redan ingår i ett levererat bibliotek är det säkert att ignorera en varning från den här regeln för att undvika en icke-bakåtkompatibel ändring för bibliotekskonsumenterna.

Ignorera en varning

Om du bara vill förhindra en enda överträdelse lägger du till förprocessordirektiv i källfilen för att inaktivera och aktiverar sedan regeln igen.

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

Om du vill inaktivera regeln för en fil, mapp eller ett projekt anger du dess allvarlighetsgrad till none i konfigurationsfilen.

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

Mer information finns i Så här utelämnar du kodanalysvarningar.

Konfigurera kod för analys

Använd följande alternativ för att konfigurera vilka delar av kodbasen som regeln ska köras på.

Du kan konfigurera dessa alternativ för just den här regeln, för alla regler som den gäller för eller för alla regler i den här kategorin (design) som den gäller för. Mer information finns i Konfigurationsalternativ för kodkvalitetsregel.

Inkludera specifika API-ytor

Du kan konfigurera vilka delar av kodbasen som ska köras med den här regeln baserat på deras tillgänglighet. Om du till exempel vill ange att regeln endast ska köras mot den icke-offentliga API-ytan lägger du till följande nyckel/värde-par i en .editorconfig-fil i projektet:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Exkludera specifika symboler

Du kan exkludera specifika symboler, till exempel typer och metoder, från analys. Om du till exempel vill ange att regeln inte ska köras på någon kod inom typer med namnet MyTypelägger du till följande nyckel/värde-par i en .editorconfig-fil i projektet:

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

Tillåtna symbolnamnformat i alternativvärdet (avgränsade med |):

  • Endast symbolnamn (innehåller alla symboler med namnet, oavsett vilken typ eller namnrymd som innehåller).
  • Fullständigt kvalificerade namn i symbolens dokumentations-ID-format. Varje symbolnamn kräver ett symboltypprefix, till exempel M: för metoder, T: för typer och N: för namnområden.
  • .ctor för konstruktorer och .cctor statiska konstruktorer.

Exempel:

Alternativvärde Sammanfattning
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType Matchar alla symboler med namnet MyType.
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1|MyType2 Matchar alla symboler med namnet antingen MyType1 eller MyType2.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType) Matchar en specifik metod MyMethod med den angivna fullständigt kvalificerade signaturen.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType) Matchar specifika metoder MyMethod1 och MyMethod2 med respektive fullständigt kvalificerade signaturer.

Exkludera specifika typer och deras härledda typer

Du kan exkludera specifika typer och deras härledda typer från analys. Om du till exempel vill ange att regeln inte ska köras på några metoder inom typer som heter MyType och deras härledda typer lägger du till följande nyckel/värde-par i en .editorconfig-fil i projektet:

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

Tillåtna symbolnamnformat i alternativvärdet (avgränsade med |):

  • Skriv endast namn (innehåller alla typer med namnet, oavsett vilken typ eller namnrymd som innehåller).
  • Fullständigt kvalificerade namn i symbolens dokumentations-ID-format, med ett valfritt T: prefix.

Exempel:

Alternativvärde Sammanfattning
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType Matchar alla typer med namnet MyType och alla deras härledda typer.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1|MyType2 Matchar alla typer med namnet antingen MyType1 eller MyType2 och alla deras härledda typer.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType Matchar en specifik typ MyType med ett angivet fullständigt kvalificerat namn och alla dess härledda typer.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1|M:NS2.MyType2 Matchar specifika typer MyType1 och MyType2 med respektive fullständigt kvalificerade namn och alla deras härledda typer.

Se även