interpolação de $-C# String (referência)$ - 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. Esse recurso está disponível a partir C# de 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-a 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. A representação de cadeia de caracteres de null é String.Empty.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 cadeia de caracteres 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 cadeia de caracteres textual interpolada começa com o caractere de $ seguido pelo caractere de @.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

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

Conversões implícitas e como especificar IFormatProvider 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. Essa conversão usa o CurrentCulture para formatar resultados de expressão.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, chame um dos seguintes métodos:To do that, call one of the following methods:

    Use também o método ToString(IFormatProvider) para fornecer uma implementação definida pelo usuário da interface IFormatProvider que dá suporte à formatação personalizada.You also can 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 seção formatação personalizada com ICustomFormatter do artigo tipos de formatação no .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 outro tutorial de interpolação de cadeia de caracteres C# que demonstra como usar cadeias de caracteres interpoladas para produzir cadeias de caracteres formatadas.You also can 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.

Consulte tambémSee also