$ - Interpolación de cadenas (Referencia de C#)$ - string interpolation (C# Reference)

El carácter especial $ identifica un literal de cadena como una cadena interpolada.The $ special character identifies a string literal as an interpolated string. Una cadena interpolada es un literal de cadena que puede contener expresiones de interpolación.An interpolated string is a string literal that might contain interpolation expressions. Cuando una cadena interpolada se resuelve en una cadena de resultado, los elementos con expresiones de interpolación se reemplazan por las representaciones de cadena de los resultados de la expresión.When an interpolated string is resolved to a result string, items with interpolation expressions are replaced by the string representations of the expression results. Esta característica está disponible en C# 6 y versiones posteriores del lenguaje.This feature is available in C# 6 and later versions of the language.

La interpolación de cadenas proporciona una sintaxis más legible y cómoda de crear cadenas con formato que si se usa la característica de formato compuesto de cadena.String interpolation provides a more readable and convenient syntax to create formatted strings than a string composite formatting feature. En este ejemplo se usan ambas características para producir el mismo 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.

Estructura de una cadena interpoladaStructure of an interpolated 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. No puede haber ningún espacio en blanco entre el carácter $ y el carácter " que inicia un literal de cadena.You cannot have any white space between the $ and the " that starts a string literal. Si hay alguno, se producirá un error en tiempo de compilación.Doing so causes a compile-time error.

La estructura de un elemento con una expresión de interpolación es como se muestra aquí:The structure of an item with an interpolation expression is as follows:

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

Los elementos entre corchetes son opcionales.Elements in square brackets are optional. En esta tabla se describe cada elemento:The following table describes each element:

ElementoElement DescripciónDescription
interpolationExpression Expresión que genera un resultado al que se va a aplicar formato.The expression that produces a result to be formatted. La representación de cadena del resultado de null es String.Empty.String representation of the null result is String.Empty.
alignment La expresión constante cuyo valor define el número mínimo de caracteres en la representación de cadena del resultado de la expresión de interpolación.The constant expression whose value defines the minimum number of characters in the string representation of the result of the interpolation expression. Si es positivo, la representación de cadena está alineada a la derecha; si es negativo, está alineada a la izquierda.If positive, the string representation is right-aligned; if negative, it's left-aligned. Para más información, vea Alignment (Componente).For more information, see Alignment Component.
formatString Cadena de formato compatible con el tipo de resultado de la expresión.A format string that is supported by the type of the expression result. Para más información, vea Format String (Componente).For more information, see Format String Component.

En el ejemplo siguiente, se usan componentes opcionales de formato que se han descrito anteriormente: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 especialesSpecial characters

Para incluir una llave ("{" o "}") en el texto generado por una cadena interpolada, use dos llaves ("{{" o "}}").To include a brace, "{" or "}", in the text produced by an interpolated string, use two braces, "{{" or "}}". Para más información, vea Llaves de escape.For more information, see Escaping Braces.

Como los dos puntos (":") tienen un significado especial en un elemento de expresión de interpolación, para poder usar un operador condicional en una expresión de interpolación, incluya esa expresión entre paréntesis.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.

En este ejemplo, se muestra cómo incluir una llave en una cadena de resultado y cómo usar un operador condicional en una expresión de interpolación: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.

Las cadenas interpoladas textuales comienzan por el carácter $, seguido del carácter @.A verbatim interpolated string starts with the $ character followed by the @ character. Para más información sobre las cadenas textuales, vea los temas string e Identificador textual.For more information about verbatim strings, see the string and verbatim identifier topics.

Nota

El token $ debe aparecer antes del token @ en una cadena interpolada textual.The $ token must appear before the @ token in a verbatim interpolated string.

Conversiones implícitas y especificar una implementación de IFormatProviderImplicit conversions and specifying IFormatProvider implementation

Hay tres conversiones implícitas de una cadena interpolada:There are three implicit conversions from an interpolated string:

  1. Conversión de una cadena interpolada a una instancia de String, que es el resultado de la resolución de cadenas interpoladas con elementos de expresión de interpolación que se reemplazan con las representaciones de cadena con formato correcto de sus resultados.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 conversión usa la referencia cultural actual.This conversion uses the current culture.

  2. Conversión de una cadena interpolada a una instancia FormattableString que representa una cadena de formato compuesto junto con los resultados de expresión a los que se va a aplicar formato.Conversion of an interpolated string to a FormattableString instance that represents a composite format string along with the expression results to be formatted. Esto permite crear varias cadenas de resultado con contenido específico de la referencia cultural de una sola instancia de FormattableString.That allows you to create multiple result strings with culture-specific content from a single FormattableString instance. Para ello, llame a uno de estos métodos:To do that call one of the following methods:

    También puede usar el método ToString(IFormatProvider) para proporcionar una implementación definido por el usuario de la interfaz IFormatProvider que admite formatos personalizados.You also can use the ToString(IFormatProvider) method to provide a user-defined implementation of the IFormatProvider interface that supports custom formatting. Para más información, vea Formato personalizado con ICustomFormatter.For more information, see Custom Formatting with ICustomFormatter.

  3. Conversión de una cadena interpolada a una instancia IFormattable que también permite crear varias cadenas de resultado con contenido específico de la referencia cultural de una sola instancia 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.

En el ejemplo siguiente, se usa la conversión implícita a FormattableString para crear cadenas de resultado específicas de la referencia cultural: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 adicionalesAdditional resources

Si no está familiarizado con la interpolación de cadenas, vea el tutorial interactivo Interpolación de cadenas en C#.If you are new to string interpolation, see the String interpolation in C# interactive tutorial. También puede consultar otro tutorial de interpolación de cadenas en C# que muestra cómo usar cadenas interpoladas para generar cadenas con formato.You also can check another String interpolation in C# tutorial that demonstrates how to use interpolated strings to produce formatted strings.

Compilación de cadenas interpoladasCompilation of interpolated strings

Si una cadena interpolada tiene el tipo string, normalmente se transforma en una llamada de método String.Format.If an interpolated string has the type string, it's typically transformed into a String.Format method call. El compilador puede reemplazar String.Format por String.Concat si el comportamiento analizado es equivalente a una concatenación.The compiler may replace String.Format with String.Concat if the analyzed behavior would be equivalent to concatenation.

Si una cadena interpolada tiene el tipo IFormattable o FormattableString, el compilador genera una llamada al método FormattableStringFactory.Create.If an interpolated string has the type IFormattable or FormattableString, the compiler generates a call to the FormattableStringFactory.Create method.

Especificación del lenguaje C#C# language specification

Para obtener más información, vea la sección Interpolated strings (Cadenas interpoladas) de la especificación del lenguaje C#.For more information, see the Interpolated strings section of the C# language specification.

Vea tambiénSee also