WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / C#

ICustomFormatter.Format — benutzerdefinierte Wertformatierung

ICustomFormatter.Format ermöglicht einem Formatierungsanbieter, die Textdarstellung eines Werts festzulegen, ohne dessen Typ zu ändern. Die Methode arbeitet mit IFormatProvider und Methoden wie string.Format; eine Implementierung sollte auch gewöhnliche Formate und null behandeln.

Version: .NET 10; repository net10.0 and LangVersion=preview; feature versions require per-entry verification

Syntax

string Format(string? format, object? arg, IFormatProvider? formatProvider);

ICustomFormatter.Format im Namespace System ist ein Rückruf, der bei der benutzerdefinierten Formatierung verwendet wird. Anders als IFormattable, das vom formatierten Typ implementiert wird, können Sie damit Regeln außerhalb dieses Typs festlegen. Die API ist in .NET 10 verfügbar; sie ist weder neu in dieser Version noch eine Funktion, die LangVersion=preview erfordert.

Übergeben Sie string.Format oder StringBuilder.AppendFormat einen IFormatProvider. Der Mechanismus fragt mit GetFormat(typeof(ICustomFormatter)) nach einem Formatter. Eine Klasse kann beide Schnittstellen implementieren und this zurückgeben. Anschließend wird Format für jedes Formatelement aufgerufen: Bei {0:tag} erhält die Methode "tag" als format, und arg ist das Argument am Index 0. Ohne Formatbezeichner ist format gleich null; formatProvider bezeichnet den Anbieter des Formatierungsdienstes.

Behandeln Sie Ihre benutzerdefinierten Kombinationen aus Typ und Format und leiten Sie andere Fälle an IFormattable.ToString(format, provider) oder an die parameterlose Methode ToString() weiter. Geben Sie für arg == null eine leere Zeichenfolge zurück. Ein ungültiges Format, das an die Standardformatierung weitergegeben wird, kann FormatException auslösen; ein benutzerdefinierter Formatter sollte diesen Fehler nicht unüberlegt verbergen.

Das Beispiel erkennt "tag" nur bei int. Für andere Werte verwendet es ausdrücklich CultureInfo.InvariantCulture, statt sich auf die aktuelle Kultur oder den Parameter formatProvider zu verlassen. Daher ergibt F2 den Wert 12.50, und bei null bleiben die Klammern leer.

Beispiele

#nullable enable
using System;
using System.Globalization;

Console.WriteLine(string.Format(new LabelFormatter(),
    "{0:tag} | {1:F2} | [{2}]", 42, 12.5m, (object?)null));

sealed class LabelFormatter : IFormatProvider, ICustomFormatter
{
    public object? GetFormat(Type? formatType) =>
        formatType == typeof(ICustomFormatter) ? this : null;

    public string Format(string? format, object? arg,
        IFormatProvider? formatProvider)
    {
        if (format == "tag" && arg is int number)
            return "ID-" + number.ToString("D4", CultureInfo.InvariantCulture);

        return arg switch
        {
            null => string.Empty,
            IFormattable formattable =>
                formattable.ToString(format, CultureInfo.InvariantCulture) ?? string.Empty,
            _ => arg.ToString() ?? string.Empty
        };
    }
}

Ergebnis

ID-0042 | 12.50 | []

Der angezeigte Code und das angegebene Ergebnis wurden in einer isolierten Umgebung mit der im Prüfnachweis für genau diese Version dokumentierten Methode verifiziert.

Quellen