Interpolation de chaîne à l’aide de $

  • Article

Le caractère $ 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, le compilateur remplace les éléments avec des expressions d’interpolation les représentations sous forme de chaîne des résultats des expressions.

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

var 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.

À partir de C# 10, vous pouvez utiliser une chaîne interpolée pour initialiser une chaîne constante. Vous pouvez le faire uniquement si toutes les expressions d’interpolation au sein de la chaîne interpolée sont également des chaînes constantes.

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 $. N’ajoutez pas d’espace blanc entre les signes $ et " au début d’un 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. Lorsque l’expression est null, la sortie est la chaîne vide (String.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 la section Composant d’alignement de l’article Mise en forme composite.
formatString Chaîne de format prise en charge par le type de résultat de l’expression. Pour plus d’informations, consultez la section Composant de chaîne de mise en forme de l’article Mise en forme composite.

L’exemple suivant utilise les composants de mise en forme facultatifs décrits dans le tableau précédent :

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");
// 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# 11, vous pouvez utiliser de nouvelles lignes dans une expression d’interpolation pour rendre le code de l’expression plus lisible. L’exemple suivant montre comment les nouvelles lignes peuvent améliorer la lisibilité d’une expression impliquant des critères spéciaux :

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",
    }
    }";

Littéraux de chaîne brute interpolés

À compter de C# 11, vous pouvez utiliser un littéral de chaîne brute interpolé, comme l’illustre l’exemple suivant :

int X = 2;
int Y = 3;

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

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

Pour incorporer les caractères { et } dans la chaîne de résultat, démarrez un littéral de chaîne brut interpolé avec plusieurs caractères $. Lorsque vous faites cela, toute séquence de caractères { ou } plus courte que le nombre de caractères $ est incorporée dans la chaîne de résultat. Pour placer une expression d’interpolation dans cette chaîne, vous devez utiliser le même nombre d’accolades que le nombre de caractères $, comme illustre l’exemple suivant :

int X = 2;
int Y = 3;

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

Dans l’exemple précédent, un littéral de chaîne brute interpolé commence par deux caractères $. Vous devez placer chaque expression d’interpolation entre accolades doubles {{ et }}. Une seule accolade est incorporée dans une chaîne de résultat. Si vous devez incorporer des caractères répétés { ou } dans une chaîne de résultat, utilisez un nombre $ de caractères suffisamment élevé pour désigner un littéral de chaîne brute interpolé. Si le littéral de chaîne a plus d’accolades répétées que le nombre de caractères $, les caractères { et } sont regroupés de l’intérieur vers l’extérieur. Dans l’exemple précédent, le littéral The point {{{X}}, {{Y}}} interprète {{X}} et {{Y}} en tant qu’expressions interpolées. Les { et } externes sont inclus verbatim dans la chaîne de sortie.

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 la section Accolades d’échappement de l’article Mise en forme composite.

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

L’exemple suivant montre comment inclure une accolade dans une chaîne de résultats. 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.");
// Output is:
// He asked, "Is your name Horace?", but didn't wait for a reply :-{
// Horace is 34 years old.

Une chaîne verbatim interpolée commence par les deux caractères $ et @. Vous pouvez utiliser $ et @ dans n’importe quel ordre : $@"..." et @$"..." sont toutes deux des chaînes verbatim interpolées valides. Pour plus d’informations sur les chaînes verbatim, consultez les articles Chaîne et Identificateur verbatim.

Mise en forme spécifique à la culture

Par défaut, une chaîne interpolée utilise la culture active définie par la propriété CultureInfo.CurrentCulture pour toutes les opérations de mise en forme.

Pour résoudre une chaîne interpolée en chaîne de résultat spécifique à la culture, utilisez la méthode String.Create(IFormatProvider, DefaultInterpolatedStringHandler), qui est disponible à partir de .NET 6. L’exemple suivant montre comment effectuer cette opération :

double speedOfLight = 299792.458;

System.Globalization.CultureInfo.CurrentCulture = System.Globalization.CultureInfo.GetCultureInfo("nl-NL");
string messageInCurrentCulture = $"The speed of light is {speedOfLight:N3} km/s.";

var specificCulture = System.Globalization.CultureInfo.GetCultureInfo("en-IN");
string messageInSpecificCulture = string.Create(
    specificCulture, $"The speed of light is {speedOfLight:N3} km/s.");

string messageInInvariantCulture = string.Create(
    System.Globalization.CultureInfo.InvariantCulture, $"The speed of light is {speedOfLight:N3} km/s.");

Console.WriteLine($"{System.Globalization.CultureInfo.CurrentCulture,-10} {messageInCurrentCulture}");
Console.WriteLine($"{specificCulture,-10} {messageInSpecificCulture}");
Console.WriteLine($"{"Invariant",-10} {messageInInvariantCulture}");
// 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.

Dans .NET 5 et versions antérieures de .NET, utilisez la conversion implicite d’une chaîne interpolée en une instance FormattableString . Ensuite, vous pouvez utiliser une méthode d’instance FormattableString.ToString(IFormatProvider) ou une méthode statique FormattableString.Invariant pour produire une chaîne de résultat spécifique à la culture. L’exemple suivant montre comment effectuer cette opération :

double speedOfLight = 299792.458;
FormattableString message = $"The speed of light is {speedOfLight:N3} km/s.";

var specificCulture = System.Globalization.CultureInfo.GetCultureInfo("en-IN");
string messageInSpecificCulture = message.ToString(specificCulture);
Console.WriteLine(messageInSpecificCulture);
// Output:
// The speed of light is 2,99,792.458 km/s.

string messageInInvariantCulture = FormattableString.Invariant(message);
Console.WriteLine(messageInInvariantCulture);
// Output is:
// The speed of light is 299,792.458 km/s.

Pour plus d’informations sur la lise en forma personnalisée, consultez la section Mise en forme personnalisée avec ICustomFormatter de l’article Types de mise en forme dans .NET.

Autres ressources

Si vous débutez en matière d’interpolation de chaîne, consultez le tutoriel interactif Interpolation de chaîne en C#. Vous pouvez également consulter un autre tutoriel Interpolation de chaîne en C#. Ce tutoriel montre comment utiliser des chaînes interpolées pour produire des chaînes mises en forme.

Compilation de chaînes interpolées

À compter de C# 10 et .NET 6, le compilateur vérifie si une chaîne interpolée est affectée à un type qui satisfait au modèle de gestionnaire de chaîne interpolé. Un gestionnaire de chaîne interpolée est un type qui convertit la chaîne interpolée en chaîne de résultat. Lorsqu’une chaîne interpolée a le type string, elle est traitée par System.Runtime.CompilerServices.DefaultInterpolatedStringHandler. Pour obtenir l’exemple d’un gestionnaire de chaînes interpolé personnalisé, consultez le didacticiel Écrire un gestionnaire d’interpolation de chaîne personnalisé. L’utilisation d’un gestionnaire de chaîne interpolée est un scénario avancé, généralement nécessaire pour des raisons de performances.

Remarque

L’un des effets secondaires des gestionnaires de chaînes interpolées est que, un gestionnaire personnalisé, y compris System.Runtime.CompilerServices.DefaultInterpolatedStringHandler, peut ne pas évaluer toutes les expressions d’interpolations dans la chaîne interpolée dans toutes les conditions. Cela peut se traduire par l’absence d’effets secondaires dans ces expressions.

Avant C# 10, 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.

spécification du langage C#

Pour plus d’informations, consultez la section Expressions des chaînes interpolées de la Spécification du langage C# et les nouvelles spécifications de fonctionnalités suivantes :

Voir aussi