Udostępnij za pośrednictwem

CA1068: Parametry CancellationToken muszą być ostatnie

Właściwości Wartość
Identyfikator reguły CA1068
Tytuł Parametry CancellationToken muszą występować na końcu
Kategoria Projektowanie
Poprawka łamiąca lub nienaruszająca Przełomowe
Domyślnie włączone na platformie .NET 10 Jako sugestia
Zastosowane języki C# i Visual Basic

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, który tworzy ten token i używa go w obliczeniach możliwych do anulowania. Częstą praktyką jest posiadanie długiego łańcucha wywołań metod, które przekazują token anulowania od wywołującego do wywoływanych. W związku z tym duża liczba metod biorących udział w anulowalnych obliczeniach ma parametr 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 zignorować ostrzeżenie tej reguły, aby uniknąć zmiany powodującej niekompatybilność dla użytkowników tej biblioteki.

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ć, na które części bazy kodu ma być stosowana ta reguła.

Możesz skonfigurować te opcje tylko dla tej reguły, dla wszystkich reguł, do których mają zastosowanie, lub dla wszystkich reguł w tej kategorii (Design), do których mają 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óre części bazy kodu ma być stosowana ta reguła, na podstawie ich poziomu dostępu, ustawiając opcję api_surface. 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

Notatka

Zastąp część XXXXCAXXXX identyfikatorem odpowiedniej reguły.

Wyklucz określone symbole

Z analizy można wykluczyć określone symbole, takie jak typy i metody, ustawiając opcję excluded_symbol_names. 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

Notatka

Zastąp część XXXXCAXXXX identyfikatorem odpowiedniej reguły.

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 symbolu wymaga prefiksu określającego rodzaj symbolu, takiego jak M: dla metody, T: dla typów i N: dla przestrzeni nazw.
  • .ctor dla konstruktorów i .cctor dla 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) Dopasowuje określoną metodę MyMethod do określonej, w pełni kwalifikowanej sygnatury.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType) Dopasowuje określone metody MyMethod1 i MyMethod2 z odpowiednimi w pełni kwalifikowanymi sygnaturami.

Wyklucz określone typy i ich pochodne typy

Określone typy i ich typy pochodne można wykluczyć z analizy, ustawiając opcję excluded_type_names_with_derived_types. 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

Notatka

Zastąp część XXXXCAXXXX identyfikatorem odpowiedniej reguły.

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

  • Podaj tylko nazwę typu (obejmuje wszystkie typy o tej nazwie, bez względu na typ zawierający lub przestrzeń nazw).
  • W pełni kwalifikowane nazwy w formacie dokumentacyjnego identyfikatora symbolu, z opcjonalnym prefiksem T:.

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 Dopasowuje określony typ MyType do danej w pełni kwalifikowanej nazwy i do wszystkich jego pochodnych typów.
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ż

  • Last updated on