Tutorial: Escrever um manipulador de interpolação de cadeia de caracteres personalizado

Neste tutorial, irá aprender a:

• Implementar o padrão do manipulador de interpolação de cadeia de caracteres
• Interaja com o recetor em uma operação de interpolação de cordas.
• Adicionar argumentos ao manipulador de interpolação de cadeia de caracteres
• Compreender os novos recursos da biblioteca para interpolação de cadeias de caracteres

Pré-requisitos

Você precisará configurar sua máquina para executar o .NET 6, incluindo o compilador C# 10. O compilador C# 10 está disponível a partir do Visual Studio 2022 ou do SDK do .NET 6.

Este tutorial pressupõe que você esteja familiarizado com C# e .NET, incluindo o Visual Studio ou a CLI do .NET.

Novo esboço

C# 10 adiciona suporte para um manipulador de cadeia de caracteres interpolado personalizado. Um manipulador de cadeia de caracteres interpolado é um tipo que processa a expressão de espaço reservado em uma cadeia de caracteres interpolada. Sem um manipulador personalizado, os espaços reservados são processados de forma semelhante ao String.Format. Cada espaço reservado é formatado como texto e, em seguida, os componentes são concatenados para formar a cadeia de caracteres resultante.

Você pode escrever um manipulador para qualquer cenário em que use informações sobre a cadeia de caracteres resultante. Será utilizado? Quais são as restrições do formato? Alguns exemplos incluem:

• Você pode exigir que nenhuma das cadeias de caracteres resultantes seja maior do que algum limite, como 80 caracteres. Você pode processar as cadeias de caracteres interpoladas para preencher um buffer de comprimento fixo e interromper o processamento assim que esse comprimento de buffer for atingido.
• Você pode ter um formato tabular e cada espaço reservado deve ter um comprimento fixo. Um manipulador personalizado pode impor isso, em vez de forçar todo o código do cliente a estar em conformidade.

Neste tutorial, você criará um manipulador de interpolação de cadeia de caracteres para um dos principais cenários de desempenho: bibliotecas de log. Dependendo do nível de log configurado, o trabalho para construir uma mensagem de log não é necessário. Se o registro em log estiver desativado, o trabalho para construir uma cadeia de caracteres a partir de uma expressão de cadeia de caracteres interpolada não será necessário. A mensagem nunca é impressa, portanto, qualquer concatenação de cadeia de caracteres pode ser ignorada. Além disso, quaisquer expressões usadas nos espaços reservados, incluindo a geração de rastreamentos de pilha, não precisam ser feitas.

Um manipulador de cadeia de caracteres interpolado pode determinar se a cadeia de caracteres formatada será usada e executar apenas o trabalho necessário se necessário.

Execução inicial

Vamos começar a partir de uma classe básica Logger que suporta diferentes níveis:

public enum LogLevel
{
    Off,
    Critical,
    Error,
    Warning,
    Information,
    Trace
}

public class Logger
{
    public LogLevel EnabledLevel { get; init; } = LogLevel.Error;

    public void LogMessage(LogLevel level, string msg)
    {
        if (EnabledLevel < level) return;
        Console.WriteLine(msg);
    }
}

Isto Logger suporta seis níveis diferentes. Quando uma mensagem não passa pelo filtro de nível de log, não há saída. A API pública para o logger aceita uma cadeia de caracteres (totalmente formatada) como a mensagem. Todo o trabalho para criar a string já foi feito.

Implementar o padrão do manipulador

Esta etapa é criar um manipulador de cadeia de caracteres interpolado que recria o comportamento atual. Um manipulador de cadeia de caracteres interpolado é um tipo que deve ter as seguintes características:

• O System.Runtime.CompilerServices.InterpolatedStringHandlerAttribute aplicado ao tipo.
• Um construtor que tem dois int parâmetros literalLength e formattedCount. (Mais parâmetros são permitidos).
• Um método público AppendLiteral com a assinatura: public void AppendLiteral(string s).
• Um método público AppendFormatted genérico com a assinatura: public void AppendFormatted<T>(T t).

Internamente, o construtor cria a cadeia de caracteres formatada e fornece um membro para um cliente recuperar essa cadeia de caracteres. O código a seguir mostra um LogInterpolatedStringHandler tipo que atende a esses requisitos:

[InterpolatedStringHandler]
public ref struct LogInterpolatedStringHandler
{
    // Storage for the built-up string
    StringBuilder builder;

    public LogInterpolatedStringHandler(int literalLength, int formattedCount)
    {
        builder = new StringBuilder(literalLength);
        Console.WriteLine($"\tliteral length: {literalLength}, formattedCount: {formattedCount}");
    }

    public void AppendLiteral(string s)
    {
        Console.WriteLine($"\tAppendLiteral called: {{{s}}}");
        
        builder.Append(s);
        Console.WriteLine($"\tAppended the literal string");
    }

    public void AppendFormatted<T>(T t)
    {
        Console.WriteLine($"\tAppendFormatted called: {{{t}}} is of type {typeof(T)}");

        builder.Append(t?.ToString());
        Console.WriteLine($"\tAppended the formatted object");
    }

    internal string GetFormattedText() => builder.ToString();
}

Agora você pode adicionar uma sobrecarga à LogMessage classe Logger para tentar seu novo manipulador de cadeia de caracteres interpolada:

public void LogMessage(LogLevel level, LogInterpolatedStringHandler builder)
{
    if (EnabledLevel < level) return;
    Console.WriteLine(builder.GetFormattedText());
}

Você não precisa remover o método original LogMessage , o compilador vai preferir um método com um parâmetro manipulador interpolado sobre um método com um string parâmetro quando o argumento é uma expressão de cadeia de caracteres interpolada.

Você pode verificar se o novo manipulador é invocado usando o seguinte código como o programa principal:

var logger = new Logger() { EnabledLevel = LogLevel.Warning };
var time = DateTime.Now;

logger.LogMessage(LogLevel.Error, $"Error Level. CurrentTime: {time}. This is an error. It will be printed.");
logger.LogMessage(LogLevel.Trace, $"Trace Level. CurrentTime: {time}. This won't be printed.");
logger.LogMessage(LogLevel.Warning, "Warning Level. This warning is a string, not an interpolated string expression.");

A execução do aplicativo produz uma saída semelhante ao seguinte texto:

        literal length: 65, formattedCount: 1
        AppendLiteral called: {Error Level. CurrentTime: }
        Appended the literal string
        AppendFormatted called: {10/20/2021 12:19:10 PM} is of type System.DateTime
        Appended the formatted object
        AppendLiteral called: {. This is an error. It will be printed.}
        Appended the literal string
Error Level. CurrentTime: 10/20/2021 12:19:10 PM. This is an error. It will be printed.
        literal length: 50, formattedCount: 1
        AppendLiteral called: {Trace Level. CurrentTime: }
        Appended the literal string
        AppendFormatted called: {10/20/2021 12:19:10 PM} is of type System.DateTime
        Appended the formatted object
        AppendLiteral called: {. This won't be printed.}
        Appended the literal string
Warning Level. This warning is a string, not an interpolated string expression.

Rastreando através da saída, você pode ver como o compilador adiciona código para chamar o manipulador e construir a cadeia de caracteres:

• O compilador adiciona uma chamada para construir o manipulador, passando o comprimento total do texto literal na cadeia de caracteres de formato e o número de espaços reservados.
• O compilador adiciona chamadas para AppendLiteral e AppendFormatted para cada seção da cadeia de caracteres literal e para cada espaço reservado.
• O compilador invoca o LogMessage método usando o CoreInterpolatedStringHandler como o argumento.

Finalmente, observe que o último aviso não invoca o manipulador de cadeia de caracteres interpolada. O argumento é um string, de modo que a chamada invoca a outra sobrecarga com um parâmetro string.

Adicionar mais recursos ao manipulador

A versão anterior do manipulador de cadeia de caracteres interpolado implementa o padrão. Para evitar o processamento de todas as expressões de espaço reservado, você precisará de mais informações no manipulador. Nesta seção, você melhorará seu manipulador para que ele faça menos trabalho quando a cadeia de caracteres construída não for gravada no log. Você usa System.Runtime.CompilerServices.InterpolatedStringHandlerArgumentAttribute para especificar um mapeamento entre parâmetros para uma API pública e parâmetros para o construtor de um manipulador. Isso fornece ao manipulador as informações necessárias para determinar se a cadeia de caracteres interpolada deve ser avaliada.

Vamos começar com as alterações no manipulador. Primeiro, adicione um campo para controlar se o manipulador estiver habilitado. Adicione dois parâmetros ao construtor: um para especificar o nível de log para esta mensagem e o outro uma referência ao objeto de log:

private readonly bool enabled;

public LogInterpolatedStringHandler(int literalLength, int formattedCount, Logger logger, LogLevel logLevel)
{
    enabled = logger.EnabledLevel >= logLevel;
    builder = new StringBuilder(literalLength);
    Console.WriteLine($"\tliteral length: {literalLength}, formattedCount: {formattedCount}");
}

Em seguida, use o campo para que o manipulador só acrescente literais ou objetos formatados quando a cadeia de caracteres final for usada:

public void AppendLiteral(string s)
{
    Console.WriteLine($"\tAppendLiteral called: {{{s}}}");
    if (!enabled) return;

    builder.Append(s);
    Console.WriteLine($"\tAppended the literal string");
}

public void AppendFormatted<T>(T t)
{
    Console.WriteLine($"\tAppendFormatted called: {{{t}}} is of type {typeof(T)}");
    if (!enabled) return;

    builder.Append(t?.ToString());
    Console.WriteLine($"\tAppended the formatted object");
}

Em seguida, você precisará atualizar a LogMessage declaração para que o compilador passe os parâmetros adicionais para o construtor do manipulador. Isso é tratado usando o System.Runtime.CompilerServices.InterpolatedStringHandlerArgumentAttribute argumento on the handler:

public void LogMessage(LogLevel level, [InterpolatedStringHandlerArgument("", "level")] LogInterpolatedStringHandler builder)
{
    if (EnabledLevel < level) return;
    Console.WriteLine(builder.GetFormattedText());
}

Este atributo especifica a lista de argumentos para LogMessage esse mapa para os parâmetros que seguem os parâmetros e obrigatórios literalLengthformattedCount . A string vazia (""), especifica o recetor. O compilador substitui o Logger valor do objeto representado por this para o próximo argumento para o construtor do manipulador. O compilador substitui o valor de level para o seguinte argumento. Você pode fornecer qualquer número de argumentos para qualquer manipulador que escrever. Os argumentos que você adiciona são argumentos de cadeia de caracteres.

Você pode executar esta versão usando o mesmo código de teste. Desta vez, você verá os seguintes resultados:

        literal length: 65, formattedCount: 1
        AppendLiteral called: {Error Level. CurrentTime: }
        Appended the literal string
        AppendFormatted called: {10/20/2021 12:19:10 PM} is of type System.DateTime
        Appended the formatted object
        AppendLiteral called: {. This is an error. It will be printed.}
        Appended the literal string
Error Level. CurrentTime: 10/20/2021 12:19:10 PM. This is an error. It will be printed.
        literal length: 50, formattedCount: 1
        AppendLiteral called: {Trace Level. CurrentTime: }
        AppendFormatted called: {10/20/2021 12:19:10 PM} is of type System.DateTime
        AppendLiteral called: {. This won't be printed.}
Warning Level. This warning is a string, not an interpolated string expression.

Você pode ver que os AppendLiteral métodos e AppendFormat estão sendo chamados, mas eles não estão fazendo nenhum trabalho. O manipulador determinou que a cadeia de caracteres final não será necessária, portanto, o manipulador não a cria. Há ainda algumas melhorias a fazer.

Primeiro, você pode adicionar uma sobrecarga que AppendFormatted restringe o argumento a um tipo que implementa System.IFormattable. Essa sobrecarga permite que os chamadores adicionem cadeias de caracteres de formato nos espaços reservados. Ao fazer essa alteração, vamos também alterar o tipo de retorno dos outros AppendFormatted e AppendLiteral métodos, de void para bool (se qualquer um desses métodos tiver diferentes tipos de retorno, então você receberá um erro de compilação). Essa mudança permite um curto-circuito. Os métodos retornam false para indicar que o processamento da expressão de cadeia de caracteres interpolada deve ser interrompido. O retorno true indica que deve continuar. Neste exemplo, você está usando-o para parar o processamento quando a cadeia de caracteres resultante não é necessária. O curto-circuito suporta ações mais refinadas. Você pode parar de processar a expressão quando ela atingir um determinado comprimento, para oferecer suporte a buffers de comprimento fixo. Ou alguma condição pode indicar que os elementos restantes não são necessários.

public void AppendFormatted<T>(T t, string format) where T : IFormattable
{
    Console.WriteLine($"\tAppendFormatted (IFormattable version) called: {t} with format {{{format}}} is of type {typeof(T)},");

    builder.Append(t?.ToString(format, null));
    Console.WriteLine($"\tAppended the formatted object");
}

Com essa adição, você pode especificar cadeias de caracteres de formato em sua expressão de cadeia de caracteres interpolada:

var time = DateTime.Now;

logger.LogMessage(LogLevel.Error, $"Error Level. CurrentTime: {time}. The time doesn't use formatting.");
logger.LogMessage(LogLevel.Error, $"Error Level. CurrentTime: {time:t}. This is an error. It will be printed.");
logger.LogMessage(LogLevel.Trace, $"Trace Level. CurrentTime: {time:t}. This won't be printed.");

A :t primeira mensagem especifica o "formato de tempo curto" para a hora atual. O exemplo anterior mostrou uma das sobrecargas para o AppendFormatted método que você pode criar para seu manipulador. Não é necessário especificar um argumento genérico para o objeto que está sendo formatado. Você pode ter maneiras mais eficientes de converter tipos criados em cadeia de caracteres. Você pode escrever sobrecargas desses tipos em vez de AppendFormatted um argumento genérico. O compilador escolherá a melhor sobrecarga. O tempo de execução usa essa técnica para converter System.Span<T> em saída de cadeia de caracteres. Você pode adicionar um parâmetro inteiro para especificar o alinhamento da saída, com ou sem um IFormattablearquivo . O System.Runtime.CompilerServices.DefaultInterpolatedStringHandler que acompanha o .NET 6 contém nove sobrecargas de AppendFormatted para diferentes usos. Você pode usá-lo como uma referência ao criar um manipulador para seus propósitos.

Execute o exemplo agora e você verá que, para a Trace mensagem, apenas a primeira AppendLiteral é chamada:

        literal length: 60, formattedCount: 1
        AppendLiteral called: Error Level. CurrentTime:
        Appended the literal string
        AppendFormatted called: 10/20/2021 12:18:29 PM is of type System.DateTime
        Appended the formatted object
        AppendLiteral called: . The time doesn't use formatting.
        Appended the literal string
Error Level. CurrentTime: 10/20/2021 12:18:29 PM. The time doesn't use formatting.
        literal length: 65, formattedCount: 1
        AppendLiteral called: Error Level. CurrentTime:
        Appended the literal string
        AppendFormatted (IFormattable version) called: 10/20/2021 12:18:29 PM with format {t} is of type System.DateTime,
        Appended the formatted object
        AppendLiteral called: . This is an error. It will be printed.
        Appended the literal string
Error Level. CurrentTime: 12:18 PM. This is an error. It will be printed.
        literal length: 50, formattedCount: 1
        AppendLiteral called: Trace Level. CurrentTime:
Warning Level. This warning is a string, not an interpolated string expression.

Você pode fazer uma atualização final no construtor do manipulador que melhora a eficiência. O manipulador pode adicionar um parâmetro final out bool . Definir esse parâmetro para false indicar que o manipulador não deve ser chamado para processar a expressão de cadeia de caracteres interpolada:

public LogInterpolatedStringHandler(int literalLength, int formattedCount, Logger logger, LogLevel level, out bool isEnabled)
{
    isEnabled = logger.EnabledLevel >= level;
    Console.WriteLine($"\tliteral length: {literalLength}, formattedCount: {formattedCount}");
    builder = isEnabled ? new StringBuilder(literalLength) : default!;
}

Essa alteração significa que você pode remover o enabled campo. Em seguida, você pode alterar o tipo de retorno de AppendLiteral e AppendFormatted para void. Agora, ao executar o exemplo, você verá a seguinte saída:

        literal length: 60, formattedCount: 1
        AppendLiteral called: Error Level. CurrentTime:
        Appended the literal string
        AppendFormatted called: 10/20/2021 12:19:10 PM is of type System.DateTime
        Appended the formatted object
        AppendLiteral called: . The time doesn't use formatting.
        Appended the literal string
Error Level. CurrentTime: 10/20/2021 12:19:10 PM. The time doesn't use formatting.
        literal length: 65, formattedCount: 1
        AppendLiteral called: Error Level. CurrentTime:
        Appended the literal string
        AppendFormatted (IFormattable version) called: 10/20/2021 12:19:10 PM with format {t} is of type System.DateTime,
        Appended the formatted object
        AppendLiteral called: . This is an error. It will be printed.
        Appended the literal string
Error Level. CurrentTime: 12:19 PM. This is an error. It will be printed.
        literal length: 50, formattedCount: 1
Warning Level. This warning is a string, not an interpolated string expression.

A única saída quando LogLevel.Trace foi especificada é a saída do construtor. O manipulador indicou que ele não está habilitado, portanto, nenhum dos Append métodos foi invocado.

Este exemplo ilustra um ponto importante para manipuladores de cadeia de caracteres interpolados, especialmente quando bibliotecas de log são usadas. Quaisquer efeitos secundários nos marcadores de posição podem não ocorrer. Adicione o seguinte código ao seu programa principal e veja esse comportamento em ação:

int index = 0;
int numberOfIncrements = 0;
for (var level = LogLevel.Critical; level <= LogLevel.Trace; level++)
{
    Console.WriteLine(level);
    logger.LogMessage(level, $"{level}: Increment index a few times {index++}, {index++}, {index++}, {index++}, {index++}");
    numberOfIncrements += 5;
}
Console.WriteLine($"Value of index {index}, value of numberOfIncrements: {numberOfIncrements}");

Você pode ver que a index variável é incrementada cinco vezes a cada iteração do loop. Como os espaços reservados são avaliados apenas para Critical, Error e Warning níveis, não para Information e Trace, o valor final de index não corresponde à expectativa:

Critical
Critical: Increment index a few times 0, 1, 2, 3, 4
Error
Error: Increment index a few times 5, 6, 7, 8, 9
Warning
Warning: Increment index a few times 10, 11, 12, 13, 14
Information
Trace
Value of index 15, value of numberOfIncrements: 25

Os manipuladores de cadeia de caracteres interpolados fornecem maior controle sobre como uma expressão de cadeia de caracteres interpolada é convertida em uma cadeia de caracteres. A equipe de tempo de execução do .NET já usou esse recurso para melhorar o desempenho em várias áreas. Você pode usar o mesmo recurso em suas próprias bibliotecas. Para explorar mais, veja o System.Runtime.CompilerServices.DefaultInterpolatedStringHandler. Ele fornece uma implementação mais completa do que você construiu aqui. Você verá muito mais sobrecargas que são possíveis para os Append métodos.