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

Свойство	Значение
Идентификатор правила	CA2241
Заголовок	Задайте правильные аргументы для методов форматирования
Категория	Использование
Исправление является критическим или не критическим	неразрывный
Включен по умолчанию в .NET 10	Как предложение
Применимые языки	C# и Visual Basic

Причина

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

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

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

Аргументы для таких методов, как WriteLine, Write и Format, состоят из строки форматирования, за которой следует несколько экземпляров System.Object. Строка формата состоит из текста и вставленных элементов форматирования, таких как {index[,alignment][:formatString]}. '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	Соответствует всем методам с именем MyFormat1 или MyFormat2 в компиляции.
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

Пример

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

Imports System

Namespace ca2241

    Class CallsStringFormat

        Sub CallFormat()

            Dim file As String = "file name"
            Dim errors As Integer = 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))

        End Sub

    End Class

End Namespace

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));
    }
}