Partilhar via

Interpolação de cadeias de caracteres usando $

  • Artigo

O $ caractere identifica uma cadeia de caracteres literal 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 para uma cadeia de caracteres de resultado, o compilador substitui itens com expressões de interpolação pelas representações de cadeia de caracteres dos resultados da expressão.

A interpolação de cadeias de caracteres fornece uma sintaxe mais legível e conveniente para formatar cadeias de caracteres. É mais fácil de ler do que a formatação composta de cadeia de caracteres. O exemplo a seguir usa ambos os recursos para produzir a mesma saída:

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ê pode fazer isso somente se todas as expressões de interpolação dentro da cadeia de caracteres interpolada também forem cadeias constantes.

Estrutura de uma cadeia interpolada

Para identificar um literal de cadeia de caracteres como uma cadeia de caracteres interpolada, coloque-a com o $ símbolo. Não é possível ter nenhum espaço em branco entre o literal $ e o " que inicia uma cadeia de caracteres.

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

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

Os elementos entre parênteses retos são opcionais. A tabela a seguir descreve cada elemento:

Elemento Description
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 constante cujo valor define o número mínimo de caracteres na representação de cadeia de caracteres do resultado da expressão. Se positivo, a representação de cadeia de caracteres está 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 suportada pelo tipo do resultado da expressão. Para obter mais informações, consulte a seção Componente Formatar cadeia de caracteres do artigo Formatação composta.

O exemplo a seguir usa 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 novas linhas podem melhorar a legibilidade de uma expressão envolvendo correspondência de padrões:

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 bruta interpolados

A partir do C# 11, você pode usar uma cadeia de caracteres bruta interpolada literal, 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 incorporar { caracteres na } cadeia de caracteres de resultado, inicie uma cadeia de caracteres bruta interpolada literal com vários $ caracteres. Quando você faz isso, qualquer sequência ou {} caracteres menores do que o número de caracteres é incorporada na cadeia de $ caracteres de resultado. Para incluir qualquer expressão de interpolação dentro dessa cadeia de caracteres, você precisa usar 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 bruto interpolado começa com dois $ caracteres. Você precisa colocar todas as expressões de interpolação entre chaves duplas ({{ e }}). Uma única chave é incorporada em uma cadeia de caracteres de resultado. Se você precisar incorporar caracteres repetidos ou { repetidos } em uma cadeia de caracteres de resultado, use um número adequadamente maior de caracteres para designar uma cadeia de $ caracteres bruta interpolada literal. 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. O exterior { e } são incluídos literalmente na cadeia de caracteres de saída.

Carateres especiais

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

Como os dois pontos (":") têm um significado especial em um item de expressão de interpolação, 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 sequência literal interpolada @ Você pode usar $ e @ em qualquer ordem: ambos $@"..." e @$"..." são strings literais interpoladas válidas. Para obter mais informações sobre cadeias de caracteres literais, consulte os artigos de identificador de cadeia de caracteres e literal.

Formatação específica da cultura

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

Para resolver uma cadeia de caracteres interpolada para uma cadeia de resultados específica da cultura, use o String.Create(IFormatProvider, DefaultInterpolatedStringHandler) método, que está disponível a partir do .NET 6. O exemplo a seguir 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 FormattableString instância. 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 exemplo a seguir 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 formatação personalizada, consulte a seção Formatação personalizada com ICustomFormatter do artigo Tipos de formatação no .NET .

Outros recursos

Se você é novo na interpolação de cadeia de caracteres, consulte o tutorial interativo Interpolação de cadeia de caracteres em C# . Você também pode verificar outra interpolação de cadeia de caracteres no tutorial em C# . Esse tutorial demonstra como usar cadeias de caracteres interpoladas para produzir cadeias de caracteres formatadas.

Compilação de strings 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 interpolado . Um manipulador de cadeia de caracteres interpolado é 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 System.Runtime.CompilerServices.DefaultInterpolatedStringHandlerpelo . Para obter o exemplo de um manipulador de cadeia de caracteres interpolado personalizado, consulte o tutorial Escrever um manipulador de interpolação de cadeia de caracteres personalizado. O uso de um manipulador de cadeia de caracteres interpolado é um cenário avançado, normalmente necessário por motivos de desempenho.

Nota

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 os efeitos colaterais dessas expressões podem não ocorrer.

Se uma cadeia de caracteres interpolada tiver o tipo string, ela normalmente é transformada em uma chamada de método String.Format. O compilador pode substituir String.Format por String.Concat se o comportamento analisado seria equivalente à concatenação.

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

Especificação da linguagem C#

Para obter mais informações, consulte a seção Interpolated string expressions da especificação da linguagem C# e as seguintes novas especificações de recurso:

Consulte também