Zeichenfolgeninterpolation in C#String interpolation in C#

In diesem Tutorial erfahren Sie, wie Sie die Zeichenfolgeninterpolation verwenden, um Ausdrucksergebnisse zu einer Ergebniszeichenfolge hinzuzufügen.This tutorial shows you how to use string interpolation to format and include expression results in a result string. Für diese Beispiele wird davon ausgegangen, dass Sie sich mit den grundlegenden C#-Konzepten und der .NET-Typformatierung auskennen.The examples assume that you are familiar with basic C# concepts and .NET type formatting. Wenn Sie sich mit der Zeichenfolgeninterpolation oder der .NET-Typformatierung nicht auskennen, absolvieren Sie zuerst das interaktive Tutorial zur Zeichenfolgeninterpolation.If you are new to string interpolation or .NET type formatting, check out the interactive string interpolation tutorial first. Weitere Informationen zum Formatieren von Typen in .NET finden Sie unter Formatieren von Typen in .NET.For more information about formatting types in .NET, see the Formatting Types in .NET topic.

Hinweis

Die C#-Beispiele in diesem Artikel werden in der Inlinecodeausführung und dem Playground von Try.NET ausgeführt.The C# examples in this article run in the Try.NET inline code runner and playground. Klicken Sie auf die Schaltfläche Ausführen, um ein Beispiel in einem interaktiven Fenster auszuführen.Select the Run button to run an example in an interactive window. Nachdem Sie den Code ausgeführt haben, können Sie ihn ändern und den geänderten Code durch erneutes Anklicken der Schaltfläche Ausführen ausführen.Once you execute the code, you can modify it and run the modified code by selecting Run again. Der geänderte Code wird entweder im interaktiven Fenster ausgeführt, oder das interaktive Fenster zeigt alle C#-Compilerfehlermeldungen an, wenn die Kompilierung fehlschlägt.The modified code either runs in the interactive window or, if compilation fails, the interactive window displays all C# compiler error messages.

EinführungIntroduction

Das Feature Zeichenfolgeninterpolation ist ein Zusatz zum Feature composite formating (Kombinierte Formatierung) und ermöglicht eine Syntax, die lesbarer und zweckmäßiger ist, um formatierte Ausdrucksergebnisse zu einer Ergebniszeichenfolge hinzuzufügen.The string interpolation feature is built on top of the composite formatting feature and provides a more readable and convenient syntax to include formatted expression results in a result string.

Wenn Sie ein Zeichenfolgenliteral als interpolierte Zeichenfolge ermitteln möchten, stellen Sie ihm ein $-Symbol voran.To identify a string literal as an interpolated string, prepend it with the $ symbol. Sie können jeden gültigen C#-Ausdruck einbetten, der einen Wert in einer interpolierten Zeichenfolge zurückgibt.You can embed any valid C# expression that returns a value in an interpolated string. Im folgenden Beispiel wird das Ergebnis eines Ausdrucks in eine Zeichenfolge konvertiert und zu einer Ergebniszeichenfolge hinzugefügt, sobald ein Ausdruck berechnet wird:In the following example, as soon as an expression is evaluated, its result is converted into a string and included in a result string:

double a = 3;
double b = 4;
Console.WriteLine($"Area of the right triangle with legs of {a} and {b} is {0.5 * a * b}");
Console.WriteLine($"Length of the hypotenuse of the right triangle with legs of {a} and {b} is {CalculateHypotenuse(a, b)}");

double CalculateHypotenuse(double leg1, double leg2) => Math.Sqrt(leg1 * leg1 + leg2 * leg2);

// Expected output:
// Area of the right triangle with legs of 3 and 4 is 6
// Length of the hypotenuse of the right triangle with legs of 3 and 4 is 5

Wie in dem Beispiel dargestellt, fügen Sie einen Ausdruck zu einer interpolierten Zeichenfolge hinzu, indem Sie diesen in Klammern setzen:As the example shows, you include an expression in an interpolated string by enclosing it with braces:

{<interpolationExpression>}

Interpolierte Zeichenfolgen unterstützen sämtliche Funktionen des Features kombinierte Formatierung von Zeichenfolgen.Interpolated strings support all the capabilities of the string composite formatting feature. Damit stellen sie eine lesbarere Alternative zur Verwendung der String.Format-Methode dar.That makes them a more readable alternative to the use of the String.Format method.

Angeben einer Formatierungszeichenfolge für einen InterpolationsausdruckHow to specify a format string for an interpolation expression

Sie können eine Formatzeichenfolge angeben, die von der Art des Ausdrucksergebnisses unterstützt wird, indem Sie den Interpolationsausdruck mit einem Doppelpunkt (:) und der Formatzeichenfolge versehen:You specify a format string that is supported by the type of the expression result by following the interpolation expression with a colon (":") and the format string:

{<interpolationExpression>:<formatString>}

Im folgenden Beispiel wird veranschaulicht, wie Sie Standardformatzeichenfolgen und benutzerdefinierte Formatzeichenfolgen für Ausdrücke angeben, die Datums- oder Uhrzeitergebnisse bzw. numerische Ergebnisse ausgeben:The following example shows how to specify standard and custom format strings for expressions that produce date and time or numeric results:

var date = new DateTime(1731, 11, 25);
Console.WriteLine($"On {date:dddd, MMMM dd, yyyy} Leonhard Euler introduced the letter e to denote {Math.E:F5} in a letter to Christian Goldbach.");

// Expected output:
// On Sunday, November 25, 1731 Leonhard Euler introduced the letter e to denote 2.71828 in a letter to Christian Goldbach.

Weitere Informationen finden Sie im Artikel Kombinierte Formatierung im Abschnitt Formatzeichenfolgenkomponente.For more information, see the Format String Component section of the Composite Formatting topic. In diesem Abschnitt finden Sie Links zu den Artikeln, in denen Standardzeichenfolgenkomponenten und benutzerdefinierte Zeichenfolgenkomponenten erläutert werden, die von den .NET-Basistypen unterstützt werden.That section provides links to the topics that describe standard and custom format strings supported by .NET base types.

Steuern der Feldbreite und -ausrichtung des formatierten InterpolationsausdrucksHow to control the field width and alignment of the formatted interpolation expression

Sie können die Mindestbreite und die Ausrichtung für das formatierte Ausdrucksergebnis angeben, indem Sie den Interpolationsausdruck mit einem Komma (,) und dem konstanten Ausdruck versehen:You specify the minimum field width and the alignment of the formatted expression result by following the interpolation expression with a comma (",") and the constant expression:

{<interpolationExpression>,<alignment>}

Wenn der Wert der Ausrichtung positiv ist, wird das formatierte Ausdrucksergebnis rechtsbündig ausgerichtet. Ist der Wert negativ, wird das Ergebnis linksbündig ausgerichtet.If the alignment value is positive, the formatted expression result is right-aligned; if negative, it's left-aligned.

Wenn Sie sowohl die Ausrichtung als auch die Formatzeichenfolge angeben müssen, beginnen Sie mit der Ausrichtungskomponente:If you need to specify both alignment and a format string, start with the alignment component:

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

Im folgenden Beispiel sehen Sie, wie Sie die Ausrichtung angeben. Es werden senkrechte Striche („|“) verwendet, um Textfelder zu begrenzen:The following example shows how to specify alignment and uses pipe characters ("|") to delimit text fields:

const int NameAlignment = -9;
const int ValueAlignment = 7;

double a = 3;
double b = 4;
Console.WriteLine($"Three classical Pythagorean means of {a} and {b}:");
Console.WriteLine($"|{"Arithmetic",NameAlignment}|{0.5 * (a + b),ValueAlignment:F3}|");
Console.WriteLine($"|{"Geometric",NameAlignment}|{Math.Sqrt(a * b),ValueAlignment:F3}|");
Console.WriteLine($"|{"Harmonic",NameAlignment}|{2 / (1 / a + 1 / b),ValueAlignment:F3}|");

// Expected output:
// Three classical Pythagorean means of 3 and 4:
// |Arithmetic|  3.500|
// |Geometric|  3.464|
// |Harmonic |  3.429|

Wie Sie in der Beispielausgabe sehen können, wird der Wert Ausrichtung ignoriert, wenn die Länge des formatierten Ausdrucksergebnisses über die angegebene Feldbreite hinausgeht.As the example output shows, if the length of the formatted expression result exceeds specified field width, the alignment value is ignored.

Weitere Informationen finden Sie im Artikel Kombinierte Formatierung im Abschnitt Ausrichtungskomponente.For more information, see the Alignment Component section of the Composite Formatting topic.

Verwenden von Escapesequenzen in einer interpolierten ZeichenfolgeHow to use escape sequences in an interpolated string

Interpolierte Zeichenfolgen unterstützen alle Escapesequenzen, die in gewöhnlichen Zeichenfolgenliteralen verwendet werden können.Interpolated strings support all escape sequences that can be used in ordinary string literals. Weitere Informationen finden Sie unter Zeichenfolgenescapesequenzen.For more information, see String escape sequences.

Verwenden Sie ein ausführliches Zeichenfolgenliteral, um Escapesequenzen wörtlich zu interpretieren.To interpret escape sequences literally, use a verbatim string literal. Ausführliche interpolierte Zeichenfolgen beginnen mit dem Zeichen $, gefolgt vom Zeichen @.An interpolated verbatim string starts with the $ character followed by the @ character. Ab C# 8.0 können Sie die Token $ und @ in beliebiger Reihenfolge verwenden: Sowohl $@"..." als auch @$"..." sind gültige interpolierte ausführliche Zeichenfolgen.Starting with C# 8.0, you can use the $ and @ tokens in any order: both $@"..." and @$"..." are valid interpolated verbatim strings.

Wenn Sie einer Ergebniszeichenfolge eine Klammer hinzufügen möchten „{“ oder „}“, sollten Sie jeweils zwei Klammern verwenden: „{{“ oder „}}“.To include a brace, "{" or "}", in a result string, use two braces, "{{" or "}}". Weitere Informationen finden Sie im Artikel Kombinierte Formatierung im Abschnitt Versehen von geschweiften Klammern mit Escapezeichen.For more information, see the Escaping Braces section of the Composite Formatting topic.

Im folgenden Beispiel wird dargestellt, wie Sie Klammern zu einer Ergebniszeichenfolge hinzufügen und eine ausführliche interpolierte Zeichenfolge erstellen:The following example shows how to include braces in a result string and construct a verbatim interpolated string:

var xs = new int[] { 1, 2, 7, 9 };
var ys = new int[] { 7, 9, 12 };
Console.WriteLine($"Find the intersection of the {{{string.Join(", ",xs)}}} and {{{string.Join(", ",ys)}}} sets.");

var userName = "Jane";
var stringWithEscapes = $"C:\\Users\\{userName}\\Documents";
var verbatimInterpolated = $@"C:\Users\{userName}\Documents";
Console.WriteLine(stringWithEscapes);
Console.WriteLine(verbatimInterpolated);

// Expected output:
// Find the intersection of the {1, 2, 7, 9} and {7, 9, 12} sets.
// C:\Users\Jane\Documents
// C:\Users\Jane\Documents

Verwenden eines ternären bedingten ?:-Operators in einem InterpolationsausdruckHow to use a ternary conditional operator ?: in an interpolation expression

Da der Doppelpunkt (:) in einem Element mit einem Interpolationsausdruck eine besondere Funktion einnimmt, müssen Sie diesen Ausdruck wie folgt in runde Klammern einschließen, um einen Bedingungsoperator verwenden zu können:As the colon (":") has special meaning in an item with an interpolation expression, in order to use a conditional operator in an expression, enclose it in parentheses, as the following example shows:

var rand = new Random();
for (int i = 0; i < 7; i++)
{
    Console.WriteLine($"Coin flip: {(rand.NextDouble() < 0.5 ? "heads" : "tails")}");
}

Erstellen einer kulturspezifischen Ergebniszeichenfolge mit einer ZeichenfolgeninterpolationHow to create a culture-specific result string with string interpolation

Standardmäßig verwendet eine interpolierte Zeichenfolge die aktuelle Kultur, die von der CultureInfo.CurrentCulture-Eigenschaft für alle Formatierungsvorgänge definiert ist.By default, an interpolated string uses the current culture defined by the CultureInfo.CurrentCulture property for all formatting operations. Verwenden Sie für eine interpolierte Zeichenfolge einen impliziten Wechsel in eine System.FormattableString-Instanz, und rufen Sie deren ToString(IFormatProvider)-Methode auf, um eine kulturspezifische Ergebniszeichenfolge zu erstellen.Use implicit conversion of an interpolated string to a System.FormattableString instance and call its ToString(IFormatProvider) method to create a culture-specific result string. Das folgende Beispiel zeigt, wie Sie dabei vorgehen müssen:The following example shows how to do that:

var cultures = new System.Globalization.CultureInfo[]
{
    System.Globalization.CultureInfo.GetCultureInfo("en-US"),
    System.Globalization.CultureInfo.GetCultureInfo("en-GB"),
    System.Globalization.CultureInfo.GetCultureInfo("nl-NL"),
    System.Globalization.CultureInfo.InvariantCulture
};

var date = DateTime.Now;
var number = 31_415_926.536;
FormattableString message = $"{date,20}{number,20:N3}";
foreach (var culture in cultures)
{
    var cultureSpecificMessage = message.ToString(culture);
    Console.WriteLine($"{culture.Name,-10}{cultureSpecificMessage}");
}

// Expected output is like:
// en-US       5/17/18 3:44:55 PM      31,415,926.536
// en-GB      17/05/2018 15:44:55      31,415,926.536
// nl-NL        17-05-18 15:44:55      31.415.926,536
//            05/17/2018 15:44:55      31,415,926.536

Wie in dem Beispiel dargestellt, können Sie eine FormattableString-Instanz verwenden, um mehrere Ergebniszeichenfolgen für verschiedene Kulturen zu generieren.As the example shows, you can use one FormattableString instance to generate multiple result strings for various cultures.

Erstellen einer Ergebniszeichenfolge mithilfe der invarianten KulturHow to create a result string using the invariant culture

Neben der FormattableString.ToString(IFormatProvider)-Methode können Sie die statische FormattableString.Invariant-Methode verwenden, um eine interpolierte Zeichenfolge in eine Ergebniszeichenfolge für InvariantCulture auszulösen.Along with the FormattableString.ToString(IFormatProvider) method, you can use the static FormattableString.Invariant method to resolve an interpolated string to a result string for the InvariantCulture. Das folgende Beispiel zeigt, wie Sie dabei vorgehen müssen:The following example shows how to do that:

string messageInInvariantCulture = FormattableString.Invariant($"Date and time in invariant culture: {DateTime.Now}");
Console.WriteLine(messageInInvariantCulture);

// Expected output is like:
// Date and time in invariant culture: 05/17/2018 15:46:24

SchlussbemerkungConclusion

In diesem Tutorial wurden häufig auftretende Szenarios zur Verwendung der Zeichenfolgeninterpolation beschrieben.This tutorial describes common scenarios of string interpolation usage. Weitere Informationen zur Zeichenfolgeninterpolation finden Sie unter Zeichenfolgeninterpolation.For more information about string interpolation, see the String interpolation topic. Weitere Informationen zum Formatieren von Typen in .NET finden Sie unter Formatieren von Typen in .NET und Kombinierte Formatierung.For more information about formatting types in .NET, see the Formatting Types in .NET and Composite formatting topics.

Siehe auchSee also