CA1863: Użyj formatu złożonego

Właściwości	Wartość
Identyfikator reguły	CA1863
Tytuł	Korzystanie z polecenia CompositeFormat
Kategoria	Wydajność
Poprawka powodująca niezgodność lub niezgodność	Niezgodność
Domyślnie włączone na platformie .NET 9	Nie.

Przyczyna

Wywołania String.Format(String, Object[]) kodu lub StringBuilder.AppendFormat(String, Object[]) ciąg static formatu, który nie został buforowany w wystąpieniu CompositeFormat .

Opis reguły

Analizowanie ciągu formatu w czasie wykonywania jest kosztowne. Ta reguła lokalizuje miejsca w kodzie, w których można buforować i używać CompositeFormat wystąpienia jako argumentu do operacji formatowania, zamiast przekazywać oryginalny ciąg formatu. Wystąpienie CompositeFormat analizuje ciąg formatu złożonego podczas jego tworzenia, co oznacza, że formatowanie ciągu "gorąca ścieżka" może być wykonywane znacznie szybciej.

Jak naprawić naruszenia

Utwórz wystąpienie obiektu CompositeFormat przez wywołanie CompositeFormat.Parse(String) i przekazanie go do String.Format(IFormatProvider, CompositeFormat, Object[]) lub StringBuilder.AppendFormat(IFormatProvider, CompositeFormat, Object[]) zamiast oryginalnego ciągu formatu.

Przykład

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

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

W poniższym przykładzie pokazano kod, który naprawia oba naruszenia:

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

Kiedy pomijać ostrzeżenia

Można bezpiecznie pominąć diagnostykę z tej reguły, jeśli wydajność nie jest problemem.

Pomijanie ostrzeżenia

Jeśli chcesz po prostu pominąć pojedyncze naruszenie, dodaj dyrektywy preprocesora do pliku źródłowego, aby wyłączyć, a następnie ponownie włączyć regułę.

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

Aby wyłączyć regułę dla pliku, folderu lub projektu, ustaw jego ważność na none w pliku konfiguracji.

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

Aby uzyskać więcej informacji, zobacz Jak pominąć ostrzeżenia dotyczące analizy kodu.