Freigeben über

CA1068: Die CancellationToken-Parameter müssen zuletzt aufgeführt werden.

Eigenschaft Wert
Regel-ID CA1068
Titel CancellationToken-Parameter müssen als letztes angegeben werden.
Kategorie Design
Fix führt zu Unterbrechungen oder bleibt funktionsfähig Eilmeldung
Standardmäßig in .NET 10 aktiviert Als Vorschlag
Anwendbare Sprachen C# und Visual Basic

Ursache

Eine Methode verfügt über einen CancellationToken-Parameter, der nicht der letzte Parameter ist.

Standardmäßig analysiert diese Regel die gesamte Codebasis, aber dieses Verhalten ist konfigurierbar.

Regelbeschreibung

Methoden, die lang andauernde oder asynchrone Vorgänge ausführen und abgebrochen werden können, akzeptieren normalerweise einen Abbruchtoken-Parameter. Jedes Abbruch-Token hat eine CancellationTokenSource, die das Token erstellt und es für abbrechbare Berechnungen nutzt. Es ist üblich, eine lange Kette von Methodenaufrufen zu verwenden, die das Cancellation-Token von den Aufrufern an die Aufgerufenen weitergeben. Daher verfügt eine große Anzahl von Methoden, die an einer abbrechbaren Berechnung teilnehmen, über einen Abbruch-Token-Parameter. Das Abbruch-Token selbst ist jedoch in der Regel nicht für die Kernfunktionen der Mehrzahl dieser Methoden relevant. Es ist eine gute API-Entwurfspraxis, solche Parameter als letzten Parameter in der Liste zu haben.

Spezialfälle

Die Regel CA1068 wird in den folgenden Sonderfällen nicht ausgelöst:

  • Die Methode verfügt über mindestens einen optionalen Parameter (optional in Visual Basic) nach einem nicht optionalen Abbruch-Token-Parameter. Der Compiler erfordert, dass alle optionalen Parameter nach allen nicht optionalen Parametern definiert werden.
  • Die Methode verfügt über einen oder mehrere ref- oder out-Parameter (ByRef in Visual Basic), die einem Abbruch-Token-Parameter folgen. Es ist üblich, ref- oder out-Parameter am Ende der Liste zu haben, da sie normalerweise Ausgabewerte für die Methode angeben.

So beheben Sie Verstöße

Ändern Sie die Methodensignatur, um den Abbruch-Token-Parameter an das Ende der Liste zu verschieben. Die folgenden beiden Codeausschnitte zeigen z. B. einen Verstoß gegen die Regel und wie dieser korrigiert werden kann:

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

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

Wann sollten Warnungen unterdrückt werden?

Wenn die Methode eine extern sichtbare öffentliche API ist, die bereits Teil einer ausgelieferten Bibliothek ist, ist es sicher, eine Warnung gemäß dieser Regel zu unterdrücken, um eine kompatibilitätsbrechende Änderung für die Nutzer der Bibliothek zu vermeiden.

Unterdrücken einer Warnung

Um nur eine einzelne Verletzung zu unterdrücken, fügen Sie der Quelldatei Präprozessoranweisungen hinzu, um die Regel zu deaktivieren und dann wieder zu aktivieren.

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

Um die Regel für eine Datei, einen Ordner oder ein Projekt zu deaktivieren, legen Sie den Schweregrad auf none in der Konfigurationsdatei fest.

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

Weitere Informationen finden Sie unter Vorgehensweise: Unterdrücken von Codeanalyse-Warnungen.

Konfigurieren des zu analysierenden Codes

Mit den folgenden Optionen können Sie konfigurieren, für welche Teile Ihrer Codebasis diese Regel ausgeführt werden soll.

Sie können diese Optionen nur für diese Regel konfigurieren, für alle Regeln, auf die sie angewendet werden, oder für alle Regeln, auf die sie in dieser Kategorie (Entwurf) angewendet werden. Weitere Informationen finden Sie unter Konfigurationsoptionen für die Codequalitätsregel.

Einschließen bestimmter API-Oberflächen

Sie können konfigurieren, in welchen Teilen Ihrer Codebasis je nach Barrierefreiheit diese Regel ausgeführt werden soll, indem Sie die Option api_surface festlegen. Sie können beispielsweise festlegen, dass die Regel nur für die nicht öffentliche API-Oberfläche ausgeführt werden soll, indem Sie einer EDITORCONFIG-Datei in Ihrem Projekt das folgende Schlüssel-Wert-Paar hinzufügen:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Hinweis

Ersetzen Sie den XXXX-Teil von CAXXXX durch die ID der anwendbaren Regel.

Ausschließen bestimmter Symbole

Sie können bestimmte Symbole, wie z. B. Typen und Methoden, von der Analyse ausschließen, indem Sie die Option excluded_symbol_names festlegen. Sie können beispielsweise festlegen, dass die Regel nicht für Code innerhalb von Typen namens MyType ausgeführt werden soll, indem Sie einer EDITORCONFIG-Datei in Ihrem Projekt das folgende Schlüssel-Wert-Paar hinzufügen:

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

Hinweis

Ersetzen Sie den XXXX-Teil von CAXXXX durch die ID der anwendbaren Regel.

Zulässige Formate für Symbolnamen im Optionswert (durch | getrennt):

  • Nur Symbolname (schließt alle Symbole mit dem Namen ein, unabhängig vom enthaltenden Typ oder Namespace)
  • Vollqualifizierte Namen im Dokumentations-ID-Format der Symbole. Jeder Symbolname erfordert ein Symbolartpräfix, z. B. M: für Methoden, T: für Typen und N: für Namespaces.
  • .ctor für Konstruktoren und .cctor für statische Konstruktoren

Beispiele:

Optionswert Zusammenfassung
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType Trifft auf alle Symbole namens MyType zu
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1|MyType2 Trifft auf alle Symbole namens MyType1 oder MyType2 zu
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType) Entspricht der speziellen Methode MyMethod mit der angegebenen vollqualifizierten Signatur.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType) Ordnet die spezifischen Methoden MyMethod1 und MyMethod2 ihren jeweiligen vollqualifizierten Signaturen zu.

Ausschließen bestimmter Typen und von diesen abgeleiteten Typen

Sie können bestimmte Typen und ihre abgeleiteten Typen von der Analyse ausschließen, indem Sie die Option excluded_type_names_with_derived_types festlegen. Wenn Sie z. B. festlegen möchten, dass die Regel nicht für Methoden innerhalb von MyType-Typen und von diesen abgeleiteten Typen ausgeführt werden soll, fügen Sie einer EDITORCONFIG-Datei in Ihrem Projekt das folgende Schlüssel-Wert-Paar hinzu:

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

Hinweis

Ersetzen Sie den XXXX-Teil von CAXXXX durch die ID der anwendbaren Regel.

Zulässige Formate für Symbolnamen im Optionswert (durch | getrennt):

  • Nur Typname (schließt alle Typen mit dem Namen ein, unabhängig vom enthaltenden Typ oder Namespace)
  • Vollqualifizierte Namen im Dokumentations-ID-Format des Symbols mit einem optionalen Präfix T:

Beispiele:

Optionswert Zusammenfassung
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType Stimmt mit allen MyType-Typen und allen von diesen abgeleiteten Typen überein.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1|MyType2 Stimmt mit allen MyType1- oder MyType2-Typen und allen von diesen abgeleiteten Typen überein.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType Stimmt mit einem bestimmten Typ MyType überein, der anhand eines angegebenen vollqualifizierten Namens und aller von ihm abgeleiteten Typen identifiziert wird.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1|M:NS2.MyType2 Bestimmte MyType1- und MyType2-Typen werden mit ihren entsprechenden vollqualifizierten Namen und allen abgeleiteten Typen abgeglichen.

Siehe auch

  • Last updated on