CA2241: Provide correct arguments to formatting methods

Artikkel
12/16/2023

Property	Value
Rule ID	CA2241
Title	Provide correct arguments to formatting methods
Category	Usage
Fix is breaking or non-breaking	Non-breaking
Enabled by default in .NET 8	As suggestion

Cause

The format string argument passed to a method such as WriteLine, Write, or System.String.Format does not contain a format item that corresponds to each object argument, or vice versa.

By default, this rule only analyzes calls to the three methods mentioned previously, but this is configurable.

Rule description

The arguments to methods such as WriteLine, Write, and Format consist of a format string followed by several System.Object instances. The format string consists of text and embedded format items of the form {index[,alignment][:formatString]}. 'index' is a zero-based integer that indicates which of the objects to format. If an object does not have a corresponding index in the format string, the object is ignored. If the object specified by 'index' does not exist, a System.FormatException is thrown at run time.

How to fix violations

To fix a violation of this rule, provide a format item for each object argument and provide an object argument for each format item.

When to suppress warnings

Do not suppress a warning from this rule.

Configure code to analyze

Use the following options to configure additional methods to run this rule on.

Additional string formatting methods
Determine additional string formatting methods automatically

Additional string formatting methods

You can configure names of additional string formatting methods which should be analyzed by this rule. For example, to specify all methods named MyFormat as string formatting methods, you can add the following key-value pair to an .editorconfig file in your project:

dotnet_code_quality.CA2241.additional_string_formatting_methods = MyFormat

Allowed method name formats in the option value (separated by |):

Method name only (includes all methods with the name, regardless of the containing type or namespace)
Fully qualified names in the symbol's documentation ID format, with an optional M: prefix.

Examples:

Option Value	Summary
`dotnet_code_quality.CA2241.additional_string_formatting_methods = MyFormat`	Matches all methods named `MyFormat` in the compilation.
`dotnet_code_quality.CA2241.additional_string_formatting_methods = MyFormat1\|MyFormat2`	Matches all methods named either `MyFormat1` or `MyFormat2` in the compilation.
`dotnet_code_quality.CA2241.additional_string_formatting_methods = NS.MyType.MyFormat(ParamType)`	Matches specific method `MyFormat` with given fully qualified signature.
`dotnet_code_quality.CA2241.additional_string_formatting_methods = NS1.MyType1.MyFormat1(ParamType)\|NS2.MyType2.MyFormat2(ParamType)`	Matches specific methods `MyFormat1` and `MyFormat2` with respective fully qualified signature.

Determine additional string formatting methods automatically

Instead of specifying an explicit list of additional string formatting methods, you can configure the analyzer to automatically attempt to determine the string formatting method. By default, this option is disabled. If the option is enabled, any method that has a string format parameter followed by a params object[] parameter is considered a string formatting method:

dotnet_code_quality.CA2241.try_determine_additional_string_formatting_methods_automatically = true

Example

The following example shows two violations of the rule.

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

Jagamisviis: