Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / C#

Formatação personalizada em .NET: fornecedor, formatador e tipo

Distingue três contratos de formatação: procurar um serviço, intercetar um item de formato e deixar que o próprio tipo do valor produza o texto.

Versão: C# 12 and .NET 8; later runtimes may add compatible features

Sintaxe

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)

Em C# 12 e .NET 8, as três interfaces pertencem a System. A sobrecarga de string.Format que aceita um fornecedor chama IFormatProvider.GetFormat(Type?) com typeof(ICustomFormatter), não com o tipo do valor a formatar. O fornecedor devolve um serviço do tipo pedido ou null. Pode devolver this se implementar o serviço. O formatador encontrado é reutilizado durante essa chamada.

Para {0:F2}, ICustomFormatter.Format recebe "F2", o argumento de índice zero e o fornecedor. Em {0}, não há código de formato, pelo que o método recebe null. Qualquer cadeia devolvida, mesmo "", conclui a formatação do item. Se devolver null, esta sobrecarga de string.Format prossegue com a formatação normal. O ! em null! apenas suprime um aviso de nulabilidade: o método devolve null apesar de o tipo de retorno ser string.

Se não houver um formatador personalizado ou se este não tratar o item, no .NET 8 string.Format pode tentar primeiro usar ISpanFormattable.TryFormat. Se esse passo for ignorado ou se TryFormat devolver false, um argumento não nulo que implemente IFormattable é formatado por IFormattable.ToString(format, provider). Para os outros argumentos não nulos, é usado ToString() sem parâmetros, que não recebe o código de formato. Um argumento null que chegue à formatação normal é tratado como uma cadeia vazia antes de serem acrescentados eventuais espaços para o alinhamento. Implementa "G" e null como formato geral. Um tipo pode lançar FormatException perante um código não suportado; string.Format pode lançar a mesma exceção de forma independente, por exemplo se o índice estiver fora da lista de argumentos.

Chamar diretamente ToString com dois argumentos não invoca automaticamente ICustomFormatter. O tipo pode, ainda assim, usar o fornecedor para obter, por exemplo, NumberFormatInfo ou DateTimeFormatInfo através de GetFormat. Evita voltar a chamar string.Format dentro de Format com o mesmo fornecedor, argumento e código: podes voltar a entrar no mesmo formatador.

Exemplos

#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";
}

Resultado

[12.50 V] | 12.50 V | 12.5 V

O formatador trata `bracket` para `Voltage`: chama diretamente `ToString("F2", formatProvider)` e acrescenta parênteses retos. Os outros dois itens são tratados por `Voltage.ToString`. O fornecedor delega os pedidos de dados culturais em `CultureInfo.InvariantCulture`, pelo que o separador decimal é um ponto.

Lições relacionadas

  • C# · Lição 33 · Avançado · Versão: 3

Fontes