Прочитать на английском

Поделиться через

CA2241: предоставьте правильные аргументы методам форматирования

  • Статья
  • 06.09.2023
Свойство Значение
Идентификатор правила CA2241
Заголовок Задайте правильные аргументы для методов форматирования
Категория Использование
Исправление является критическим или не критическим Не критическое
Включен по умолчанию в .NET 9 Как предложение

Причина

Строковый format аргумент, переданный методу, например WriteLine, Writeили System.String.Format не содержит элемент формата, соответствующий каждому аргументу объекта или наоборот.

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

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

Аргументы для таких методов, как WriteLine, Write и Format, состоят из строки форматирования, за которой следует несколько экземпляров System.Object. Строка формата состоит из текстовых и внедренных элементов формата формы {index[,alignment][:formatString]}. 'index' — это отсчитываемое от нуля целое число, которое указывает форматируемый объект. Если у объекта нет соответствующего индекса в строке формата, объект игнорируется. Если объект, указанный параметром "index", не существует, во время выполнения создается исключение System.FormatException.

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

Чтобы устранить нарушение этого правила, укажите элемент форматирования для каждого аргумента объекта и предоставьте аргумент объекта для каждого элемента форматирования.

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

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

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

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

Дополнительные методы форматирования строк

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

dotnet_code_quality.CA2241.additional_string_formatting_methods = MyFormat

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

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

Примеры:

Значение параметра Итоги
dotnet_code_quality.CA2241.additional_string_formatting_methods = MyFormat Соответствует всем методам, именованным MyFormat в компиляции.
dotnet_code_quality.CA2241.additional_string_formatting_methods = MyFormat1|MyFormat2 Соответствует всем методам с именем или MyFormat1MyFormat2 в компиляции.
dotnet_code_quality.CA2241.additional_string_formatting_methods = NS.MyType.MyFormat(ParamType) Соответствует конкретному методу MyFormat с заданной полной подписью.
dotnet_code_quality.CA2241.additional_string_formatting_methods = NS1.MyType1.MyFormat1(ParamType)|NS2.MyType2.MyFormat2(ParamType) Соответствует определенным методам MyFormat1 и MyFormat2 с соответствующей полной подписью.

Автоматическое определение дополнительных методов форматирования строк

Вместо явного указания списка дополнительных методов форматирования строк анализатор можно настроить на автоматическую попытку определить метод форматирования строк. По умолчанию этот параметр отключен. Если этот параметр включен, то любой метод с параметром string format, за которым следует параметр params object[], считается методом форматирования строк:

dotnet_code_quality.CA2241.try_determine_additional_string_formatting_methods_automatically = true

Пример

В следующем примере показаны два нарушения правила.

class CallsStringFormat
{
    void CallFormat()
    {
        string file = "file name";
        int errors = 13;

        // Violates the rule.
        Console.WriteLine(string.Format("{0}", file, errors));

        Console.WriteLine(string.Format("{0}: {1}", file, errors));

        // Violates the rule and generates a FormatException at runtime.
        Console.WriteLine(string.Format("{0}: {1}, {2}", file, errors));
    }
}