$ – Zeichenfolgeninterpolation (C#-Referenz)

Das Sonderzeichen $ 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, werden Elemente mit Interpolationsausdrücken durch die Zeichenfolgendarstellungen der Ausdrucksergebnisse ersetzt. Dieses Feature ist ab C# 6 verfügbar.

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:

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.

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. Um mehrere interpolierte Zeichenfolgen zu verketten, fügen Sie jedem Zeichenfolgen literal das $ Sonderzeichen hinzu.

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:

Element Beschreibung
interpolationExpression Der Ausdruck, der zu einem Ergebnis führt, das formatiert werden soll. Die Zeichenfolgendarstellung von null lautet String.Empty.
alignment Der konstante Ausdruck, dessen Wert die Mindestanzahl von Zeichen in der Zeichenfolgendarstellung des Ausdrucksergebnisses definiert. Bei einem positiven Wert wird die Zeichenfolge rechtsbündig ausgerichtet. Ist der Wert negativ, wird sie linksbündig ausgerichtet. Weitere Informationen finden Sie unter Ausrichtungskomponente.
formatString Eine Formatierungszeichenfolge oder benutzerdefinierte Formatierungszeichenfolge, die durch den Typ des Ausdrucksergebnisses unterstützt wird. Weitere Informationen finden Sie unter Formatzeichenfolgen-Komponente.

Im folgenden Beispiel werden die oben 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");
// Expected 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# 10 können Sie mithilfe der Zeichenfolgeninterpolation eine konstante Zeichenfolge initialisieren. Alle für Platzhalter verwendeten Ausdrücke müssen konstante Zeichenfolgen sein. Mit anderen Worten: Jeder Interpolationsausdruck muss eine Zeichenfolge und zudem eine Kompilierzeitkonstante sein.

Ab C# 11 können die interpolierten Ausdrücke neue Linien enthalten. Der Text zwischen dem und } dem { gültigen C#-Objekt kann daher neue Linien enthalten, die die Lesbarkeit verbessern. Im folgenden Beispiel wird gezeigt, wie newlines die Lesbarkeit eines Ausdrucks verbessern können, der Musterabgleich umfasst:

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

Außerdem können Sie ab C# 11 eine unformatierte Zeichenfolge literal für die Formatzeichenfolge verwenden:

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.

Sie können mehrere $ Zeichen in einer interpolierten unformatierten Zeichenfolge verwenden, um die Ausgabezeichenfolge einzubetten und Zeichen einzubetten { , } ohne sie auszufangen:

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.

Wenn Ihre Ausgabezeichenfolge wiederholte { oder } Zeichen enthalten soll, können Sie mehr $ hinzufügen, um die interpolierte Zeichenfolge festzulegen. Jede Sequenz von { oder } kürzer als die Anzahl $ wird in die Ausgabezeichenfolge eingebettet. Wie im vorherigen Beispiel gezeigt, werden Sequenzen länger als die Sequenz von $ Zeichen in die {} Ausgabe eingebettet. Der Compiler gibt einen Fehler aus, wenn die Sequenz von Klammernzeichen gleich oder größer als doppelt die Länge der Zeichenfolge $ ist.

Sie können diese Features mithilfe des .NET 7 SDK testen. Oder wenn Sie über das .NET SDK 6.00.200 oder höher verfügen, können Sie das <LangVersion> Element in Ihrer csproj-Datei auf previewfestlegen.

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 unter 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 in runde Klammern einschließen.

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.");
// Expected output is:
// He asked, "Is your name Horace?", but didn't wait for a reply :-{
// Horace is 34 years old.

Ausführliche interpolierte Zeichenfolgen beginnen mit dem Zeichen $, gefolgt vom Zeichen @. Weitere Informationen zu ausführlichen Zeichenfolgen finden Sie in den Artikeln zu Zeichenfolgen und ausführlichen Bezeichnern.

Hinweis

Ab C# 8.0 können Sie die Token $ und @ in beliebiger Reihenfolge verwenden: Sowohl $@"..." als auch @$"..." sind gültige interpolierte ausführliche Zeichenfolgen. In früheren C#-Versionen musste das Token $ vor dem Token @ vorhanden sein.

Implizite Konvertierungen und Angeben der IFormatProvider-Implementierung

Es gibt drei implizite Konvertierungen aus einer interpolierten Zeichenfolge:

  1. Die Konvertierung einer interpolierten Zeichenfolge in eine String-Instanz. Die Zeichenfolge ist das Ergebnis der Auflösung der interpolierten Zeichenfolge. Alle Elemente eines Interpolationsausdrucks werden durch die ordnungsgemäß formatierten Zeichenfolgendarstellungen ihrer Ergebnisse ersetzt. Diese Konvertierung verwendet CurrentCulture zum Formatieren von Ausdrucksergebnissen.

  2. Konvertierung einer interpolierten Zeichenfolge in eine FormattableString-Instanz, die eine zusammengesetzte Formatzeichenfolge mit den zu formatierenden Ausdrucksergebnissen darstellt. Dadurch können Sie aus einer einzigen FormattableString-Instanz mehrere Ergebniszeichenfolgen mit kulturspezifischem Inhalt erstellen. Rufen Sie hierzu eine der folgenden Methoden auf:

    ToString(IFormatProvider) bietet eine benutzerdefinierte Implementierung der IFormatProvider-Schnittstelle, die das benutzerdefinierte Formatieren unterstützt. Weitere Informationen finden Sie im Abschnitt Benutzerdefinierte Formatierung mit ICustomFormatter des Artikels Formatieren von Typen in .NET.

  3. Konvertierung einer interpolierten Zeichenfolge in eine IFormattable-Instanz, die Ihnen das Erstellen mehrerer Ergebniszeichenfolgen mit kulturspezifischem Inhalt aus einer einzigen IFormattable-Instanz ermöglicht.

Im folgenden Beispiel wird die implizite Konvertierung in FormattableString zum Erstellen kulturspezifischer Ergebniszeichenfolgen verwendet:

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.

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

Wenn eine interpolierte Zeichenfolge vom Typ string ist, wird sie in der Regel in einen String.Format-Methodenaufruf transformiert. Der Compiler ersetzt String.Concat möglicherweise mit einem String.Format, 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.

Ab C# 10 überprüft der Compiler bei Verwendung einer interpolierten Zeichenfolge, ob diese einem Typ zugewiesen ist, der das Muster von Handlern für interpolierte Zeichenfolgen erfüllt. Ein Handler für interpolierte Zeichenfolgen ist ein benutzerdefinierter Typ, der die interpolierte Zeichenfolge in eine Zeichenfolge konvertiert. Ein Handler für interpolierte Zeichenfolgen stellt ein erweitertes Szenario dar, das in der Regel aus Leistungsgründen verwendet wird. Informationen zu den Anforderungen zum Erstellen eines Handlers für interpolierte Zeichenfolgen finden Sie in der Sprachspezifikation für Verbesserungen interpolierter Zeichenfolgen. Im Tutorial zu Handlern für interpolierte Zeichenfolgen können Sie einen Handler im Abschnitt „Neuerungen in C#“ erstellen. Wenn Sie in .NET 6 eine interpolierte Zeichenfolge für ein Argument vom Typ string verwenden, wird die interpolierte Zeichenfolge vom System.Runtime.CompilerServices.DefaultInterpolatedStringHandler verarbeitet.

Hinweis

Ein Nebeneffekt von Handlern für interpolierte Zeichenfolgen besteht darin, dass ein benutzerdefinierter Handler, einschließlich System.Runtime.CompilerServices.DefaultInterpolatedStringHandler, nicht immer alle Ausdrücke auswerten kann, die als Platzhalter in der interpolierten Zeichenfolge verwendet werden. Das bedeutet, dass in diesen Ausdrücken keine Nebeneffekte auftreten können.

C#-Sprachspezifikation

Weitere Informationen finden Sie im Abschnitt Interpolierte Zeichenfolgen der C#-Sprachspezifikation.

Siehe auch