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