CA2241: Dostarcz poprawne argumenty do metod formatowania

Właściwości	Wartość
Identyfikator reguły	CA2241
Tytuł	Podaj poprawne argumenty metod formatowania
Kategoria	Użycie
Poprawka powodująca niezgodność lub niezgodność	Niezgodność
Domyślnie włączone na platformie .NET 9	Jako sugestia

Przyczyna

format Argument ciągu przekazany do metody, takiej jak WriteLine, Writelub System.String.Format nie zawiera elementu formatu odpowiadającego każdemu argumentowi obiektu lub odwrotnie.

Domyślnie ta reguła analizuje tylko wywołania do trzech wymienionych wcześniej metod, ale jest to możliwe do skonfigurowania.

Opis reguły

Argumenty metod, takich jak WriteLine, Writei Format składają się z ciągu formatu, po którym następuje kilka System.Object wystąpień. Ciąg formatu składa się z tekstu i osadzonych elementów formatu formularza {index[,alignment][:formatString]}. "index" jest liczbą całkowitą opartą na zera, która wskazuje, które obiekty mają być sformatowane. Jeśli obiekt nie ma odpowiedniego indeksu w ciągu formatu, obiekt jest ignorowany. Jeśli obiekt określony przez "index" nie istnieje, System.FormatException obiekt jest zgłaszany w czasie wykonywania.

Jak naprawić naruszenia

Aby naprawić naruszenie tej reguły, podaj element formatu dla każdego argumentu obiektu i podaj argument obiektu dla każdego elementu formatu.

Kiedy pomijać ostrzeżenia

Nie pomijaj ostrzeżeń dla tej reguły.

Konfigurowanie kodu do analizowania

Użyj poniższych opcji, aby skonfigurować dodatkowe metody uruchamiania tej reguły.

• Dodatkowe metody formatowania ciągów
• Automatyczne określanie dodatkowych metod formatowania ciągów

Dodatkowe metody formatowania ciągów

Można skonfigurować nazwy dodatkowych metod formatowania ciągów, które powinny być analizowane przez tę regułę. Aby na przykład określić wszystkie metody o nazwie MyFormat jako metody formatowania ciągów, możesz dodać następującą parę klucz-wartość do pliku .editorconfig w projekcie:

dotnet_code_quality.CA2241.additional_string_formatting_methods = MyFormat

Dozwolone formaty nazw metod w wartości opcji (oddzielone przez |):

• Tylko nazwa metody (zawiera wszystkie metody o nazwie, niezależnie od typu zawierającego lub przestrzeni nazw)
• W pełni kwalifikowane nazwy w formacie identyfikatora dokumentacji symbolu z opcjonalnym M: prefiksem.

Przykłady:

Wartość opcji	Podsumowanie
dotnet_code_quality.CA2241.additional_string_formatting_methods = MyFormat	Pasuje do wszystkich metod nazwanych MyFormat w kompilacji.
dotnet_code_quality.CA2241.additional_string_formatting_methods = MyFormat1|MyFormat2	Pasuje do wszystkich metod o nazwie MyFormat1 lub MyFormat2 w kompilacji.
dotnet_code_quality.CA2241.additional_string_formatting_methods = NS.MyType.MyFormat(ParamType)	Pasuje do określonej metody MyFormat z podanym w pełni kwalifikowanym podpisem.
dotnet_code_quality.CA2241.additional_string_formatting_methods = NS1.MyType1.MyFormat1(ParamType)|NS2.MyType2.MyFormat2(ParamType)	Pasuje do określonych metod MyFormat1 i MyFormat2 z odpowiednim w pełni kwalifikowanym podpisem.

Automatyczne określanie dodatkowych metod formatowania ciągów

Zamiast określać jawną listę dodatkowych metod formatowania ciągów, można skonfigurować analizator, aby automatycznie próbować określić metodę formatowania ciągów. Domyślnie ta opcja jest wyłączona. Jeśli opcja jest włączona, każda metoda, która ma string format parametr, po którym następuje params object[] parametr, jest traktowana jako metoda formatowania ciągów:

dotnet_code_quality.CA2241.try_determine_additional_string_formatting_methods_automatically = true

Przykład

W poniższym przykładzie przedstawiono dwa naruszenia reguły.

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