CA1304: укажите CultureInfo

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

Причина

Метод или конструктор вызывает элемент, имеющий перегрузку, которая принимает параметр System.Globalization.CultureInfo, и этот метод или конструктор не вызывает перегрузку, которая принимает параметр CultureInfo. Это правило игнорирует вызовы следующих методов:

Вы также можете настроить дополнительные символы для исключения с помощью этого правила.

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

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

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

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

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

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

Примечание.

CultureInfo.CurrentUICulture используется только для получения локализованных ресурсов с помощью экземпляра класса System.Resources.ResourceManager.

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

Чтобы устранить нарушение этого правила, используйте перегрузку, которая принимает аргумент CultureInfo.

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

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

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

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

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

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

[*.{cs,vb}]
dotnet_diagnostic.CA1304.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 с заданным полным именем и всем производным от них типам.

Пример, демонстрирующий устранение нарушений

В следующем примере BadMethod вызывает два нарушения этого правила. GoodMethod устраняет первое нарушение, передавая инвариантные язык и региональные параметры в String.Compare, и исправляет второе нарушение, передавая текущие язык и региональные параметры в String.ToLower, так как string3 отображается для пользователя.

public class CultureInfoTest
{
    public void BadMethod(String string1, String string2, String string3)
    {
        if (string.Compare(string1, string2, false) == 0)
        {
            Console.WriteLine(string3.ToLower());
        }
    }

    public void GoodMethod(String string1, String string2, String string3)
    {
        if (string.Compare(string1, string2, false,
                          CultureInfo.InvariantCulture) == 0)
        {
            Console.WriteLine(string3.ToLower(CultureInfo.CurrentCulture));
        }
    }
}

Пример, демонстрирующий форматированный вывод

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

public class IFormatProviderTest
{
    public static void Main1304()
    {
        string dt = "6/4/1900 12:15:12";

        // The default behavior of DateTime.Parse is to use
        // the current culture.

        // Violates rule: SpecifyIFormatProvider.
        DateTime myDateTime = DateTime.Parse(dt);
        Console.WriteLine(myDateTime);

        // Change the current culture to the French culture,
        // and parsing the same string yields a different value.

        Thread.CurrentThread.CurrentCulture = new CultureInfo("Fr-fr", true);
        myDateTime = DateTime.Parse(dt);

        Console.WriteLine(myDateTime);
    }
}

В примере получается следующий вывод.

6/4/1900 12:15:12 PM
06/04/1900 12:15:12

См. также