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

CKTIS / C#

ICustomFormatter.Format — formatação personalizada de valores

ICustomFormatter.Format permite que um fornecedor de formatos controle a representação textual de um valor sem alterar o respetivo tipo. Funciona com IFormatProvider e métodos como string.Format; uma implementação também deve tratar os formatos habituais e null.

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

Sintaxe

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

ICustomFormatter.Format, no espaço de nomes System, é um callback utilizado na formatação personalizada. Ao contrário de IFormattable, implementada pelo tipo a formatar, permite definir regras fora desse tipo. A API está disponível no .NET 10; não é uma novidade dessa versão nem uma funcionalidade que exija LangVersion=preview.

Passe um IFormatProvider a string.Format ou a StringBuilder.AppendFormat. O mecanismo pede um formatador através de GetFormat(typeof(ICustomFormatter)). Uma classe pode implementar ambas as interfaces e devolver this. Em seguida, Format é chamada para cada elemento de formato: em {0:tag}, recebe "tag" como format, e arg é o argumento no índice 0. Sem especificador, format é null; formatProvider identifica o fornecedor do serviço de formatação.

Trate as suas combinações personalizadas de tipo e formato e delegue os restantes casos em IFormattable.ToString(format, provider) ou em ToString() sem parâmetros. Devolva uma cadeia vazia quando arg == null. Um formato inválido encaminhado para a formatação alternativa pode causar FormatException; um formatador personalizado não deve ocultar esse erro sem ponderação.

O exemplo reconhece "tag" apenas para int. Para os outros valores, utiliza explicitamente CultureInfo.InvariantCulture, em vez de depender da cultura atual ou do parâmetro formatProvider. Assim, F2 produz 12.50 e null deixa os parênteses retos vazios.

Exemplos

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

Resultado

ID-0042 | 12.50 | []

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes