$ - interpolação de cordas (referência C#)$ - string interpolation (C# reference)

O caractere especial $ identifica um literal de cadeia de caracteres como uma cadeia de caracteres interpolada.The $ special character identifies a string literal as an interpolated string. Uma cadeia de caracteres interpolada é um literal de cadeia de caracteres que pode conter expressões de interpolação.An interpolated string is a string literal that might contain interpolation expressions. 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.When an interpolated string is resolved to a result string, items with interpolation expressions are replaced by the string representations of the expression results. Este recurso está disponível a partir de C# 6.This feature is available starting with C# 6.

A interpolação de cadeia de caracteres fornece uma sintaxe mais legível e conveniente para criar cadeias de caracteres formatadas do que o recurso de formatação composta de cadeia de caracteres.String interpolation provides a more readable and convenient syntax to create formatted strings than a string composite formatting feature. O exemplo a seguir usa os dois recursos para produzir o mesmo resultado:The following example uses both features to produce the same output:

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 interpoladaStructure of an interpolated string

Para identificar uma literal de cadeia de caracteres como uma cadeia de caracteres interpolada, preceda-o com o símbolo $.To identify a string literal as an interpolated string, prepend it with the $ symbol. Não pode haver nenhum espaço em branco entre o $ e " que iniciam um literal de cadeia de caracteres.You cannot have any white space between the $ and the " that starts a string literal.

A estrutura de um item com uma expressão de interpolação é da seguinte maneira:The structure of an item with an interpolation expression is as follows:

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

Os elementos entre colchetes são opcionais.Elements in square brackets are optional. A seguinte tabela descreve cada elemento:The following table describes each element:

ElementoElement DescriçãoDescription
interpolationExpression A expressão que produz um resultado a ser formatado.The expression that produces a result to be formatted. Representação null de String.Emptycordas de é .String representation of null is String.Empty.
alignment A expressão constante cujo valor define o número mínimo de caracteres na representação de seqüência do resultado da expressão.The constant expression whose value defines the minimum number of characters in the string representation of the expression result. Se for positiva, a representação de cadeia de caracteres será alinhada à direita; se for negativa, será alinhada à esquerda.If positive, the string representation is right-aligned; if negative, it's left-aligned. Para obter mais informações, consulte Componente de alinhamento.For more information, see Alignment Component.
formatString Uma cadeia de caracteres de formato compatível com o tipo do resultado da expressão.A format string that is supported by the type of the expression result. Para obter mais informações, consulte Componente da cadeia de caracteres de formato.For more information, see Format String Component.

O exemplo a seguir usa os componentes opcionais de formatação descritos acima:The following example uses optional formatting components described above:

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

Caracteres especiaisSpecial characters

Para incluir uma chave, "{" ou "}", no texto produzido por uma cadeia de caracteres interpolada, use duas chaves, "{{" ou "}}".To include a brace, "{" or "}", in the text produced by an interpolated string, use two braces, "{{" or "}}". Para obter mais informações, consulte Chaves de escape.For more information, see Escaping Braces.

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.As the colon (":") has special meaning in an interpolation expression item, in order to use a conditional operator in an interpolation expression, enclose that expression in parentheses.

O seguinte exemplo mostra como incluir uma chave em uma cadeia de caracteres de resultado e como usar um operador condicional em uma expressão de interpolação:The following example shows how to include a brace in a result string and how to use a conditional operator in an interpolation expression:

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 seqüência de caracteres $ interpolada @ começa com o personagem seguido pelo personagem.An interpolated verbatim string starts with the $ character followed by the @ character. Para obter mais informações sobre cadeias de caracteres textuais, confira os tópicos cadeia de caracteres e identificador textual.For more information about verbatim strings, see the string and verbatim identifier topics.

Observação

Começando com C# 8.0, $ você @ pode usar os tokens em qualquer ordem: ambos $@"..." e @$"..." são cadeias verbatim interpoladas válidas.Starting with C# 8.0, you can use the $ and @ tokens in any order: both $@"..." and @$"..." are valid interpolated verbatim strings. Nas versões C# anteriores, $ @ o token deve aparecer antes do token.In earlier C# versions, the $ token must appear before the @ token.

Conversões implícitas e IFormatProvider como especificar a implementaçãoImplicit conversions and how to specify IFormatProvider implementation

Há três conversões implícitas de uma cadeia de caracteres interpolada:There are three implicit conversions from an interpolated string:

  1. Conversão de uma cadeia de caracteres interpolada uma instância String, que é a resolução da cadeia de caracteres interpolada com os itens da expressão de interpolação que estão sendo substituídos pelas representações de seus resultados da cadeia de caracteres corretamente formatada.Conversion of an interpolated string to a String instance that is the result of interpolated string resolution with interpolation expression items being replaced with the properly formatted string representations of their results. Esta conversão CurrentCulture usa os resultados de expressão para formatar.This conversion uses the CurrentCulture to format expression results.

  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.Conversion of an interpolated string to a FormattableString instance that represents a composite format string along with the expression results to be formatted. 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.That allows you to create multiple result strings with culture-specific content from a single FormattableString instance. Para fazer isso, ligue para um dos seguintes métodos:To do that, call one of the following methods:

    Você também pode ToString(IFormatProvider) usar o método para fornecer IFormatProvider uma implementação definida pelo usuário da interface que suporta formatação personalizada.You can also use the ToString(IFormatProvider) method to provide a user-defined implementation of the IFormatProvider interface that supports custom formatting. Para obter mais informações, consulte a formatação personalizada com a seção ICustomFormatter dos tipos de formatação no artigo .NET.For more information, see the Custom formatting with ICustomFormatter section of the Formatting types in .NET article.

  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.Conversion of an interpolated string to an IFormattable instance that also allows you to create multiple result strings with culture-specific content from a single IFormattable instance.

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:The following example uses implicit conversion to FormattableString to create culture-specific result strings:

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 adicionaisAdditional resources

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.If you are new to string interpolation, see the String interpolation in C# interactive tutorial. Você também pode verificar outra interpolação de strings no tutorial C# que demonstra como usar strings interpoladas para produzir strings formatadas.You can also check another String interpolation in C# tutorial that demonstrates how to use interpolated strings to produce formatted strings.

Compilação de cadeias de caracteres interpoladasCompilation of interpolated strings

Se uma cadeia de caracteres interpolada tiver o tipo string, ela normalmente será transformada em uma chamada de método String.Format.If an interpolated string has the type string, it's typically transformed into a String.Format method call. O compilador pode substituir String.Format por String.Concat se o comportamento analisado for equivalente à concatenação.The compiler may replace String.Format with String.Concat if the analyzed behavior would be equivalent to concatenation.

Se uma cadeia de caracteres interpolada tiver o tipo IFormattable ou FormattableString, o compilador gerará uma chamada para o método FormattableStringFactory.Create.If an interpolated string has the type IFormattable or FormattableString, the compiler generates a call to the FormattableStringFactory.Create method.

especificação da linguagem C#C# language specification

Para obter mais informações, consulte a seção cadeias de caracteres interpoladas da especificação da linguagem C#.For more information, see the Interpolated strings section of the C# language specification.

Confira tambémSee also