Zeichenfolgeninterpolation mit $

Das Zeichen $ kennzeichnet ein Zeichenfolgenliteral als interpolierte Zeichenfolge. Eine interpolierte Zeichenfolge ist ein Zeichenfolgenliteral, das möglicherweise Interpolationsausdrücke enthält. Wenn eine interpolierte Zeichenfolge in eine Ergebniszeichenfolge aufgelöst wird, ersetzt der Compiler Elemente mit Interpolationsausdrücken durch die Zeichenfolgendarstellungen der Ausdrucksergebnisse.

Die Zeichenfolgeninterpolation bietet eine lesbarere, benutzerfreundliche Syntax zum Formatieren von Zeichenfolgen. Sie ist einfacher zu lesen als die zusammengesetzte Formatierung von Zeichenfolgen. Im folgenden Beispiel wird mit beiden Features die gleiche Ausgabe erzeugt:

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.

Ab C# 10 können Sie mithilfe einer interpolierten Zeichenfolge eine konstante Zeichenfolge initialisieren. Dies ist nur möglich, wenn alle Interpolationsausdrücke innerhalb der interpolierten Zeichenfolge auch konstante Zeichenfolgen sind.

Struktur einer interpolierten Zeichenfolge

Wenn Sie ein Zeichenfolgenliteral als interpolierte Zeichenfolge ermitteln möchten, stellen Sie ihm ein $-Symbol voran. Zwischen $ und " am Anfang des Zeichenfolgenliterals dürfen sich keine Leerzeichen befinden.

Die Struktur eines Elements mit einem Interpolationsausdruck sieht wie folgt aus:

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

Elemente in eckigen Klammern sind optional. In der folgenden Tabelle wird jedes Element beschrieben:

Im folgenden Beispiel werden die in der vorherigen Tabelle beschriebenen Formatierungskomponenten verwendet:

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

Ab C# 11 können Sie Neue-Zeile-Zeichen in einem Interpolationsausdruck verwenden, um den Code des Ausdrucks übersichtlicher zu gestalten. Das folgende Beispiel zeigt, wie Zeilenumbrüche die Lesbarkeit eines Ausdrucks mit Musterabgleich verbessern können:

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

Interpolierte Rohzeichenfolgenliterale

Ab C# 11 können Sie ein interpoliertes Rohzeichenfolgenliteral verwenden, wie das folgende Beispiel zeigt:

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

Um die Zeichen { und } in die Ergebniszeichenfolge einzubetten, beginnen Sie ein interpoliertes Rohzeichenfolgenliteral mit mehreren $-Zeichen. In diesem Fall wird jede Abfolge der Zeichen { und }, die kürzer als die Anzahl der $-Zeichen ist, in die Ergebniszeichenfolge eingebettet. Um einen Interpolationsausdruck in diese Zeichenfolge einzuschließen, muss die verwendete Anzahl geschweifter Klammern mit der Anzahl der $-Zeichen übereinstimmen, wie im folgenden Beispiel gezeigt:

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}

Im obigen Beispiel beginnt ein interpoliertes Rohzeichenfolgenliteral mit zwei $-Zeichen. Sie müssen jeden Interpolationsausdruck zwischen doppelten geschweiften Klammern ({{ und }}) platzieren. Eine einzelne geschweifte Klammer wird in eine Ergebniszeichenfolge eingebettet. Wenn Sie wiederholte {- oder }-Zeichen in eine Ergebniszeichenfolge einbetten müssen, verwenden Sie eine entsprechend höhere Anzahl von $-Zeichen, um ein interpoliertes Rohzeichenfolgenliteral festzulegen. Wenn das Zeichenfolgenliteral wiederholte geschweifte Klammern aufweist als die Anzahl der $ Zeichen, werden die { Zeichen } von innen nach außen gruppiert. Im vorherigen Beispiel interpretiert das Literal The point {{{X}}, {{Y}}} {{X}} und {{Y}} als interpolierte Ausdrücke. Die äußeren { und } sind in der Ausgabezeichenfolge enthalten.

Sonderzeichen

Wenn eine geschweifte Klammer („{“ oder „}“) im Text angezeigt werden soll, der durch die interpolierte Zeichenfolge erstellt wird, müssen Sie zwei geschweifte Klammern verwenden, also „{{“ oder „}}“. Weitere Informationen finden Sie im Artikel Kombinierte Formatierung im Abschnitt Versehen von geschweiften Klammern mit Escapezeichen.

Da der Doppelpunkt („:“) in einem Element eines Interpolationsausdrucks eine besondere Funktion einnimmt, müssen Sie zur Verwendung eines Bedingungsoperators in einem Interpolationsausdruck diesen Ausdruck einschließen. Schließen Sie diesen Ausdruck in Klammern ein.

Im folgenden Beispiel wird gezeigt, wie Sie eine runde Klammer in eine Ergebniszeichenfolge einschließen. Außerdem wird die Verwendung eines bedingten Operators gezeigt:

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.

Eine interpolierte ausführliche Zeichenfolge beginnt mit den Zeichen $ und @. Sie können $ und @ in beliebiger Reihenfolge verwenden: Sowohl $@"..." als auch @$"..." sind gültige interpolierte ausführliche Zeichenfolgen. Weitere Informationen zu ausführlichen Zeichenfolgen finden Sie in den Artikeln zu Zeichenfolgen und ausführlichen Bezeichnern.

Kulturspezifische Formatierung

Standardmäßig verwendet eine interpolierte Zeichenfolge die aktuelle Kultur, die von der CultureInfo.CurrentCulture-Eigenschaft für alle Formatierungsvorgänge definiert ist.

Um eine interpolierte Zeichenfolge in eine kulturspezifische Ergebniszeichenfolge aufzulösen, verwenden Sie die String.Create(IFormatProvider, DefaultInterpolatedStringHandler)-Methode, die ab .NET 6 verfügbar ist. Das folgende Beispiel zeigt, wie Sie dabei vorgehen müssen:

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.

Verwenden Sie in .NET 5 und früheren Versionen von .NET die implizite Konvertierung einer interpolierten Zeichenfolge in eine FormattableString-Instanz. Anschließend können Sie die FormattableString.ToString(IFormatProvider)-Methode einer Instanz oder eine statische FormattableString.Invariant-Methode verwenden, um eine kulturspezifische Ergebniszeichenfolge zu generieren. Das folgende Beispiel zeigt, wie Sie dabei vorgehen müssen:

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.

Weitere Informationen zur benutzerdefinierten Formatierung finden Sie im Artikel Formatieren von Typen in .NET im Abschnitt Benutzerdefinierte Formatierung mit ICustomFormatter.

Weitere Ressourcen

Wenn Sie noch nicht mit der Zeichenfolgeninterpolation vertraut sind, finden Sie weitere Informationen im interaktiven Tutorial Zeichenfolgeninterpolation in C#. Sie können sich auch ein weiteres Tutorial zur Zeichenfolgeninterpolation in C# ansehen. Dieses Tutorial demonstriert die Verwendung interpolierter Zeichenfolgen zum Erzeugen formatierter Zeichenfolgen.

Kompilierung interpolierter Zeichenfolgen

Ab C# 10 und .NET 6 überprüft der Compiler, ob eine interpolierte Zeichenfolge einem Typ zugewiesen ist, der das Muster von Handlern für interpolierte Zeichenfolgen erfüllt. Ein Handler für interpolierte Zeichenfolgen ist ein Typ, der die interpolierte Zeichenfolge in eine Ergebniszeichenfolge konvertiert. Wenn eine interpolierte Zeichenfolge den Typ string aufweist, wird sie vom System.Runtime.CompilerServices.DefaultInterpolatedStringHandler verarbeitet. Ein Beispiel für einen benutzerdefinierten Handler für interpolierte Zeichenfolgen finden Sie im Tutorial Schreiben eines benutzerdefinierten Zeichenfolgeninterpolationshandlers. Der Einsatz eines Handlers für interpolierte Zeichenfolgen stellt ein erweitertes Szenario dar, das in der Regel aus Leistungsgründen erforderlich ist.

Wenn eine interpolierte Zeichenfolge vor C# 10 vom Typ string ist, wird sie in der Regel in einen String.Format-Methodenaufruf transformiert. Der Compiler ersetzt String.Format möglicherweise mit String.Concat, wenn das analysierte Verhalten mit der Verkettung übereinstimmt.

Wenn eine interpolierte Zeichenfolge vom Typ IFormattable oder FormattableString ist, generiert der Compiler einen Aufruf der FormattableStringFactory.Create-Methode.

C#-Sprachspezifikation

Weitere Informationen finden Sie im Abschnitt Interpolierte Zeichenfolgenausdrücke der C#-Sprachspezifikation und in den folgenden neuen Featurespezifikationen:

• C# 10: verbesserte interpolierte Zeichenfolgen
• C# 11 – UTF-8-Zeichenfolgenliterale
• C# 11: Neue-Zeile-Zeichen in Zeichenfolgeninterpolationen

Weitere Informationen

• C#-Sonderzeichen
• Zeichenfolgen
• Standardmäßige Zahlenformatzeichenfolgen
• Kombinierte Formatierung
• String.Format
• Die Interpolation vereinfachen (Stilregel IDE0071)
• Zeichenfolgeninterpolation in C# 10 und .NET 6 (.NET-Blog)