CA1068: I parametri CancellationToken devono venire per ultimi

  • Articolo
Proprietà valore
ID regola CA1068
Title I parametri CancellationToken devono essere indicati per ultimi
Categoria Progettazione
Correzione che causa un'interruzione o un'interruzione Interruzione
Abilitato per impostazione predefinita in .NET 8 Come suggerimento

Causa

Un metodo ha un CancellationToken parametro che non è l'ultimo parametro.

Per impostazione predefinita, questa regola analizza l'intera codebase, ma è configurabile.

Descrizione regola

I metodi che eseguono operazioni a esecuzione prolungata o operazioni asincrone e sono annullabili normalmente accettano un parametro del token di annullamento. Ogni token di annullamento ha un CancellationTokenSource oggetto che crea il token e lo usa per i calcoli annullabili. È pratica comune avere una lunga catena di chiamate di metodo che passano intorno al token di annullamento dai chiamanti ai chiamato. Di conseguenza, un numero elevato di metodi che prendono parte a un calcolo annullabile finisce per avere un parametro token di annullamento. Tuttavia, il token di annullamento stesso non è in genere rilevante per la funzionalità di base di una maggior parte di questi metodi. È considerata una buona procedura di progettazione dell'API avere tali parametri come l'ultimo parametro nell'elenco.

Casi speciali

La regola CA1068 non viene attivata nei casi speciali seguenti:

  • Il metodo ha uno o più parametri facoltativi (facoltativo in Visual Basic) che seguono un parametro di token di annullamento non facoltativo. Il compilatore richiede che tutti i parametri facoltativi siano definiti dopo tutti i parametri non facoltativi.
  • Il metodo ha uno o più parametri ref o out (ByRef in Visual Basic) dopo un parametro di token di annullamento. È prassi comune avere ref o out parametri alla fine dell'elenco, perché in genere indicano i valori di output per il metodo .

Come correggere le violazioni

Modificare la firma del metodo per spostare il parametro del token di annullamento alla fine dell'elenco. Ad esempio, i due frammenti di codice seguenti mostrano una violazione della regola e come risolverli:

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

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

Quando eliminare gli avvisi

Se il metodo è un'API pubblica visibile esternamente che fa già parte di una libreria fornita, è possibile eliminare un avviso da questa regola per evitare una modifica di rilievo per i consumer della libreria.

Eliminare un avviso

Se si vuole eliminare una singola violazione, aggiungere direttive del preprocessore al file di origine per disabilitare e quindi riabilitare la regola.

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

Per disabilitare la regola per un file, una cartella o un progetto, impostarne la gravità none su nel file di configurazione.

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

Per altre informazioni, vedere Come eliminare gli avvisi di analisi del codice.

Configurare il codice da analizzare

Usare le opzioni seguenti per configurare le parti della codebase in cui eseguire questa regola.

È possibile configurare queste opzioni solo per questa regola, per tutte le regole a cui si applica o per tutte le regole in questa categoria (Progettazione) a cui si applica. Per altre informazioni, vedere Opzioni di configurazione delle regole di qualità del codice.

Includere superfici API specifiche

È possibile configurare le parti della codebase in modo da eseguire questa regola in base all'accessibilità. Ad esempio, per specificare che la regola deve essere eseguita solo sulla superficie dell'API non pubblica, aggiungere la coppia chiave-valore seguente a un file con estensione editorconfig nel progetto:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Escludere simboli specifici

È possibile escludere simboli specifici, ad esempio tipi e metodi, dall'analisi. Ad esempio, per specificare che la regola non deve essere eseguita in alcun codice all'interno di tipi denominati MyType, aggiungere la coppia chiave-valore seguente a un file con estensione editorconfig nel progetto:

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

Formati di nome simbolo consentiti nel valore dell'opzione (separati da |):

  • Solo nome simbolo (include tutti i simboli con il nome, indipendentemente dal tipo o dallo spazio dei nomi contenitore).
  • Nomi completi nel formato ID della documentazione del simbolo. Ogni nome di simbolo richiede un prefisso di tipo simbolo, ad esempio M: per i metodi, T: per i tipi e N: per gli spazi dei nomi.
  • .ctor per costruttori e .cctor per costruttori statici.

Esempi:

Valore opzione Riepilogo
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType Corrisponde a tutti i simboli denominati MyType.
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1|MyType2 Corrisponde a tutti i simboli denominati MyType1 o MyType2.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType) Corrisponde a un metodo MyMethod specifico con la firma completa specificata.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType) Trova la corrispondenza con metodi MyMethod1 specifici e MyMethod2 con le rispettive firme complete.

Escludere tipi specifici e i relativi tipi derivati

È possibile escludere tipi specifici e i relativi tipi derivati dall'analisi. Ad esempio, per specificare che la regola non deve essere eseguita in alcun metodo all'interno di tipi denominati MyType e dei relativi tipi derivati, aggiungere la coppia chiave-valore seguente a un file con estensione editorconfig nel progetto:

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

Formati di nome simbolo consentiti nel valore dell'opzione (separati da |):

  • Solo nome di tipo (include tutti i tipi con il nome, indipendentemente dal tipo o dallo spazio dei nomi contenitore).
  • Nomi completi nel formato ID della documentazione del simbolo, con un prefisso facoltativoT:.

Esempi:

Valore opzione Riepilogo
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType Corrisponde a tutti i tipi denominati MyType e a tutti i relativi tipi derivati.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1|MyType2 Corrisponde a tutti i tipi denominati MyType1 o MyType2 e a tutti i relativi tipi derivati.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType Corrisponde a un tipo MyType specifico con il nome completo specificato e tutti i relativi tipi derivati.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1|M:NS2.MyType2 Corrisponde a tipi MyType1 specifici e MyType2 con i rispettivi nomi completi e tutti i relativi tipi derivati.

Vedi anche