CA2241: Geben Sie die korrekte Anzahl für Formatierungsmethoden an.

  • Artikel
Eigenschaft Wert
Regel-ID CA2241
Titel Geben Sie die korrekte Anzahl für Formatierungsmethoden an.
Kategorie Verwendung
Fix führt oder führt nicht zur Unterbrechung Nicht unterbrechend
Standardmäßig in .NET 8 aktiviert Als Vorschlag

Ursache

Das format-Zeichenfolgenargument, das an eine Methode wie WriteLine, Write oder System.String.Format übergeben wird, enthält kein Formatelement, das den einzelnen Objektargumenten entspricht (oder umgekehrt).

Standardmäßig analysiert diese Regel nur Aufrufe der drei zuvor genannten Methoden, dies ist aber konfigurierbar.

Regelbeschreibung

Die Argumente für Methoden wie WriteLine, Write, und Format bestehen aus einer Formatzeichenfolge, gefolgt von mehreren System.Object Instanzen. Die Formatzeichenfolge besteht aus Text und eingebetteten Formatelementen der Form {index[,alignment][:formatString]}. 'Index' ist eine null-basierte Ganzzahl, die angibt, welche der Objekte formatiert werden sollen. Wenn ein Objekt keinen entsprechenden Index in der Format Zeichenfolge enthält, wird das Objekt ignoriert. Wenn das durch 'Index' angegebene Objekt nicht existiert, wird zur Laufzeit ein System.FormatException geworfen.

Behandeln von Verstößen

Um einen Verstoß gegen diese Regel zu beheben, geben Sie ein Format Element für jedes Objekt Argument an, und geben Sie für jedes Format Element ein Objekt Argument an.

Wann sollten Warnungen unterdrückt werden?

Unterdrücken Sie keine Warnung dieser Regel.

Konfigurieren des zu analysierenden Codes

Verwenden Sie die folgenden Optionen, um zusätzliche Methoden zum Ausführen dieser Regel zu konfigurieren.

Zusätzliche Methoden zur Zeichenfolge-Formatierung

Sie können Namen von zusätzlichen Zeichenfolge-Formatierungsmethoden konfigurieren, die von dieser Regel analysiert werden sollen Um, zum Beispiel, alle Methoden, die als MyFormat Zeichenfolge-Formatierungsmethoden benannt sind anzugeben, können Sie das folgende Schlüssel-Wert-Paar zu einer .editorconfig Datei in Ihrem Projekt hinzufügen:

dotnet_code_quality.CA2241.additional_string_formatting_methods = MyFormat

Erlaubte Formate für Methodennamen im Optionswert (getrennt durch |):

  • Nur Methodenname (schließt alle Methoden mit dem Namen ein, unabhängig vom enthaltenden Typ oder Namespace).
  • Vollständig qualifizierte Namen des Symbols Dokumentations-ID im Format, mit einem optionalen M: Präfix.

Beispiele:

Optionswert Zusammenfassung
dotnet_code_quality.CA2241.additional_string_formatting_methods = MyFormat Entspricht allen Methoden mit dem Namen MyFormat in der Kompilierung
dotnet_code_quality.CA2241.additional_string_formatting_methods = MyFormat1|MyFormat2 Entspricht allen Methoden mit dem Namen MyFormat1 oder MyFormat2 in der Kompilierung
dotnet_code_quality.CA2241.additional_string_formatting_methods = NS.MyType.MyFormat(ParamType) Entspricht der spezifische Methode MyFormat mit der angegebenen vollqualifizierten Signatur
dotnet_code_quality.CA2241.additional_string_formatting_methods = NS1.MyType1.MyFormat1(ParamType)|NS2.MyType2.MyFormat2(ParamType) Entspricht spezifischen Methoden MyFormat1 und MyFormat2 mit der jeweiligen vollqualifizierten Signatur.

Zusätzliche Zeichenfolge-Formatierungsmethoden automatisch ermitteln

Anstatt eine explizite Liste zusätzlicher Zeichenfolge-Formatierungsmethoden anzugeben, können Sie den Analysator so konfigurieren, dass er automatisch versucht, die Zeichenfolge-Formatierungsmethode zu ermitteln. Diese Option ist standardmäßig deaktiviert. Wenn die Option aktiviert ist, wird jede Methode, die über einen Parameter string formatverfügt, gefolgt von einem params object[] Parameter, als Zeichenfolgen-Formatierungsmethode betrachtet:

dotnet_code_quality.CA2241.try_determine_additional_string_formatting_methods_automatically = true

Beispiel

Das folgende Beispiel zeigt zwei Verstöße gegen die Regel.

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