Udostępnij za pośrednictwem

CA1305: Określ IFormatProvider

Właściwości Wartość
Identyfikator reguły CA1305
Tytuł Określ IFormatProvider
Kategoria Globalizacja
Poprawka jest powodująca problemy lub niepowodująca problemów Niezgodność
Domyślnie włączone na platformie .NET 10 Nie.
Zastosowane języki C# i Visual Basic

Przyczyna

Wywołanie jest wykonywane do metody, która ma przeciążenie, które akceptuje System.IFormatProvider argument, i że przeciążenie nie jest wywoływane.

Ta reguła ignoruje wywołania metod platformy .NET, które są udokumentowane jako ignorujące IFormatProvider parametr . Reguła ignoruje również następujące metody:

Opis reguły

Jeśli obiekt System.Globalization.CultureInfo lub IFormatProvider nie zostanie podany, wartość domyślna dostarczana przez przeciążoną metodę może nie mieć oczekiwanego efektu we wszystkich lokalach. Ponadto członkowie platformy .NET wybierają domyślną kulturę i formatowanie na podstawie założeń, które mogą nie być poprawne dla kodu. Aby upewnić się, że kod działa zgodnie z oczekiwaniami w scenariuszach, należy podać informacje specyficzne dla kultury zgodnie z następującymi wytycznymi:

  • Jeśli wartość zostanie wyświetlona użytkownikowi, użyj bieżącej kultury. Zobacz: CultureInfo.CurrentCulture.

  • Jeśli wartość będzie przechowywana i uzyskiwana przez oprogramowanie (utrwalone w pliku lub bazie danych), użyj niezmiennej kultury. Zobacz: CultureInfo.InvariantCulture.

  • Jeśli nie znasz miejsca docelowego wartości, określ kulturę odbiorcy danych lub dostawcy danych.

Nawet jeśli domyślne zachowanie przeciążonego elementu członkowskiego jest odpowiednie dla Twoich potrzeb, lepiej jest jawnie wywołać przeciążenie specyficzne dla kultury, aby kod był dokumentowany samodzielnie i łatwiej konserwowany.

Jak naprawić naruszenia

Aby naprawić naruszenie tej reguły, użyj przeciążenia, które przyjmuje IFormatProvider argument. Albo, aby użyć niezmiennej kultury, użyj ciągu interpolowanego języka C# i przekaż go do String.Create(IFormatProvider, DefaultInterpolatedStringHandler) wraz z CultureInfo.InvariantCulture, na przykład:

string.Create(CultureInfo.InvariantCulture, $"{major}.{minor}.{build}.{revision}");

Kiedy pomijać ostrzeżenia

Można bezpiecznie pominąć ostrzeżenie z tej reguły, gdy jest pewien, że domyślny format jest poprawnym wyborem, a utrzymanie kodu nie jest ważnym priorytetem programowania.

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 CA1305
// The code that's violating the rule is on this line.
#pragma warning restore CA1305

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

[*.{cs,vb}]
dotnet_diagnostic.CA1305.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órych częściach bazy kodu ma być uruchamiana 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 (globalizacji), do których mają zastosowanie. Aby uzyskać więcej informacji, zobacz Opcje konfiguracji reguły jakości kodu.

Wykluczanie określonych symboli

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 rodzaju symbolu, takiego jak M: dla metod, 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) 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) Dopasowuje określone metody MyMethod1 i MyMethod2 z odpowiednimi w pełni kwalifikowanymi sygnaturami.

Wyklucz określone typy i ich typy pochodne

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 |):

  • 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 Dopasowuje określony typ MyType z podaną w pełni kwalifikowaną nazwą i wszystkimi jego typami dziedziczącymi.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1|M:NS2.MyType2 Dopasowuje określone typy MyType1 i MyType2 do ich odpowiednich w pełni kwalifikowanych nazw oraz wszystkich ich typów pochodnych.

Przykład

W poniższym kodzie ciąg example1 narusza regułę CA1305. Ciąg example2 spełnia regułę CA1305 przez przekazanie CultureInfo.CurrentCulture, który implementuje IFormatProvider, do String.Format(IFormatProvider, String, Object). Ciąg example3 spełnia regułę CA1305, przekazując ciąg interpolowany do String.Create(IFormatProvider, DefaultInterpolatedStringHandler) wraz z CultureInfo.InvariantCulture.

string name = "Georgette";

// Violates CA1305
string example1 = string.Format("Hello {0}", name);

// Satisfies CA1305
string example2 = string.Format(CultureInfo.CurrentCulture, "Hello {0}", name);

// Satisfies CA1305
string example3 = string.Create(CultureInfo.InvariantCulture, $"Hello {name}");

Zobacz też

  • Last updated on