Use string interpolation to construct formatted strings
This tutorial teaches you how to use string interpolation to insert values into a single string. You also learn how to control text formatting of the result string. You use your browser to write and run C# code and can immediately see the results.
Create an interpolated string
Run the following code in the interactive window. Select the Enter focus mode button. Then, type the following code block in the interactive window (replace <name> with your name) and select Run:
var name = "<name>";
Console.WriteLine($"Hello, {name}. It's a pleasure to meet you!");
When you run the code, Output displays a string that includes your name in the greeting. The string argument of the WriteLine method call is an interpolated string expression. It's a kind of template that lets you construct a single string (called the result string) from a string that includes embedded code. Interpolated string expressions are particularly useful for inserting values into a string or concatenating (joining together) several strings.
The example above contains the two elements that every interpolated string expression must have:
A string literal that begins with the
$character before its opening quotation mark character. There can't be any spaces between the$symbol and the quotation mark character. (If you'd like to see what happens if you include one, insert a space after the$character in the interactive window and run the updated code. The C# compiler complains, "Unexpected character '$'".)One or more interpolation expressions. An interpolation expression is indicated by an opening and closing brace (
{and}). You can put any C# expression that returns a value (includingnull) inside the braces.
Let's try a few more string interpolation examples with some other data types.
Include different data types
In the previous step, you used string interpolation to insert one string inside of another. Each interpolation expression that is part of an interpolated string expression can be of any data type, though. Let's include values of various data type expressions in an interpolated string.
In the following example, we first define a tuple that has Name, Price, and perPackage members. Run the following code in the interactive window:
var item = (Name: "eggplant", Price: 1.99m, perPackage: 3);
var date = DateTime.Now;
Console.WriteLine($"On {date}, the price of {item.Name} was {item.Price} per {item.perPackage} items.");
Note that the interpolation expression item.Price in the interpolated string resolves to the text "1.99" in the result string. That's because, when the type of the expression result is not a string, the result is resolved to a string in the following way:
If the interpolation expression evaluates to
null, an empty string ("", or String.Empty) is used.If the interpolation expression doesn't evaluate to
null, typically theToStringmethod of the result expression is called.
In the output from this example, the date is too precise (the price of eggplant doesn't change every second), and the price value doesn't indicate a unit of currency. In the next step, you'll learn how to fix those issues by controlling the format of string representations of the expression results.
Control the formatting of interpolation expressions
In the previous step, two poorly formatted strings were inserted into the result string. One was a date and time value for which only the date was appropriate. The second was a price that didn't indicate its unit of currency. Both issues are easy to address. String interpolation lets you specify format strings that control the formatting of particular types. Modify the call to Console.WriteLine from the previous example to include the format strings for the date and price expressions as shown in the following line:
Console.WriteLine($"On {date:d}, the price of {item.Name} was {item.Price:C2} per {item.perPackage} items");
You specify a format string by following the interpolation expression with a colon (":") and the format string. "d" is a standard date and time format string that represents the short date format. "C2" is a standard numeric format string that represents a number as a currency value with two digits after the decimal point.
A number of types in the .NET libraries support a predefined set of format strings. These include all the numeric types and the date and time types. For a complete list of types that support format strings, see Format Strings and .NET Class Library Types in the Formatting Types in .NET article.
Try modifying the format strings in the example to see how they affect the formatting of the date and time and the numeric value. Change the "d" in {date:d} to "t" (to display the short time format), "y" (to display the year and month), and "yyyy" (to display the year as a four-digit number). Change the "C2" in {price:C2} to "e" (for exponential notation) and "F3" (for a numeric value with three digits after the decimal point).
In addition to controlling formatting, you can also control the field width and alignment of the formatted strings that are included in the result string. In the next step, you'll learn how to do this.
Control the field width and alignment of interpolation expressions
Ordinarily, when the result of an interpolated string expression is formatted to string, that string is included in a result string without leading or trailing spaces. Particularly when you work with a set of data, being able to control a field width and text alignment helps to produce a more readable output. To see this, run the following code:
var inventory = new Dictionary<string, int>()
{
["hammer, ball pein"] = 18,
["hammer, cross pein"] = 5,
["screwdriver, Phillips #2"] = 14
};
Console.WriteLine($"Inventory on {DateTime.Now:d}");
Console.WriteLine(" ");
Console.WriteLine($"|{"Item",-25}|{"Quantity",10}|");
foreach (var item in inventory)
Console.WriteLine($"|{item.Key,-25}|{item.Value,10}|");
The item names are left-aligned, and their quantities are right-aligned. You specify the alignment by adding a comma (",") after an interpolation expression and designating the minimum field width. If the specified value is a positive number, the field is right-aligned. If it is a negative number, the field is left-aligned.
Try removing the negative signs from the {"Item",-25} and {item.Key,-25} code and run the example again. This time, the item names are right-aligned.
You can combine an alignment specifier and a format string for a single interpolation expression. To do that, specify the alignment first, followed by a colon and the format string. Try the following code that displays three formatted strings with defined field widths:
Console.WriteLine($"[{DateTime.Now,-20:d}] Hour [{DateTime.Now,-10:HH}] [{1063.342,15:N2}] feet");
Congratulations!
You've completed the string interpolation interactive tutorial. You can visit the .NET site to download the .NET Core SDK, create a project on your machine, and keep coding.
For more information, see String interpolation.
Have an issue with this section? If so, please give us some feedback so we can improve this section.
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for