CA1068: I parametri CancellationToken devono venire per ultimi
Proprietà | valore |
---|---|
ID regola | CA1068 |
Title | I parametri CancellationToken devono essere indicati per ultimi |
Categoria | Progettazione |
La correzione causa un'interruzione o meno | Interruzione |
Abilitato per impostazione predefinita in .NET 9 | 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
oout
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.
- Includere superfici API specifiche
- Escludere simboli specifici
- Escludere tipi specifici e i relativi tipi derivati
È 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 eN:
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 facoltativo
T:
.
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. |