$ - Interpolación de cadenas: referencia de C#

El carácter especial $ identifica un literal de cadena como una cadena interpolada. Una cadena interpolada es un literal de cadena que puede contener expresiones de interpolación. 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. Esta característica está disponible a partir de C# 6.

La interpolación de cadenas proporciona una sintaxis más legible y conveniente de dar formato a las cadenas. Es más fácil de leer que el formato compuesto de cadenas. Compare el ejemplo siguiente donde se usan ambas características para producir el mismo resultado:

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 interpolada

Para distinguir un literal de cadena como una cadena interpolada, antepóngale el símbolo $. No puede haber ningún espacio en blanco entre el carácter $ y el carácter " que inicia un literal de cadena.

La estructura de un elemento con una expresión de interpolación es como se muestra aquí:

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

Los elementos entre corchetes son opcionales. En esta tabla se describe cada elemento:

Elemento Descripción
interpolationExpression Expresión que genera un resultado al que se va a aplicar formato. La representación de cadena de null es 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. Si es positivo, la representación de cadena está alineada a la derecha; si es negativo, está alineada a la izquierda. Para más información, vea Alignment (Componente).
formatString Cadena de formato compatible con el tipo de resultado de la expresión. Para más información, vea Format String (Componente).

En el ejemplo siguiente, se usan componentes opcionales de formato que se han descrito anteriormente:

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

A partir de C# 10, se puede utilizar la interpolación de cadenas para inicializar una constante de cadena. Todas las expresiones usadas en los marcadores de posición deben ser constantes de cadena. En otras palabras, cada expresión de interpolación debe ser una cadena y debe ser una constante en tiempo de compilación.

Caracteres especiales

Para incluir una llave ("{" o "}") en el texto generado por una cadena interpolada, use dos llaves ("{{" o "}}"). Para más información, vea Llaves de escape.

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.

En el siguiente ejemplo se muestra cómo incluir una llave en una cadena de resultado. También se muestra cómo usar un operador condicional:

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 @. Para más información sobre las cadenas textuales, consulte los artículos sobre cadenas e Identificadores textuales.

Nota

A partir de C# 8.0, puede usar los tokens $ y @ en cualquier orden; tanto $@"..." como @$"..." son cadenas textuales interpoladas válidas. En versiones de C# anteriores, el token $ debe aparecer delante del token @.

Conversiones implícitas y cómo especificar la implementación de IFormatProvider

Hay tres conversiones implícitas de una cadena interpolada:

  1. Conversión de una cadena interpolada en una instancia de String. La cadena es el resultado de la resolución de la cadena interpolada. Todos los elementos de la expresión de interpolación se reemplazan por las representaciones de cadena con el formato correcto de sus resultados. Esta conversión utiliza CurrentCulture para dar formato a los resultados de la expresión.

  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. Esto permite crear varias cadenas de resultado con contenido específico de la referencia cultural de una sola instancia de FormattableString. Para ello, llame a uno de estos métodos:

    El método ToString(IFormatProvider) proporciona una implementación definida por el usuario de la interfaz IFormatProvider que admite formato personalizado. Para más información, consulte la sección Formato personalizado con ICustomFormatter del artículo Aplicar formato a tipos en .NET.

  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.

En el ejemplo siguiente, se usa la conversión implícita a FormattableString para crear cadenas de resultado específicas de la referencia cultural:

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 adicionales

Si no está familiarizado con la interpolación de cadenas, consulte el tutorial interactivo Interpolación de cadenas en C#. También puede consultar otro tutorial sobre la interpolación de cadenas en C#. En ese tutorial se muestra el uso de cadenas interpoladas para generar cadenas con formato.

Compilación de cadenas interpoladas

Si una cadena interpolada tiene el tipo string, normalmente se transforma en una llamada de método String.Format. El compilador puede reemplazar String.Format por String.Concat si el comportamiento analizado es equivalente a una concatenación.

Si una cadena interpolada tiene el tipo IFormattable o FormattableString, el compilador genera una llamada al método FormattableStringFactory.Create.

A partir de C# 10, cuando se usa una cadena interpolada, el compilador comprueba si esta está asignada a un tipo que satisface el patrón de controlador de cadenas interpoladas. Un controlador de cadenas interpoladas es un tipo personalizado que convierte la cadena interpolada en una cadena. Un controlador de cadenas interpoladas es un escenario avanzado, que normalmente se usa por motivos de rendimiento. Puede obtener información sobre los requisitos para crear un controlador de cadenas interpoladas en la especificación del lenguaje para las mejoras de cadenas interpoladas. Para crear uno, puede seguir el tutorial sobre el controlador de cadenas interpoladas en la sección de Novedades de C#. En .NET 6, cuando se usa una cadena interpolada para un argumento de tipo string, System.Runtime.CompilerServices.DefaultInterpolatedStringHandler procesa la cadena interpolada.

Nota

Un efecto secundario de los controladores de cadenas interpoladas es que un controlador personalizado, por ejemplo, System.Runtime.CompilerServices.DefaultInterpolatedStringHandler, podría no evaluar todas las expresiones usadas como marcadores de posición en la cadena interpolada en todas las condiciones. Esto significa que es posible que no se produzcan efectos secundarios en esas expresiones.

Especificación del lenguaje C#

Para obtener más información, vea la sección Interpolated strings (Cadenas interpoladas) de la especificación del lenguaje C#.

Vea también