Udostępnij za pośrednictwem

CA1068: Parametry CancellationToken muszą być ostatnie

  • Artykuł
Właściwości Wartość
Identyfikator reguły CA1068
Tytuł Parametry CancellationToken muszą występować na końcu
Kategoria Projekt
Poprawka powodująca niezgodność lub niezgodność Kluczowa
Domyślnie włączone na platformie .NET 9 Jako sugestia

Przyczyna

Metoda ma CancellationToken parametr, który nie jest ostatnim parametrem.

Domyślnie ta reguła analizuje całą bazę kodu, ale można to skonfigurować.

Opis reguły

Metody, które wykonują długotrwałe operacje lub operacje asynchroniczne i można je anulować, zwykle przyjmują parametr tokenu anulowania. Każdy token anulowania ma CancellationTokenSource element , który tworzy token i używa go do anulowania obliczeń. Częstą praktyką jest posiadanie długiego łańcucha wywołań metod, które przekazują token anulowania z obiektu wywołującego do wywołań. W związku z tym duża liczba metod, które biorą udział w obliczeniach, które można anulować, kończą się parametrem tokenu anulowania. Jednak sam token anulowania nie jest zwykle istotny dla podstawowych funkcji większości tych metod. Uważa się, że dobrym rozwiązaniem projektowym interfejsu API jest posiadanie takich parametrów jako ostatniego parametru na liście.

Przypadki szczególne

Reguła CA1068 nie jest uruchamiana w następujących przypadkach specjalnych:

  • Metoda ma co najmniej jeden opcjonalny parametr (opcjonalny w Visual Basic) po nie-opcjonalnym parametrze tokenu anulowania. Kompilator wymaga, aby wszystkie parametry opcjonalne zostały zdefiniowane po wszystkich parametrach innych niż opcjonalne.
  • Metoda ma co najmniej jeden parametr ref lub out (ByRef w Visual Basic) po parametrze tokenu anulowania. Typową praktyką jest posiadanie ref parametrów lub out na końcu listy, ponieważ zwykle wskazują one wartości wyjściowe dla metody.

Jak naprawić naruszenia

Zmień sygnaturę metody, aby przenieść parametr tokenu anulowania na końcu listy. Na przykład następujące dwa fragmenty kodu pokazują naruszenie reguły i sposób jego naprawy:

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

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

Kiedy pomijać ostrzeżenia

Jeśli metoda jest zewnętrznie widocznym publicznym interfejsem API, który jest już częścią dostarczonej biblioteki, można bezpiecznie pominąć ostrzeżenie z tej reguły, aby uniknąć zmiany powodującej niezgodność dla użytkowników bibliotek.

Pomijanie ostrzeżenia

Jeśli chcesz po prostu pominąć pojedyncze naruszenie, dodaj dyrektywy preprocesora do pliku źródłowego, aby wyłączyć, a następnie ponownie włączyć regułę.

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

Aby wyłączyć regułę dla pliku, folderu lub projektu, ustaw jego ważność na none w pliku konfiguracji.

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

Aby uzyskać więcej informacji, zobacz Jak pominąć ostrzeżenia dotyczące analizy kodu.

Konfigurowanie kodu do analizowania

Użyj poniższych opcji, aby skonfigurować, które części bazy kodu mają być uruchamiane w tej regule.

Możesz skonfigurować te opcje tylko dla tej reguły, dla wszystkich reguł, do których ma ona zastosowanie, lub dla wszystkich reguł w tej kategorii (Projekt), do których ma ona zastosowanie. Aby uzyskać więcej informacji, zobacz Opcje konfiguracji reguły jakości kodu.

Uwzględnij określone powierzchnie interfejsu API

Możesz skonfigurować, na których częściach bazy kodu ma być uruchamiana ta reguła, na podstawie ich ułatwień dostępu. Aby na przykład określić, że reguła powinna być uruchamiana tylko na powierzchni niepublicznego interfejsu API, dodaj następującą parę klucz-wartość do pliku editorconfig w projekcie:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Wykluczanie określonych symboli

Z analizy można wykluczyć określone symbole, takie jak typy i metody. Aby na przykład określić, że reguła nie powinna być uruchamiana w żadnym kodzie w typach o nazwie MyType, dodaj następującą parę klucz-wartość do pliku editorconfig w projekcie:

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

Dozwolone formaty nazw symboli w wartości opcji (oddzielone przez |):

  • Tylko nazwa symbolu (zawiera wszystkie symbole o nazwie, niezależnie od typu zawierającego lub przestrzeni nazw).
  • W pełni kwalifikowane nazwy w formacie identyfikatora dokumentacji symbolu. Każda nazwa symboli wymaga prefiksu typu symboli, takiego jak M: metody, T: dla typów i N: przestrzeni nazw.
  • .ctor dla konstruktorów i .cctor konstruktorów statycznych.

Przykłady:

Wartość opcji Podsumowanie
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType Pasuje do wszystkich symboli o nazwie MyType.
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1|MyType2 Pasuje do wszystkich symboli o nazwie MyType1 lub MyType2.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType) Pasuje do określonej metody MyMethod z określonym w pełni kwalifikowanym podpisem.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType) Pasuje do określonych metod MyMethod1 i MyMethod2 z odpowiednimi w pełni kwalifikowanymi podpisami.

Wykluczanie określonych typów i ich typów pochodnych

Z analizy można wykluczyć określone typy i ich typy pochodne. Aby na przykład określić, że reguła nie powinna być uruchamiana na żadnych metodach w typach nazwanych MyType i ich typach pochodnych, dodaj następującą parę klucz-wartość do pliku .editorconfig w projekcie:

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

Dozwolone formaty nazw symboli w wartości opcji (oddzielone przez |):

  • Nazwa typu (zawiera tylko wszystkie typy o nazwie, niezależnie od typu zawierającego lub przestrzeni nazw).
  • W pełni kwalifikowane nazwy w formacie identyfikatora dokumentacji symbolu z opcjonalnym T: prefiksem.

Przykłady:

Wartość opcji Podsumowanie
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType Pasuje do wszystkich typów nazwanych MyType i wszystkich ich typów pochodnych.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1|MyType2 Dopasuje wszystkie typy o nazwie MyType1 lub MyType2 i wszystkie ich typy pochodne.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType Pasuje do określonego typu MyType z daną w pełni kwalifikowaną nazwą i wszystkimi jego typami pochodnymi.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1|M:NS2.MyType2 Pasuje do określonych typów MyType1 i MyType2 z odpowiednimi w pełni kwalifikowanymi nazwami i wszystkimi ich typami pochodnymi.

Zobacz też