CA1863: Verwenden von „CompositeFormat“

Eigenschaft	Wert
Regel-ID	CA1863
Titel	Verwenden Sie CompositeFormat
Kategorie	Leistung
Fix führt oder führt nicht zur Unterbrechung	Nicht unterbrechend
Standardmäßig in .NET 8 aktiviert	Nein

Ursache

Der Code ruft String.Format(String, Object[]) oder StringBuilder.AppendFormat(String, Object[]) mit einer static Formatzeichenfolge auf, die nicht in einer CompositeFormat Instanz zwischengespeichert wurde.

Regelbeschreibung

Es ist teuer, eine Formatzeichenfolge zur Laufzeit zu parsen. Diese Regel sucht nach Stellen in Ihrem Code, an denen Sie eine CompositeFormat-Instanz zwischenspeichern und als Argument für einen Formatierungsvorgang verwenden können, anstatt den ursprünglichen Formatierungsstring zu übergeben. Eine CompositeFormat-Instanz analysiert die zusammengesetzte Formatzeichenfolge, wenn sie erstellt wird, was bedeutet, dass der „Hot Path“ der Zeichenfolgenformatierung viel schneller ausgeführt werden kann.

Behandeln von Verstößen

Erstellen Sie eine Instanz von CompositeFormat, indem Sie CompositeFormat.Parse(String) aufrufen, und übergeben Sie diese an String.Format(IFormatProvider, CompositeFormat, Object[]) oder StringBuilder.AppendFormat(IFormatProvider, CompositeFormat, Object[]) anstelle des ursprünglichen Formatzeichenfolge.

Beispiel

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

class C
{
    private static readonly string StaticField = "Format one value: {0}";

    static void Main()
    {
        _ = string.Format(StaticField, 42);

        StringBuilder sb = new();
        sb.AppendFormat(StaticField, 42);
    }
}

Das folgende Beispiel zeigt einen Code, der beide Verstöße behebt:

class C
{
    private static readonly CompositeFormat StaticField = CompositeFormat.Parse("Format one value: {0}");

    static void Main()
    {
        _ = string.Format(null, StaticField, 42);

        StringBuilder sb = new();
        sb.AppendFormat(null, StaticField, 42);
    }
}

Wann sollten Warnungen unterdrückt werden?

Wenn die Leistung keine Rolle spielt, können Sie die Diagnose in dieser Regel unterdrücken.

Unterdrücken einer Warnung

Um nur eine einzelne Verletzung zu unterdrücken, fügen Sie der Quelldatei Präprozessoranweisungen hinzu, um die Regel zu deaktivieren und dann wieder zu aktivieren.

#pragma warning disable CA1863
// The code that's violating the rule is on this line.
#pragma warning restore CA1863

Um die Regel für eine Datei, einen Ordner oder ein Projekt zu deaktivieren, legen Sie den Schweregrad in der Konfigurationsdatei auf none fest.

[*.{cs,vb}]
dotnet_diagnostic.CA1863.severity = none

Weitere Informationen finden Sie unter Vorgehensweise: Unterdrücken von Codeanalyse-Warnungen.