$ – interpolação de cadeia de caracteres (referência de C#)

O caractere especial $ 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, itens com expressões de interpolação são substituídos pelas representações de cadeia de caracteres dos resultados da expressão. Esse recurso está disponível a partir do C# 6.

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

string 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.

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 $. Você não pode ter nenhum espaço em branco entre o e o que inicia $ 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. A representação de cadeia de null caracteres de é 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 for positiva, a representação de cadeia de caracteres será alinhada à direita; se for negativa, será alinhada à esquerda. Para obter mais informações, consulte Componente de alinhamento.
formatString Uma cadeia de caracteres de formato compatível com o tipo do resultado da expressão. Para obter mais informações, consulte Componente da cadeia de caracteres de formato.

O exemplo a seguir usa os componentes opcionais de formatação descritos acima:

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");
// Expected 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# 10, você pode usar a interpolação de cadeia de caracteres para inicializar uma cadeia de caracteres constante. Todas as expressões usadas para os espaço reservados devem ser cadeias de caracteres constantes. Em outras palavras, cada expressão de interpolação deve ser uma cadeia de caracteres e deve ser uma constante de tempo de compilação.

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 Chaves de escape.

Como os dois-pontos (":") têm 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.");
// Expected output is:
// He asked, "Is your name Horace?", but didn't wait for a reply :-{
// Horace is 34 years old.

Uma cadeia de caracteres textual interpolada começa com $ o caractere seguido pelo caractere @ . Para obter mais informações sobre cadeias de caracteres textual, consulte os artigos de cadeia de caracteres e identificador textual.

Observação

A partir do C# 8.0, você pode usar os tokens e em qualquer ordem: e são cadeias de $ @ $@"..." @$"..." caracteres textual interpoladas válidas. Em versões anteriores do C#, $ o token deve aparecer antes do @ token.

Conversões implícitas e como especificar a IFormatProvider implementação

Há três conversões implícitas de uma cadeia de caracteres interpolada:

  1. Conversão de uma cadeia de caracteres interpolada em uma String instância. A cadeia de caracteres é o resultado da resolução de cadeia de caracteres interpolada. Todos os itens de expressão de interpolação são substituídos por representações de cadeia de caracteres formatadas corretamente de seus resultados. Essa conversão usa o CurrentCulture para formatar os resultados da expressão.

  2. Conversão de uma cadeia de caracteres interpolada em uma instância de FormattableString, que representa uma cadeia de caracteres de formato composto, juntamente com os resultados da expressão a ser formatada. Isso permite criar várias cadeias de caracteres de resultado com conteúdo específico da cultura com base em uma única instância FormattableString. Para fazer isso, chame um dos seguintes métodos:

    O ToString(IFormatProvider) fornece uma implementação definida pelo usuário da interface que dá suporte à IFormatProvider formatação personalizada. Para obter mais informações, consulte a seção Formatação personalizada com ICustomFormatter do artigo Formatação de tipos no .NET.

  3. Conversão de uma cadeia de caracteres interpolada em uma instância IFormattable, que também permite criar várias cadeias de caracteres de resultado com conteúdo específico da cultura com base em uma única instância IFormattable.

O exemplo a seguir usa a conversão implícita em FormattableString para a criação de cadeias de caracteres de resultado específicas de cultura:

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

System.Globalization.CultureInfo.CurrentCulture = System.Globalization.CultureInfo.GetCultureInfo("nl-NL");
string messageInCurrentCulture = message.ToString();

var specificCulture = System.Globalization.CultureInfo.GetCultureInfo("en-IN");
string messageInSpecificCulture = message.ToString(specificCulture);

string messageInInvariantCulture = FormattableString.Invariant(message);

Console.WriteLine($"{System.Globalization.CultureInfo.CurrentCulture,-10} {messageInCurrentCulture}");
Console.WriteLine($"{specificCulture,-10} {messageInSpecificCulture}");
Console.WriteLine($"{"Invariant",-10} {messageInInvariantCulture}");
// Expected 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.

Recursos adicionais

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

Compilação de cadeias de caracteres interpoladas

Se uma cadeia de caracteres interpolada tiver o tipo string, ela normalmente será 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.

A partir do C# 10, quando uma cadeia de caracteres interpolada é usada, o compilador verifica se a 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 personalizado que converte a cadeia de caracteres interpolada em uma cadeia de caracteres. Um manipulador de cadeia de caracteres interpolado é um cenário avançado, normalmente usado por motivos de desempenho. Você pode aprender sobre os requisitos para criar um manipulador de cadeia de caracteres interpolado na especificação de linguagem para melhorias de cadeia de caracteres interpoladas. Você pode criar um seguindo o tutorial do manipulador de cadeia de caracteres interpolado na seção Novidades em C#. No .NET 6, quando você usa uma cadeia de caracteres interpolada para um argumento do tipo , a cadeia de caracteres string interpolada é processada pelo System.Runtime.CompilerServices.DefaultInterpolatedStringHandler .

Observação

Um efeito colateral dos manipuladores de cadeia de caracteres interpolados é que um manipulador personalizado, incluindo , pode não avaliar todas as expressões usadas como espaço reservados na cadeia de caracteres interpolada em todas System.Runtime.CompilerServices.DefaultInterpolatedStringHandler as condições. Isso significa que os efeitos colaterais nessas expressões podem não ocorrer.

Especificação da linguagem C#

Para obter mais informações, consulte a seção cadeias de caracteres interpoladas da especificação da linguagem C#.

Confira também