Бөлісу құралы:

CA1305: следует указать IFormatProvider

Свойство Значение
Идентификатор правила CA1305
Заголовок Указывайте IFormatProvider
Категория Глобализация
Исправление является разрушающим или неразрушающим Неразрывный
Включен по умолчанию в .NET 10 Нет
Применимые языки C# и Visual Basic

Причина

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

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

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

Если объект System.Globalization.CultureInfo или IFormatProvider не указан, значение по умолчанию, предоставленное перегруженным членом, может не соответствовать вашим требованиям во всех языковых стандартах. Кроме того, участники .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

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

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

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

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

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

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

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

Заметка

Замените XXXX частью CAXXXX идентификатором применимого правила.

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

  • Только имя символа (включает все символы с данным именем, вне зависимости от типа и пространства имен).
  • Полные имена в формате идентификатора документации для символа. Для каждого имени символа требуется префикс в виде символа, например 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 с соответствующими полными квалифицированными сигнатурами.

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

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

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

Заметка

Замените XXXX частью CAXXXX идентификатором применимого правила.

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

  • Только имя типа (включает все типы с этим именем, независимо от содержащего типа или пространства имен).
  • полные имена символов в формате идентификатора документации с необязательным префиксом T:.

Примеры:

Значение параметра выбора Итоги
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}");

См. также

  • Last updated on