Interpolação de cadeia de caracteres em C#

2025-05-06

Este tutorial mostra como usar a interpolação de cadeia de caracteres para formatar e incluir resultados de expressão em uma cadeia de caracteres de resultado. Os exemplos pressupõem que você esteja familiarizado com conceitos básicos de C# e formatação de tipo .NET. Para obter mais informações sobre tipos de formatação no .NET, consulte Tipos de formatação no .NET.

Introdução

Para identificar uma literal de cadeia de caracteres como uma cadeia de caracteres interpolada, preceda-o com o símbolo $. Você pode inserir qualquer expressão C# válida que retorne um valor em uma cadeia de caracteres interpolada. No exemplo a seguir, assim que uma expressão é avaliada, seu resultado é convertido em uma cadeia de caracteres e incluído em uma cadeia de caracteres de resultado:

double a = 3;
double b = 4;
Console.WriteLine($"Area of the right triangle with legs of {a} and {b} is {0.5 * a * b}");
Console.WriteLine($"Length of the hypotenuse of the right triangle with legs of {a} and {b} is {CalculateHypotenuse(a, b)}");
double CalculateHypotenuse(double leg1, double leg2) => Math.Sqrt(leg1 * leg1 + leg2 * leg2);
// Output:
// Area of the right triangle with legs of 3 and 4 is 6
// Length of the hypotenuse of the right triangle with legs of 3 and 4 is 5

Como mostra o exemplo, você inclui uma expressão em uma cadeia de caracteres interpolada colocando-a com chaves:

{<interpolationExpression>}

Cadeias de caracteres interpoladas dão suporte a todos os recursos do recurso de formatação de composição de cadeia de caracteres . Isso os torna uma alternativa mais legível ao uso do String.Format método. Cada cadeia de caracteres interpolada deve ter:

Um literal de cadeia de caracteres que começa com o $ caractere antes de seu caractere de aspas de abertura. Não pode haver espaços entre o $ símbolo e o caractere de aspas.
Uma ou mais expressões de interpolação. Você indica uma expressão de interpolação com uma chave de abertura e fechamento ({ e }). Você pode colocar qualquer expressão C# que retorna um valor (incluindo null) dentro das chaves.

O C# avalia a expressão entre os caracteres e { as } seguintes regras:

Se a expressão de interpolação for avaliada como null, uma cadeia de caracteres vazia ("" ou String.Empty) será usada.
Se a expressão de interpolação não for avaliada null, normalmente o ToString método do tipo de resultado será chamado.

Como especificar uma cadeia de caracteres de formato para uma expressão de interpolação

Para especificar uma cadeia de caracteres de formato que seja compatível com o tipo do resultado da expressão, siga a expressão de interpolação com um dois-pontos (":") seguido pela cadeia de formato.

{<interpolationExpression>:<formatString>}

O exemplo a seguir mostra como especificar cadeias de caracteres de formato padrão e personalizado para expressões que produzem resultados numéricos e de data e hora:

var date = new DateTime(1731, 11, 25);
Console.WriteLine($"On {date:dddd, MMMM dd, yyyy} L. Euler introduced the letter e to denote {Math.E:F5}.");
// Output:
// On Sunday, November 25, 1731 L. Euler introduced the letter e to denote 2.71828.

Para obter mais informações, consulte a seção Componente de cadeia de caracteres de formato do artigo Formatação composta.

Como controlar a largura do campo e o alinhamento da expressão de interpolação formatada

Para especificar a largura mínima do campo e o alinhamento do resultado da expressão formatada, siga a expressão de interpolação com uma vírgula (") e a expressão constante:

{<interpolationExpression>,<width>}

O exemplo de código a seguir usa a largura mínima do campo para criar uma saída tabular:

var titles = new Dictionary<string, string>()
{
    ["Doyle, Arthur Conan"] = "Hound of the Baskervilles, The",
    ["London, Jack"] = "Call of the Wild, The",
    ["Shakespeare, William"] = "Tempest, The"
};

Console.WriteLine("Author and Title List");
Console.WriteLine();
Console.WriteLine($"|{"Author",-25}|{"Title",30}|");
foreach (var title in titles)
{
    Console.WriteLine($"|{title.Key,-25}|{title.Value,30}|");
}
// Output:
// Author and Title List
// 
// |Author                   |Title                          |
// |Doyle, Arthur Conan      |Hound of the Baskervilles, The |
// |London, Jack             |         Call of the Wild, The |
// |Shakespeare, William     |                  Tempest, The |

Se o valor da largura for positivo, o resultado da expressão formatada será alinhado à direita; se negativo, é alinhado à esquerda. Remova os - sinais antes do especificador de largura e execute o exemplo novamente para ver os resultados.

Se você precisar especificar a largura e uma cadeia de caracteres de formato, comece com o componente de largura:

{<interpolationExpression>,<width>:<formatString>}

O exemplo a seguir mostra como especificar largura e alinhamento e usa caracteres de pipe ("|") para delimitar campos de texto:

const int NameAlignment = -9;
const int ValueAlignment = 7;
double a = 3;
double b = 4;
Console.WriteLine($"Three classical Pythagorean means of {a} and {b}:");
Console.WriteLine($"|{"Arithmetic",NameAlignment}|{0.5 * (a + b),ValueAlignment:F3}|");
Console.WriteLine($"|{"Geometric",NameAlignment}|{Math.Sqrt(a * b),ValueAlignment:F3}|");
Console.WriteLine($"|{"Harmonic",NameAlignment}|{2 / (1 / a + 1 / b),ValueAlignment:F3}|");
// Output:
// Three classical Pythagorean means of 3 and 4:
// |Arithmetic|  3.500|
// |Geometric|  3.464|
// |Harmonic |  3.429|

Como mostra a saída de exemplo, se o comprimento do resultado da expressão formatada exceder a largura do campo especificada, o valor de largura será ignorado.

Para obter mais informações, consulte a seção Componente de Largura do artigo de formatação composta.

Como usar sequências de escape em uma cadeia de caracteres interpolada

Cadeias de caracteres interpoladas dão suporte a todas as sequências de escape que podem ser usadas em literais de cadeia de caracteres comuns. Para obter mais informações, consulte Sequências de escape de cadeia de caracteres.

Para interpretar sequências de escape literalmente, use um literal de cadeia de caracteres textual. Uma cadeia de caracteres verbatim interpolada começa com os caracteres $ e @. Você pode usar $ e @ em qualquer ordem: ambas $@"..." e @$"..." são cadeias de caracteres verbatim interpoladas válidas.

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

O seguinte exemplo mostra como incluir chaves em uma cadeia de caracteres de resultado e construir uma cadeia de caracteres interpolada textual:

var xs = new int[] { 1, 2, 7, 9 };
var ys = new int[] { 7, 9, 12 };
Console.WriteLine($"Find the intersection of the {{{string.Join(", ",xs)}}} and {{{string.Join(", ",ys)}}} sets.");
// Output:
// Find the intersection of the {1, 2, 7, 9} and {7, 9, 12} sets.

var userName = "Jane";
var stringWithEscapes = $"C:\\Users\\{userName}\\Documents";
var verbatimInterpolated = $@"C:\Users\{userName}\Documents";
Console.WriteLine(stringWithEscapes);
Console.WriteLine(verbatimInterpolated);
// Output:
// C:\Users\Jane\Documents
// C:\Users\Jane\Documents

A partir do C# 11, você pode usar literais de cadeia de caracteres bruta e interpolada.

Como usar um operador `?:` condicional ternário em uma expressão de interpolação

Como os dois-pontos (:) têm um significado especial em um item com uma expressão de interpolação, para usar um operador condicional em uma expressão, coloque-a entre parênteses, como mostra o seguinte exemplo:

var rand = new Random();
for (int i = 0; i < 7; i++)
{
    Console.WriteLine($"Coin flip: {(rand.NextDouble() < 0.5 ? "heads" : "tails")}");
}

Como criar uma cadeia de caracteres de resultado específica a uma cultura com a interpolação de cadeia de caracteres

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.

A partir do .NET 6, você pode usar o método String.Create(IFormatProvider, DefaultInterpolatedStringHandler) para resolve uma cadeia de caracteres interpolada para uma cadeia de caracteres de resultado específica da cultura, como mostra o exemplo a seguir:

var cultures = new System.Globalization.CultureInfo[]
{
    System.Globalization.CultureInfo.GetCultureInfo("en-US"),
    System.Globalization.CultureInfo.GetCultureInfo("en-GB"),
    System.Globalization.CultureInfo.GetCultureInfo("nl-NL"),
    System.Globalization.CultureInfo.InvariantCulture
};
var date = DateTime.Now;
var number = 31_415_926.536;
foreach (var culture in cultures)
{
    var cultureSpecificMessage = string.Create(culture, $"{date,23}{number,20:N3}");
    Console.WriteLine($"{culture.Name,-10}{cultureSpecificMessage}");
}
// Output is similar to:
// en-US       8/27/2023 12:35:31 PM      31,415,926.536
// en-GB         27/08/2023 12:35:31      31,415,926.536
// nl-NL         27-08-2023 12:35:31      31.415.926,536
//               08/27/2023 12:35:31      31,415,926.536

Em versões anteriores do .NET, use a conversão implícita de uma cadeia de caracteres interpolada em uma instância System.FormattableString e chame seu método ToString(IFormatProvider) para criar uma cadeia de caracteres de resultado específica da cultura. O seguinte exemplo mostra como fazer isso:

var cultures = new System.Globalization.CultureInfo[]
{
    System.Globalization.CultureInfo.GetCultureInfo("en-US"),
    System.Globalization.CultureInfo.GetCultureInfo("en-GB"),
    System.Globalization.CultureInfo.GetCultureInfo("nl-NL"),
    System.Globalization.CultureInfo.InvariantCulture
};
var date = DateTime.Now;
var number = 31_415_926.536;
FormattableString message = $"{date,23}{number,20:N3}";
foreach (var culture in cultures)
{
    var cultureSpecificMessage = message.ToString(culture);
    Console.WriteLine($"{culture.Name,-10}{cultureSpecificMessage}");
}
// Output is similar to:
// en-US       8/27/2023 12:35:31 PM      31,415,926.536
// en-GB         27/08/2023 12:35:31      31,415,926.536
// nl-NL         27-08-2023 12:35:31      31.415.926,536
//               08/27/2023 12:35:31      31,415,926.536

Como mostra o exemplo, você pode usar uma FormattableString instância para gerar várias cadeias de caracteres de resultado para várias culturas.

Como criar uma cadeia de caracteres de resultado usando a cultura invariável

A partir do .NET 6, use o método String.Create(IFormatProvider, DefaultInterpolatedStringHandler) para converter uma cadeia de caracteres interpolada em uma cadeia de resultado para InvariantCulture, conforme mostra o exemplo a seguir.

string message = string.Create(CultureInfo.InvariantCulture, $"Date and time in invariant culture: {DateTime.Now}");
Console.WriteLine(message);
// Output is similar to:
// Date and time in invariant culture: 05/17/2018 15:46:24

Em versões anteriores do .NET, juntamente com o FormattableString.ToString(IFormatProvider) método, você pode usar o método estático FormattableString.Invariant , como mostra o exemplo a seguir:

string message = FormattableString.Invariant($"Date and time in invariant culture: {DateTime.Now}");
Console.WriteLine(message);
// Output is similar to:
// Date and time in invariant culture: 05/17/2018 15:46:24

Conclusão

Este tutorial descreve cenários comuns de uso de interpolação de cadeia de caracteres. Para obter mais informações sobre interpolação de cadeia de caracteres, consulte Interpolação de cadeia de caracteres. Para obter mais informações sobre tipos de formatação no .NET, consulte os artigos Tipos de formatação no .NET e Formatação composta.

Compartilhar via