Interpolação de cadeias de caracteres em C#String interpolation in C#

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.This tutorial shows you how to use string interpolation to format and include expression results in a result string. Os exemplos pressupõem que você esteja familiarizado com os conceitos básicos do C# e a formatação de tipos do .NET.The examples assume that you are familiar with basic C# concepts and .NET type formatting. Se você não estiver familiarizado com a interpolação de cadeia de caracteres ou com a formatação de tipos do .NET, confira primeiro o tutorial interativo sobre a interpolação de cadeia de caracteres.If you are new to string interpolation or .NET type formatting, check out the interactive string interpolation tutorial first. Para obter mais informações sobre como formatar tipos no .NET, confira o tópico Formatando tipos no .NET.For more information about formatting types in .NET, see the Formatting Types in .NET topic.

Observação

Os exemplos de C# neste artigo são executados no executador de código embutido Try.NET e no playground.The C# examples in this article run in the Try.NET inline code runner and playground. Clique no botão Executar para executar um exemplo em uma janela interativa.Select the Run button to run an example in an interactive window. Ao executar o código, é possível modificá-lo e executar o código modificado clicando em Executar novamente.Once you execute the code, you can modify it and run the modified code by selecting Run again. O código modificado será executado na janela interativa ou, se a compilação falhar, a janela interativa exibirá todos as mensagens de erro do compilador C#.The modified code either runs in the interactive window or, if compilation fails, the interactive window displays all C# compiler error messages.

IntroduçãoIntroduction

O recurso interpolação de cadeia de caracteres baseia-se no recurso formatação composta e fornece uma sintaxe mais legível e conveniente para incluir resultados de expressão formatada em uma cadeia de caracteres de resultado.The string interpolation feature is built on top of the composite formatting feature and provides a more readable and convenient syntax to include formatted expression results in a result 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. Você pode inserir qualquer expressão C# válida que retorna um valor em uma cadeia de caracteres interpolada.You can embed any valid C# expression that returns a value in an interpolated string. No seguinte exemplo, assim que uma expressão é avaliada, o resultado é convertido em uma cadeia de caracteres e incluído em uma cadeia de caracteres de resultado:In the following example, as soon as an expression is evaluated, its result is converted into a string and included in a result string:

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);

// Expected 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:As the example shows, you include an expression in an interpolated string by enclosing it with braces:

{<interpolationExpression>}

Cadeia de caracteres interpoladas são compatíveis com todos os recursos do recurso formatação composta de cadeia de caracteres.Interpolated strings support all the capabilities of the string composite formatting feature. Isso as torna uma alternativa mais legível ao uso do método String.Format.That makes them a more readable alternative to the use of the String.Format method.

Como especificar uma cadeia de caracteres de formato para uma expressão de interpolaçãoHow to specify a format string for an interpolation expression

Especifique uma cadeia de caracteres de formato compatível com o tipo do resultado de expressão seguindo a expressão de interpolação com dois-pontos (":") e a cadeia de caracteres de formato:You specify a format string that is supported by the type of the expression result by following the interpolation expression with a colon (":") and the format string:

{<interpolationExpression>:<formatString>}

O seguinte exemplo mostra como especificar cadeias de caracteres de formato padrão e personalizadas para expressões que produzem resultados numéricos ou de data e hora:The following example shows how to specify standard and custom format strings for expressions that produce date and time or numeric results:

var date = new DateTime(1731, 11, 25);
Console.WriteLine($"On {date:dddd, MMMM dd, yyyy} Leonhard Euler introduced the letter e to denote {Math.E:F5} in a letter to Christian Goldbach.");

// Expected output:
// On Sunday, November 25, 1731 Leonhard Euler introduced the letter e to denote 2.71828 in a letter to Christian Goldbach.

Para obter mais informações, consulte a seção Componente de cadeia de caracteres de formato do tópico Formatação composta.For more information, see the Format String Component section of the Composite Formatting topic. Esta seção fornece links para tópicos que descrevem cadeias de caracteres de formatos padrão e personalizado compatíveis com os tipos base do .NET.That section provides links to the topics that describe standard and custom format strings supported by .NET base types.

Como controlar a largura do campo e o alinhamento da expressão de interpolação formatadaHow to control the field width and alignment of the formatted interpolation expression

Você especifica a largura mínima do campo e o alinhamento do resultado de expressão formatada seguindo a expressão de interpolação com uma vírgula (",") e a expressão de constante:You specify the minimum field width and the alignment of the formatted expression result by following the interpolation expression with a comma (",") and the constant expression:

{<interpolationExpression>,<alignment>}

Se o valor alignment for positivo, o resultado da expressão formatada será alinhado à direita; se for negativo, ele será alinhado à esquerda.If the alignment value is positive, the formatted expression result is right-aligned; if negative, it's left-aligned.

Caso precise especificar o alinhamento e uma cadeia de caracteres de formato, comece com o componente de alinhamento:If you need to specify both alignment and a format string, start with the alignment component:

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

O seguinte exemplo mostra como especificar o alinhamento e usa caracteres de barra vertical ("|") para delimitar campos de texto:The following example shows how to specify alignment and uses pipe characters ("|") to delimit text fields:

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}|");

// Expected 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 tamanho do resultado da expressão formatada exceder a largura de campo especificada, o valor alignment será ignorado.As the example output shows, if the length of the formatted expression result exceeds specified field width, the alignment value is ignored.

Para obter mais informações, consulte a seção Componente de alinhamento do tópico Formatação composta.For more information, see the Alignment Component section of the Composite Formatting topic.

Como usar sequências de escape em uma cadeia de caracteres interpoladaHow to use escape sequences in an interpolated string

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.Interpolated strings support all escape sequences that can be used in ordinary string literals. Para obter mais informações, consulte Sequências de escape de cadeia de caracteres.For more information, see String escape sequences.

Para interpretar sequências de escape literalmente, use um literal de cadeia de caracteres textual.To interpret escape sequences literally, use a verbatim string literal. Uma cadeia de @ caracteres textual interpolada começa $ com o caractere seguido pelo caractere.An interpolated verbatim string starts with the $ character followed by the @ character. A partir C# do 8,0, você pode usar $ os @ tokens e em qualquer ordem $@"..." : @$"..." e são cadeias de caracteres idênticas interpoladas válidas.Starting with C# 8.0, you can use the $ and @ tokens in any order: both $@"..." and @$"..." are valid interpolated verbatim strings.

Para incluir uma chave, "{" ou "}", em uma cadeia de caracteres de resultado, use duas chaves, "{{" ou "}}".To include a brace, "{" or "}", in a result string, use two braces, "{{" or "}}". Para obter mais informações, consulte a seção Chaves de escape do tópico Formatação composta.For more information, see the Escaping Braces section of the Composite Formatting topic.

O seguinte exemplo mostra como incluir chaves em uma cadeia de caracteres de resultado e construir uma cadeia de caracteres interpolada textual:The following example shows how to include braces in a result string and construct a verbatim interpolated string:

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.");

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

// Expected output:
// Find the intersection of the {1, 2, 7, 9} and {7, 9, 12} sets.
// C:\Users\Jane\Documents
// C:\Users\Jane\Documents

Como usar um operador condicional ternário ?: em uma expressão de interpolaçãoHow to use a ternary conditional operator ?: in an interpolation expression

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

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 caracteresHow to create a culture-specific result string with string interpolation

Por padrão, uma cadeia de caracteres interpolada usa a cultura atual definida pela propriedade CultureInfo.CurrentCulture para todas as operações de formatação.By default, an interpolated string uses the current culture defined by the CultureInfo.CurrentCulture property for all formatting operations. Use uma 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 a uma cultura.Use implicit conversion of an interpolated string to a System.FormattableString instance and call its ToString(IFormatProvider) method to create a culture-specific result string. O seguinte exemplo mostra como fazer isso:The following example shows how to do that:

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,20}{number,20:N3}";
foreach (var culture in cultures)
{
    var cultureSpecificMessage = message.ToString(culture);
    Console.WriteLine($"{culture.Name,-10}{cultureSpecificMessage}");
}

// Expected output is like:
// en-US       5/17/18 3:44:55 PM      31,415,926.536
// en-GB      17/05/2018 15:44:55      31,415,926.536
// nl-NL        17-05-18 15:44:55      31.415.926,536
//            05/17/2018 15:44:55      31,415,926.536

Como mostra o exemplo, você pode usar uma instância FormattableString para gerar várias cadeias de caracteres de resultado para várias culturas.As the example shows, you can use one FormattableString instance to generate multiple result strings for various cultures.

Como criar uma cadeia de caracteres de resultado usando a cultura invariávelHow to create a result string using the invariant culture

Juntamente com o método FormattableString.ToString(IFormatProvider), você pode usar o método FormattableString.Invariant estático para resolver uma cadeia de caracteres interpolada em uma cadeia de caracteres de resultado para a InvariantCulture.Along with the FormattableString.ToString(IFormatProvider) method, you can use the static FormattableString.Invariant method to resolve an interpolated string to a result string for the InvariantCulture. O seguinte exemplo mostra como fazer isso:The following example shows how to do that:

string messageInInvariantCulture = FormattableString.Invariant($"Date and time in invariant culture: {DateTime.Now}");
Console.WriteLine(messageInInvariantCulture);

// Expected output is like:
// Date and time in invariant culture: 05/17/2018 15:46:24

ConclusãoConclusion

Este tutorial descreve cenários comuns de uso da interpolação de cadeia de caracteres.This tutorial describes common scenarios of string interpolation usage. Para obter mais informações sobre a interpolação de cadeia de caracteres, consulte o tópico Interpolação de cadeia de caracteres.For more information about string interpolation, see the String interpolation topic. Para obter mais informações sobre como formatar tipos no .NET, confira os tópicos Formatando tipos no .NET e Formatação composta.For more information about formatting types in .NET, see the Formatting Types in .NET and Composite formatting topics.

Consulte tambémSee also