Interpolación de cadenas en C#String interpolation in C#

En este tutorial se explica cómo usar la interpolación de cadenas para dar formato a resultados de expresión e incluirlos en una cadena de resultado.This tutorial shows you how to use string interpolation to format and include expression results in a result string. En los ejemplos se da por hecho que ya está familiarizado con los conceptos básicos de C# y el formato de tipos .NET.The examples assume that you are familiar with basic C# concepts and .NET type formatting. Si no conoce la interpolación de cadenas o el formato de tipos .NET, vea antes el tutorial de interpolación de cadenas interactivo.If you are new to string interpolation or .NET type formatting, check out the interactive string interpolation tutorial first. Para más información sobre cómo aplicar formato a tipos .NET, vea el tema Aplicar formato a tipos en .NET.For more information about formatting types in .NET, see the Formatting Types in .NET topic.

Nota

Los ejemplos de C# de este artículo se ejecutan en el ejecutor de código en línea y área de juegos de Try.NET.The C# examples in this article run in the Try.NET inline code runner and playground. Haga clic en el botón Ejecutar para ejecutar un ejemplo en una ventana interactiva.Select the Run button to run an example in an interactive window. Una vez que se ejecuta el código, puede modificar y ejecutar el código modificado si vuelve a hacer clic en Ejecutar.Once you execute the code, you can modify it and run the modified code by selecting Run again. El código modificado se ejecuta en la ventana interactiva o, si se produce un error en la compilación, en la ventana interactiva se muestran todos los mensajes de error del compilador de C#.The modified code either runs in the interactive window or, if compilation fails, the interactive window displays all C# compiler error messages.

IntroducciónIntroduction

La característica de interpolación de cadenas se basa en la característica de formato compuesto y proporciona una sintaxis más legible y cómoda para incluir resultados de expresiones con formato en una cadena 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 distinguir un literal de cadena como una cadena interpolada, antepóngale el símbolo $.To identify a string literal as an interpolated string, prepend it with the $ symbol. Puede insertar cualquier expresión de C# válida que devuelva un valor en una cadena interpolada.You can embed any valid C# expression that returns a value in an interpolated string. En el siguiente ejemplo, en cuanto la expresión se evalúa, su resultado se convierte en una cadena y se incluye en una cadena 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 se ilustra en el ejemplo, para incluir una expresión en una cadena interpolada hay que meterla entre llaves:As the example shows, you include an expression in an interpolated string by enclosing it with braces:

{<interpolationExpression>}

Las cadenas interpoladas admiten todas las funcionalidades de la característica de formato compuesto de cadena.Interpolated strings support all the capabilities of the string composite formatting feature. Esto las convierte en una alternativa más legible al uso del método String.Format.That makes them a more readable alternative to the use of the String.Format method.

Cómo especificar una cadena de formato para una expresión de interpolaciónHow to specify a format string for an interpolation expression

Para especificar una cadena de formato compatible con el tipo de resultado de expresión, coloque después de la expresión de interpolación dos puntos (":") y la cadena 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>}

En el siguiente ejemplo se muestra cómo especificar cadenas de formato estándar y personalizadas para expresiones que generan resultados numéricos o de fecha y 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 más información, vea la sección Format String (Componente) del tema Formatos compuestos.For more information, see the Format String Component section of the Composite Formatting topic. En esa sección encontrará vínculos a temas en los que se describen las cadenas de formato estándar y personalizadas compatibles con los tipos base .NET.That section provides links to the topics that describe standard and custom format strings supported by .NET base types.

Cómo controlar el ancho de campo y la alineación de las expresiones de interpolación con formatoHow to control the field width and alignment of the formatted interpolation expression

Para especificar el ancho de campo mínimo y la alineación del resultado de expresión con formato, coloque después de la expresión de interpolación una coma (",") y la expresión 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>}

Si el valor de alignment es positivo, el resultado de la expresión con formato se alineará a la derecha y, si es negativo, lo hará a la izquierda.If the alignment value is positive, the formatted expression result is right-aligned; if negative, it's left-aligned.

En caso de que haya que especificar una alineación y una cadena de formato, comience por el componente de alineación:If you need to specify both alignment and a format string, start with the alignment component:

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

En el siguiente ejemplo se muestra cómo especificar la alineación y se emplean caracteres de barra vertical ("|") para delimitar los 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|

Tal y como refleja la salida del ejemplo, si la longitud del resultado de expresión con formato supera el ancho de campo especificado, se omitirá el valor de alignment.As the example output shows, if the length of the formatted expression result exceeds specified field width, the alignment value is ignored.

Para más información, vea la sección Alignment (Componente) del tema Formatos compuestos.For more information, see the Alignment Component section of the Composite Formatting topic.

Cómo usar secuencias de escape en una cadena interpoladaHow to use escape sequences in an interpolated string

Las cadenas interpoladas admiten todas las secuencias de escape que se usan en los literales de cadena ordinarios.Interpolated strings support all escape sequences that can be used in ordinary string literals. Para más información, vea Secuencias de escape de cadena.For more information, see String escape sequences.

Para interpretar las secuencias de escape literalmente, use un literal de cadena textual.To interpret escape sequences literally, use a verbatim string literal. Las cadenas textuales interpoladas comienzan por el carácter $, seguido del carácter @.An interpolated verbatim string starts with the $ character followed by the @ character. A partir C# 8.0, puede usar los tokens $ y @ en cualquier orden; tanto $@"..." como @$"..." son cadenas textuales 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 una llave ("{" o "}") en una cadena de resultado, use dos llaves ("{{" o "}}").To include a brace, "{" or "}", in a result string, use two braces, "{{" or "}}". Para más información, vea la sección Llaves de escape del tema Formatos compuestos.For more information, see the Escaping Braces section of the Composite Formatting topic.

En el siguiente ejemplo se muestra cómo incluir llaves en una cadena de resultado y cómo construir una cadena 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

Cómo usar un operador condicional ternario ?: en una expresión de interpolaciónHow to use a ternary conditional operator ?: in an interpolation expression

Dado que los dos puntos (:) tienen un significado especial en un elemento con una expresión de interpolación, para poder usar un operador condicional en una expresión de este tipo habrá que ponerlo entre paréntesis, como vemos en el siguiente ejemplo: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")}");
}

Cómo crear una cadena de resultado específica de la referencia cultural con interpolación de cadenasHow to create a culture-specific result string with string interpolation

Las cadenas interpoladas usan de forma predeterminada la referencia cultural definida actualmente por la propiedad CultureInfo.CurrentCulture en todas las operaciones de formato.By default, an interpolated string uses the current culture defined by the CultureInfo.CurrentCulture property for all formatting operations. Use la conversión implícita de una cadena interpolada en una instancia de System.FormattableString y llame al método ToString(IFormatProvider) correspondiente para crear una cadena de resultado específica de referencia cultural.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. En el siguiente ejemplo se muestra cómo hacerlo: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

Tal y como se muestra en el ejemplo, se puede usar una instancia de FormattableString para generar varias cadenas de resultado para varias referencias culturales.As the example shows, you can use one FormattableString instance to generate multiple result strings for various cultures.

Cómo crear una cadena de resultado usando la referencia de cultura invariableHow to create a result string using the invariant culture

Puede usar el método estático FormattableString.Invariant junto con el método FormattableString.ToString(IFormatProvider) para resolver una cadena interpolada en una cadena de resultado de 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. En el siguiente ejemplo se muestra cómo hacerlo: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

ConclusiónConclusion

En este tutorial se han descrito escenarios habituales en los que se usa la interpolación de cadenas.This tutorial describes common scenarios of string interpolation usage. Para más información sobre la interpolación de cadenas, vea el tema Interpolación de cadenas.For more information about string interpolation, see the String interpolation topic. Para más información sobre cómo aplicar formato a tipos .NET, vea los temas Aplicar formato a tipos en .NET y Formatos compuestos.For more information about formatting types in .NET, see the Formatting Types in .NET and Composite formatting topics.

Vea tambiénSee also