CA1305: укажите IFormatProvider

  • Статья
Свойство Значение
Идентификатор правила CA1305
Заголовок Указывайте IFormatProvider
Категория Глобализация
Исправление является критическим или не критическим Не критическое
Включен по умолчанию в .NET 8 No

Причина

Вызов выполняется к методу, который имеет перегрузку, которая принимает System.IFormatProvider аргумент, и эта перегрузка не вызывается.

Это правило игнорирует вызовы методов .NET, которые задокументированы как пропускающие параметр IFormatProvider. Правило также пропускает следующие методы.

Описание правила

System.Globalization.CultureInfoIFormatProvider Если объект не указан, значение по умолчанию, предоставленное перегруженным членом, может не повлиять на то, что требуется во всех языковых стандартах. Кроме того, элементы .NET выбирают язык и региональные параметры по умолчанию и выполняют форматирование на основе допущений, что может не подходить для вашего кода. Чтобы код работал для сценариев надлежащим образом, необходимо предоставить сведения, относящиеся к языку и региональным параметрам, в соответствии со следующими рекомендациями.

  • Если значение будет отображаться для пользователя, используйте текущий язык и региональные параметры. См. раздел CultureInfo.CurrentCulture.

  • Если значение будет сохранено и доступно программному обеспечению (сохранено в файл или базу данных), используйте инвариантный язык и региональные параметры. См. раздел CultureInfo.InvariantCulture.

  • Если вы не знаете назначение значения, укажите язык и региональные параметры потребителя данных или поставщика.

Даже если поведение перегруженного члена по умолчанию подходит для ваших потребностей, лучше явно вызвать перегрузку, зависящую от языка и региональных параметров, чтобы код был самодокументирован и проще поддерживать.

Устранение нарушений

Чтобы устранить нарушение этого правила, используйте перегрузку, которая принимает аргумент IFormatProvider. Или, чтобы использовать инвариантный язык и региональные параметры, используйте интерполированную строку C# и передайте ее String.Create(IFormatProvider, DefaultInterpolatedStringHandler) вместе, CultureInfo.InvariantCultureнапример:

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

Когда лучше отключить предупреждения

Вывод предупреждений для этого правила можно отключить, если известно, что используется правильный формат по умолчанию, и обслуживание кода не является приоритетом при разработке.

Отключение предупреждений

Если вы просто хотите отключить одно нарушение, добавьте директивы препроцессора в исходный файл, чтобы отключить и повторно включить правило.

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

Чтобы отключить правило для файла, папки или проекта, задайте его серьезность none в файле конфигурации.

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

Дополнительные сведения см. в разделе Практическое руководство. Скрытие предупреждений анализа кода.

Настройка кода для анализа

Используйте следующие параметры, чтобы указать части базы кода, к которым будет применяться это правило.

Эти параметры можно настроить только для этого правила, для всех правил, к которым она применяется, или для всех правил в этой категории (глобализация), к которым она применяется. Дополнительные сведения см. в статье Параметры конфигурации правила качества кода.

Исключение определенных символов

Вы можете исключить из анализа определенные символы, например типы и методы. Например, чтобы указать, что правило не должно выполняться для какого-либо кода в типах с именем MyType, добавьте следующую пару "ключ-значение" в файл EDITORCONFIG в своем проекте:

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

Допустимые форматы имени символа в значении параметра (разделенные |):

  • Только имя символа (включает все символы с этим именем, любого типа и в любом пространстве имен).
  • Полные имена в формате идентификатора документации для символа. Для каждого имени символа требуется префикс в виде символа, например M: для методов, T: для типов и N: для пространств имен.
  • .ctor используется для конструкторов, а .cctor — для статических конструкторов.

Примеры:

Значение параметра Итоги
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType Соответствует всем символам с именем MyType.
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1|MyType2 Соответствует всем символам с именем MyType1 или MyType2.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType) Соответствует конкретному методу MyMethod с заданной полной сигнатурой.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType) Соответствует конкретным методам MyMethod1 и MyMethod2 с соответствующими полными сигнатурами.

Исключить определенные типы и их производные типы

Из анализа можно исключать определенные типы и их производные типы. Например, чтобы указать, что правило не должно выполняться в каких-либо методах типов MyType и их производных типов, добавьте следующую пару "ключ-значение" в файл .editorconfig своего проекта:

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

Допустимые форматы имени символа в значении параметра (разделенные |):

Примеры:

Значение параметра Итоги
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType Соответствует всем типам с именем MyType и всем их производным типам.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1|MyType2 Соответствует всем типам с именем MyType1 или MyType2 и всем их производным типам.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType Соответствует конкретному типу MyType с заданным полным именем и всем производным от него типам.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1|M:NS2.MyType2 Соответствует конкретным типам MyType1 и MyType2 с заданным полным именем и всем производным от них типам.

Пример

В следующем коде строка example1 нарушает правило CA1305. Строка example2 удовлетворяет правилу CA1305, передавая свойство CultureInfo.CurrentCulture, которое реализует интерфейс IFormatProvider, методу String.Format(IFormatProvider, String, Object). Строка example3 удовлетворяет правилу CA1305 путем передачи интерполированной строки String.Create(IFormatProvider, DefaultInterpolatedStringHandler) вместе с 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}");

См. также