Compartilhar via

Interpolação de cadeia de caracteres usando $

  • Artigo

O caractere $ identifica um literal de cadeia de caracteres como uma cadeia de caracteres interpolada. Uma cadeia de caracteres interpolada é um literal de cadeia de caracteres que pode conter expressões de interpolação. Quando uma cadeia de caracteres interpolada é resolvida em uma cadeia de caracteres de resultado, o compilador substitui itens por expressões de interpolação pelas representações de cadeia de caracteres dos resultados da expressão.

A interpolação de cadeia de caracteres fornece uma sintaxe mais acessível e prática para as cadeias de caracteres de formato. Ela é mais fácil de ler do que a formatação composta de cadeia de caracteres. O exemplo a seguir usa os dois recursos para produzir o mesmo resultado:

var name = "Mark";
var date = DateTime.Now;

// Composite formatting:
Console.WriteLine("Hello, {0}! Today is {1}, it's {2:HH:mm} now.", name, date.DayOfWeek, date);
// String interpolation:
Console.WriteLine($"Hello, {name}! Today is {date.DayOfWeek}, it's {date:HH:mm} now.");
// Both calls produce the same output that is similar to:
// Hello, Mark! Today is Wednesday, it's 19:40 now.

A partir do C# 10, você pode usar uma cadeia de caracteres interpolada para inicializar uma cadeia de caracteres constante. Você só poderá fazer isso se todas as expressões de interpolação dentro da cadeia de caracteres interpolada também forem cadeias de caracteres constantes.

Estrutura de uma cadeia de caracteres interpolada

Para identificar uma literal de cadeia de caracteres como uma cadeia de caracteres interpolada, preceda-o com o símbolo $. Não pode haver nenhum espaço em branco entre o $ e " que iniciam um literal de cadeia de caracteres.

A estrutura de um item com uma expressão de interpolação é da seguinte maneira:

{<interpolationExpression>[,<alignment>][:<formatString>]}

Os elementos entre colchetes são opcionais. A seguinte tabela descreve cada elemento:

Elemento Descrição
interpolationExpression A expressão que produz um resultado a ser formatado. Quando a expressão é null, a saída é a cadeia de caracteres vazia (String.Empty).
alignment A expressão de constante cujo valor define o número mínimo de caracteres da representação de cadeia de caracteres do resultado da expressão. Se positivo, a representação da cadeia de caracteres estará alinhada à direita; se negativo, alinhado à esquerda. Para obter mais informações, consulte a seção Componente de alinhamento do artigo Formatação composta.
formatString Uma cadeia de caracteres de formato compatível com o tipo do resultado da expressão. Para obter mais informações, consulte a seção Componente de cadeia de caracteres de formato do artigo Formatação composta.

O exemplo a seguir usa os componentes de formatação opcionais descritos na tabela anterior:

Console.WriteLine($"|{"Left",-7}|{"Right",7}|");

const int FieldWidthRightAligned = 20;
Console.WriteLine($"{Math.PI,FieldWidthRightAligned} - default formatting of the pi number");
Console.WriteLine($"{Math.PI,FieldWidthRightAligned:F3} - display only three decimal digits of the pi number");
// Output is:
// |Left   |  Right|
//     3.14159265358979 - default formatting of the pi number
//                3.142 - display only three decimal digits of the pi number

A partir do C# 11, você pode usar novas linhas dentro de uma expressão de interpolação para tornar o código da expressão mais legível. O exemplo a seguir mostra como as novas linhas podem melhorar a legibilidade de uma expressão que envolve padrões correspondentes:

string message = $"The usage policy for {safetyScore} is {
    safetyScore switch
    {
        > 90 => "Unlimited usage",
        > 80 => "General usage, with daily safety check",
        > 70 => "Issues must be addressed within 1 week",
        > 50 => "Issues must be addressed within 1 day",
        _ => "Issues must be addressed before continued use",
    }
    }";

Literais de cadeia de caracteres bruta e interpolada

A partir do C# 11, você pode usar um literal de cadeia de caracteres bruta e interpolada, como mostra o exemplo a seguir:

int X = 2;
int Y = 3;

var pointMessage = $"""The point "{X}, {Y}" is {Math.Sqrt(X * X + Y * Y):F3} from the origin""";

Console.WriteLine(pointMessage);
// Output is:
// The point "2, 3" is 3.606 from the origin

Para inserir caracteres { e } na cadeia de caracteres de resultado, inicie um literal de cadeia de caracteres bruta e interpolada com vários caracteres $. Quando você faz isso, qualquer sequência de { ou } caracteres menor que o número de caracteres $ é inserida na cadeia de caracteres de resultado. Para incluir qualquer expressão de interpolação da cadeia de caracteres, você precisa utilizar o mesmo número de chaves que o número de caracteres $, como mostra o exemplo a seguir:

int X = 2;
int Y = 3;

var pointMessage = $$"""{The point {{{X}}, {{Y}}} is {{Math.Sqrt(X * X + Y * Y):F3}} from the origin}""";
Console.WriteLine(pointMessage);
// Output is:
// {The point {2, 3} is 3.606 from the origin}

No exemplo anterior, um literal de cadeia de caracteres bruta e interpolada começa com dois caracteres $. Você precisa colocar todas as expressões de interpolação entre chaves duplas ({{ e }}). Uma chave única é inserida em uma cadeia de caracteres de resultado. Se você precisar inserir caracteres repetidos { ou } em uma cadeia de caracteres de resultado, use um número apropriadamente maior de caracteres $ para designar um literal de cadeia de caracteres bruta e interpolada. Se o literal de cadeia de caracteres tiver mais chaves repetidas do que o número de caracteres $, os caracteres { e } serão agrupados de dentro para fora. No exemplo anterior, o literal The point {{{X}}, {{Y}}} interpreta {{X}} e {{Y}} como expressões interpoladas. Os exteriores { e } são verbatim incluídos na cadeia de caracteres de saída.

Caracteres especiais

Para incluir uma chave, "{" ou "}", no texto produzido por uma cadeia de caracteres interpolada, use duas chaves, "{{" ou "}}". Para obter mais informações, consulte a seção Chaves de escape do artigo Formatação composta.

Como os dois-pontos (":") têm um significado especial em um item de expressão de interpolação, para usar um operador condicional em uma expressão de interpolação. Coloque essa expressão entre parênteses.

O exemplo a seguir mostra como incluir uma chave em uma cadeia de caracteres de resultado. Ele também mostra como usar um operador condicional:

string name = "Horace";
int age = 34;
Console.WriteLine($"He asked, \"Is your name {name}?\", but didn't wait for a reply :-{{");
Console.WriteLine($"{name} is {age} year{(age == 1 ? "" : "s")} old.");
// Output is:
// He asked, "Is your name Horace?", but didn't wait for a reply :-{
// Horace is 34 years old.

Uma cadeia de caracteres verbatim interpolada começa com os caracteres $ e @. Você pode usar $ e @ em qualquer ordem: $@"..." e @$"..." são cadeias de caracteres verbatim interpoladas válidas. Para obter mais informações sobre cadeias de caracteres textuais, confira os artigos cadeia de caracteres e identificador textual.

Formatação específica da cultura

Por padrão, uma cadeia de caracteres interpolada usa a cultura atual definida pela propriedade CultureInfo.CurrentCulture para todas as operações de formatação.

Para resolver uma cadeia de caracteres interpolada em uma cadeia de caracteres de resultado específica da cultura, use o método String.Create(IFormatProvider, DefaultInterpolatedStringHandler), que está disponível a partir do .NET 6. O seguinte exemplo mostra como fazer isso:

double speedOfLight = 299792.458;

System.Globalization.CultureInfo.CurrentCulture = System.Globalization.CultureInfo.GetCultureInfo("nl-NL");
string messageInCurrentCulture = $"The speed of light is {speedOfLight:N3} km/s.";

var specificCulture = System.Globalization.CultureInfo.GetCultureInfo("en-IN");
string messageInSpecificCulture = string.Create(
    specificCulture, $"The speed of light is {speedOfLight:N3} km/s.");

string messageInInvariantCulture = string.Create(
    System.Globalization.CultureInfo.InvariantCulture, $"The speed of light is {speedOfLight:N3} km/s.");

Console.WriteLine($"{System.Globalization.CultureInfo.CurrentCulture,-10} {messageInCurrentCulture}");
Console.WriteLine($"{specificCulture,-10} {messageInSpecificCulture}");
Console.WriteLine($"{"Invariant",-10} {messageInInvariantCulture}");
// Output is:
// nl-NL      The speed of light is 299.792,458 km/s.
// en-IN      The speed of light is 2,99,792.458 km/s.
// Invariant  The speed of light is 299,792.458 km/s.

No .NET 5 e versões anteriores do .NET, use a conversão implícita de uma cadeia de caracteres interpolada em uma instância FormattableString. Em seguida, você pode usar um método de instância FormattableString.ToString(IFormatProvider) ou um método estático FormattableString.Invariant para produzir uma cadeia de caracteres de resultado específica da cultura. O seguinte exemplo mostra como fazer isso:

double speedOfLight = 299792.458;
FormattableString message = $"The speed of light is {speedOfLight:N3} km/s.";

var specificCulture = System.Globalization.CultureInfo.GetCultureInfo("en-IN");
string messageInSpecificCulture = message.ToString(specificCulture);
Console.WriteLine(messageInSpecificCulture);
// Output:
// The speed of light is 2,99,792.458 km/s.

string messageInInvariantCulture = FormattableString.Invariant(message);
Console.WriteLine(messageInInvariantCulture);
// Output is:
// The speed of light is 299,792.458 km/s.

Para obter mais informações sobre a formatação personalizada, confira a seção Formatação personalizada com ICustomFormatter do artigo Tipos de formatação no .NET.

Outros recursos

Se não estiver familiarizado com a interpolação de cadeia de caracteres, confira o tutorial Interpolação de cadeia de caracteres no C# Interativo. Você também pode verificar outro tutorial Interpolação de cadeia de caracteres no C#. Esse tutorial demonstra como usar cadeias de caracteres interpoladas para produzir cadeias de caracteres formatadas.

Compilação de cadeias de caracteres interpoladas

A partir do C# 10 e .NET 6, o compilador verificar se uma cadeia de caracteres interpolada é atribuída a um tipo que atende ao padrão do manipulador de cadeia de caracteres interpolada. Um manipulador de cadeia de caracteres interpolada é um tipo que converte a cadeia de caracteres interpolada em uma cadeia de caracteres de resultado. Quando uma cadeia de caracteres interpolada tem o tipo string, ela é processada pelo System.Runtime.CompilerServices.DefaultInterpolatedStringHandler. Para ver o exemplo de um manipulador personalizado de cadeia de caracteres interpolada, consulte o tutorial Gravar um manipulador personalizado de cadeia de caracteres interpolada. O uso de um manipulador de cadeia de caracteres interpolada é um cenário avançado, normalmente exigido por motivos de desempenho.

Observação

Um efeito colateral dos manipuladores de cadeia de caracteres interpolada é que um manipulador personalizado, incluindo System.Runtime.CompilerServices.DefaultInterpolatedStringHandler, pode não avaliar todas as expressões de interpolação dentro da cadeia de caracteres interpolada em todas as condições. Isso significa que os efeitos colaterais dessas expressões podem não ocorrer.

Antes do C# 10, se uma cadeia de caracteres interpolada tivesse o tipo string, normalmente ela seria transformada em uma chamada de método String.Format. O compilador pode substituir String.Format por String.Concat se o comportamento analisado for equivalente à concatenação.

Se uma cadeia de caracteres interpolada tiver o tipo IFormattable ou FormattableString, o compilador gerará uma chamada para o método FormattableStringFactory.Create.

Especificação da linguagem C#

Para obter mais informações, confira a seção Expressões de cadeia de caracteres interpolada da Especificação da linguagem C# e as seguintes especificações de recurso novo:

Confira também