$ - 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 a partir de C# 6.This feature is available starting with C# 6.

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.

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 de null es String.Empty.String representation of null 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.The constant expression whose value defines the minimum number of characters in the string representation of the expression result. 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 textuales interpoladas comienzan por el carácter $, seguido del carácter @.An interpolated verbatim 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

A partir de 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. En versiones de C# anteriores, el token $ debe aparecer delante del token @.In earlier C# versions, the $ token must appear before the @ token.

Conversiones implícitas y cómo especificar la implementación de IFormatProviderImplicit conversions and how to specify 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 utiliza CurrentCulture para dar formato a los resultados de la expresión.This conversion uses the CurrentCulture to format expression results.

  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, consulte la sección Formato personalizado con ICustomFormatter del artículo Aplicar formato a tipos en .NET.For more information, see the Custom formatting with ICustomFormatter section of the Formatting types in .NET article.

  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