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âmetrosliteralLength
eformattedCount
. (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
eAppendFormatted
para cada seção da cadeia de caracteres literal e para cada espaço reservado. - O compilador invoca o
LogMessage
método usando oCoreInterpolatedStringHandler
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 literalLength
formattedCount
. 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.
Comentários
https://aka.ms/ContentUserFeedback.
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja:Submeter e ver comentários