$ - Interpolation de chaîne (référence C#)

Le caractère spécial $ identifie un littéral de chaîne comme une chaîne interpolée. Une chaîne interpolée est un littéral de chaîne qui peut contenir des expressions d’interpolation. Quand une chaîne interpolée est résolue en une chaîne de résultat, les éléments avec des expressions d’interpolation sont remplacés par les représentations sous forme de chaîne des résultats des expressions. Cette fonctionnalité est disponible à partir de C# 6.

L’interpolation de chaîne fournit une syntaxe plus lisible et pratique pour mettre en forme des chaînes. Il est plus facile de lire que la mise en forme composite de chaîne. Comparez l’exemple suivant qui utilise les deux fonctionnalités pour produire la même sortie :

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.

Structure d’une chaîne interpolée

Pour identifier un littéral de chaîne comme chaîne interpolée, préfixez-la du symbole $. Vous ne pouvez pas avoir d’espace blanc entre le et le $" littéral de chaîne. Pour concantener plusieurs chaînes interpolées, ajoutez le $ caractère spécial à chaque littéral de chaîne.

La structure d’un élément avec une expression d’interpolation se présente comme suit :

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

Les éléments entre crochets sont facultatifs. Le tableau suivant décrit chaque élément :

Élément Description
interpolationExpression Expression qui produit un résultat à mettre en forme. Représentation sous forme de chaîne d’est nullString.Empty.
alignment Expression constante dont la valeur définit le nombre minimal de caractères dans la représentation sous forme de chaîne du résultat de l’expression. Si le nombre est positif, la représentation sous forme de chaîne est alignée à droite ; s’il est négatif, elle est alignée à gauche. Pour plus d'informations, consultez Composant d’alignement.
formatString Chaîne de format qui est prise en charge par le type de résultat de l’expression. Pour plus d'informations, consultez Composant de chaîne de format.

L’exemple suivant utilise les composants de mise en forme facultatifs décrits ci-dessus :

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

À compter de C# 10, vous pouvez utiliser l’interpolation de chaîne pour initialiser une chaîne constante. Toutes les expressions utilisées pour les espaces réservés doivent être des chaînes constantes. En d’autres termes, chaque expression d’interpolation doit être une chaîne, et elle doit être une constante de temps de compilation.

À compter de C# 11, les expressions interpolées peuvent inclure des nouvelles lignes. Le texte entre le { texte et } doit être valide C#, il peut donc inclure des nouvelles lignes qui améliorent la lisibilité. L’exemple suivant montre comment les nouvelles lignes peuvent améliorer la lisibilité d’une expression impliquant la correspondance de modèle :

string message = $"The usage policy for {safetyScore} is {
    safetyScore switch
    {
        > 90 => "Unlimited usage",
        > 80 => "General usage, with daily safety check",
        > 70 => "Issues must be addressed within 1 week",
        > 50 => "Issues must be addressed within 1 day",
        _ => "Issues must be addressed before continued use",
    }
    }";

En outre, à compter de C# 11, vous pouvez utiliser un littéral de chaîne brute pour la chaîne de format :

int X = 2;
int Y = 3;

var pointMessage = $"""The point "{X}, {Y}" is {Math.Sqrt(X * X + Y * Y)} from the origin""";

Console.WriteLine(pointMessage);
// output:  The point "2, 3" is 3.605551275463989 from the origin.

Vous pouvez utiliser plusieurs $ caractères dans un littéral de chaîne brute interpolé pour incorporer { et } caractères dans la chaîne de sortie sans les échapper :

int X = 2;
int Y = 3;

var pointMessage = $$"""The point {{{X}}, {{Y}}} is {{Math.Sqrt(X * X + Y * Y)}} from the origin""";
Console.WriteLine(pointMessage);
// output:  The point {2, 3} is 3.605551275463989 from the origin.

Si votre chaîne de sortie doit contenir des caractères répétés { ou } des caractères, vous pouvez ajouter plus $ pour désigner la chaîne interpolée. Toute séquence de { données ou } plus courte que le nombre de $ valeurs sera incorporée dans la chaîne de sortie. Comme indiqué dans l’exemple précédent, les séquences plus longues que la séquence de $ caractères incorporent les caractères supplémentaires { ou } les caractères dans la sortie. Le compilateur émet une erreur si la séquence de caractères accolades est égale ou supérieure à la longueur de la séquence de $ caractères.

Vous pouvez essayer ces fonctionnalités à l’aide du Kit de développement logiciel (SDK) .NET 7. Ou, si vous disposez du Kit de développement logiciel (SDK) .NET 6.00.200 ou version ultérieure, vous pouvez définir l’élément <LangVersion> dans votre fichier previewcsproj sur .

Caractères spéciaux

Pour ajouter une accolade, « { » ou « } », dans le texte produit par une chaîne interpolée, entrez deux accolades, « {{ » ou « }} ». Pour plus d'informations, consultez Accolades d’échappement.

Comme le signe deux-points (« : ») a une signification particulière dans un élément d’expression d’interpolation, pour utiliser un opérateur conditionnel dans une expression d’interpolation, placez cette expression entre parenthèses.

L’exemple suivant montre comment inclure un accolades dans une chaîne de résultat. Il montre également comment utiliser un opérateur conditionnel :

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.

Une chaîne détaillée interpolée commence par le $ caractère suivi du @ caractère. Pour plus d’informations sur les chaînes détaillées, consultez les articles d’identificateur de chaîne et de verbe .

Notes

À partir de C# 8.0, vous pouvez utiliser les jetons et @ les $ jetons dans n’importe quel ordre : les deux $@"..." et @$"..." sont des chaînes détaillées interpolées valides. Dans les versions C# antérieures, le $ jeton doit apparaître avant le @ jeton.

Conversions implicites et comment spécifier IFormatProvider l’implémentation

Trois conversions implicites sont possibles à partir d’une chaîne interpolée :

  1. Conversion d’une chaîne interpolée en instance String . La chaîne est le résultat de la résolution de chaîne interpolée. Tous les éléments d’expression d’interpolation sont remplacés par les représentations de chaîne correctement mises en forme de leurs résultats. Cette conversion utilise les résultats de l’expression CurrentCulture pour mettre en forme les résultats.

  2. Conversion d’une chaîne interpolée en instance FormattableString qui représente une chaîne de format composite avec les résultats d’expression à mettre en forme. Cette conversion vous permet de créer plusieurs chaînes de résultat avec du contenu propre à la culture à partir d’une seule instance de FormattableString. Pour ce faire, appelez l’une des méthodes suivantes :

    Il ToString(IFormatProvider) fournit une implémentation définie par l’utilisateur de l’interface qui prend en charge la IFormatProvider mise en forme personnalisée. Pour plus d’informations, consultez la section Mise en forme personnalisée avec ICustomFormatter des types de mise en forme dans l’article .NET .

  3. Conversion d’une chaîne interpolée en instance IFormattable qui vous permet aussi de créer plusieurs chaînes de résultat avec du contenu propre à la culture à partir d’une seule instance de IFormattable.

L’exemple suivant utilise la conversion implicite en FormattableString pour créer des chaînes de résultat propres à la culture :

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.

Autres ressources

Si vous débutez avec l’interpolation de chaîne, consultez le didacticiel interactif Sur l’interpolation de chaîne dans C# . Vous pouvez également vérifier une autre interpolation de chaîne dans le didacticiel C# . Ce didacticiel montre comment utiliser des chaînes interpolées pour produire des chaînes mises en forme.

Compilation de chaînes interpolées

Si une chaîne interpolée est de type string, elle est généralement transformée en un appel de méthode String.Format. Le compilateur peut remplacer String.Format par String.Concat si le comportement analysé équivaut à une concaténation.

Si une chaîne interpolée est de type IFormattable ou FormattableString, le compilateur génère un appel à la méthode FormattableStringFactory.Create.

À compter de C# 10, lorsqu’une chaîne interpolée est utilisée, le compilateur vérifie si la chaîne interpolée est attribuée à un type qui satisfait au modèle de gestionnaire de chaîne interpolé. Un gestionnaire de chaîne interpolé est un type personnalisé qui convertit la chaîne interpolée en chaîne. Un gestionnaire de chaînes interpolé est un scénario avancé, généralement utilisé pour des raisons de performances. Vous pouvez en savoir plus sur les exigences de génération d’un gestionnaire de chaîne interpolé dans la spécification de langage pour les améliorations de chaîne interpolées. Vous pouvez créer un didacticiel suivant le didacticiel de gestionnaire de chaînes interpolé dans la section Nouveautés de C#. Dans .NET 6, lorsque vous utilisez une chaîne interpolée pour un argument de type string, la chaîne interpolée est traitée par le System.Runtime.CompilerServices.DefaultInterpolatedStringHandler.

Notes

L’un des effets secondaires des gestionnaires de chaînes interpolés est qu’un gestionnaire personnalisé, y compris System.Runtime.CompilerServices.DefaultInterpolatedStringHandler, ne peut pas évaluer toutes les expressions utilisées comme espaces réservés dans la chaîne interpolée sous toutes les conditions. Cela signifie que les effets secondaires dans ces expressions peuvent ne pas se produire.

spécification du langage C#

Pour plus d’informations, consultez la section Chaînes interpolées de la spécification du langage C#.

Voir aussi