Compartilhar via

Interpolação de cadeia de caracteres usando $

O caractere $ identifica um literal de cadeia de caracteres como uma cadeia de caracteres interpolada. Uma cadeia de caracteres interpolada é um string literal 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 os itens com as expressões de interpolação pelas representações em cadeia de caracteres dos resultados das expressões.

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.

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>[,<width>][:<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).
width A expressão constante cujo valor define o número mínimo de caracteres na representação em cadeia 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 Width component 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 encapsular qualquer expressão de interpolação dentro desse trecho de texto, 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 incluídos literalmente 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, é possível usar um operador condicional nessa expressã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.

Em .NET 5 e em versões anteriores do .NET, utilize a conversão implícita de uma string interpolada para 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. Esse tutorial demonstra como usar cadeias de caracteres interpoladas para produzir cadeias de caracteres formatadas.

Compilação de cadeias de caracteres interpoladas

O compilador verifica se uma cadeia de caracteres interpolada é atribuída a um tipo que satisfaz o padrão de 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 interpolados é 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 efeitos colaterais dessas expressões podem não ocorrer.

Se uma cadeia de caracteres interpolada tiver o tipo string, ela normalmente será transformada em uma String.Format chamada de método. 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