WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / C#

Benutzerdefinierte Formatierung in .NET: Anbieter, Formatierer und Typ

Unterscheide drei Aufgaben beim Formatieren: einen Dienst finden, ein Formatelement abfangen und Text durch den Typ des Werts erzeugen.

Version: C# 12 and .NET 8; later runtimes may add compatible features

Syntax

C# 12 / .NET 8, namespace System
IFormatProvider: object? GetFormat(Type? formatType);
ICustomFormatter: string Format(string? format, object? arg, IFormatProvider? formatProvider);
IFormattable: string ToString(string? format, IFormatProvider? formatProvider);
Composite formatting: string.Format(provider, "{0:code}", value)
Direct call: ((IFormattable)value).ToString("G", provider)

In C# 12 und .NET 8 liegen alle drei Schnittstellen in System. Die Überladung von string.Format mit Formatanbieter ruft IFormatProvider.GetFormat(Type?) mit typeof(ICustomFormatter) auf, nicht mit dem Typ des zu formatierenden Werts. Der Anbieter liefert einen Dienst des angeforderten Typs oder null. Implementiert er den Dienst selbst, kann er this zurückgeben. Der gefundene Formatierer wird innerhalb dieses Aufrufs wiederverwendet.

Für {0:F2} erhält ICustomFormatter.Format "F2", das Argument mit dem Index 0 und den Anbieter. In {0} fehlt der Formatcode, deshalb erhält die Methode null. Jeder zurückgegebene Text, auch "", schließt die Formatierung des Elements ab. Bei null setzt diese Überladung von string.Format die normale Formatierung fort. Das ! in null! unterdrückt nur eine Nullbarkeitswarnung: Trotz des Rückgabetyps string wird null zurückgegeben.

Fehlt der benutzerdefinierte Formatierer oder übernimmt er das Element nicht, kann string.Format in .NET 8 zuerst ISpanFormattable.TryFormat versuchen. Wird dieser Schritt übersprungen oder gibt TryFormat false zurück, wird ein Argument ungleich null, das IFormattable implementiert, über IFormattable.ToString(format, provider) formatiert. Für andere Argumente ungleich null wird das parameterlose ToString() ohne Formatcode verwendet. Erreicht ein null-Argument die normale Formatierung, wird es vor dem Auffüllen zur Ausrichtung als leere Zeichenfolge behandelt. Implementiere "G" und null als allgemeines Format. Ein Typ kann bei einem nicht unterstützten Code FormatException auslösen; string.Format kann dieselbe Ausnahme unabhängig davon auslösen, etwa bei einem Index außerhalb der Argumentliste.

Ein direkter Aufruf von ToString mit zwei Argumenten ruft ICustomFormatter nicht automatisch auf. Der Typ kann den Anbieter trotzdem nutzen, etwa um über GetFormat ein NumberFormatInfo oder ein DateTimeFormatInfo abzurufen. Rufe in Format nicht erneut string.Format mit demselben Anbieter, Argument und Code auf: Das kann denselben Formatierer erneut aufrufen.

Beispiele

#nullable enable
using System;
using System.Globalization;

var provider = new ReadingFormatProvider();
var reading = new Voltage(12.5m);
Console.WriteLine(string.Format(provider, "{0:bracket} | {0:F2} | {0}", reading));

sealed class ReadingFormatProvider : IFormatProvider, ICustomFormatter
{
    public object? GetFormat(Type? formatType) =>
        formatType == typeof(ICustomFormatter)
            ? this
            : CultureInfo.InvariantCulture.GetFormat(formatType);

    public string Format(string? format, object? arg, IFormatProvider? formatProvider)
    {
        if (format == "bracket" && arg is Voltage voltage)
            return "[" + voltage.ToString("F2", formatProvider) + "]";

        return null!; // string.Format continues with ordinary formatting.
    }
}

sealed class Voltage(decimal volts) : IFormattable
{
    public override string ToString() => ToString("G", null);

    public string ToString(string? format, IFormatProvider? formatProvider) =>
        (format switch
        {
            null or "G" => volts.ToString("G", formatProvider),
            "F2" => volts.ToString("F2", formatProvider),
            _ => throw new FormatException($"Unsupported voltage format: {format}")
        }) + " V";
}

Ergebnis

[12.50 V] | 12.50 V | 12.5 V

Der Formatierer verarbeitet `bracket` für `Voltage`, indem er `ToString("F2", formatProvider)` direkt aufruft und eckige Klammern ergänzt. Die anderen beiden Elemente werden über `Voltage.ToString` formatiert. Der Anbieter leitet Anfragen nach Kulturdaten an `CultureInfo.InvariantCulture` weiter, daher ist das Dezimaltrennzeichen ein Punkt.

Zugehörige Lektionen

  • C# · Lektion 33 · Fortgeschritten · Version: 3

Quellen