C# Reference ยท Strings and Text
C# String.Format() and string interpolation
Reference for C# string.Format() and interpolated strings: placeholders, alignment, format strings, escaping braces, culture, and FormatException.
string.Format builds text from a template with numbered placeholders such as and , followed by the values to insert. An interpolated string ($"...") is the modern shorthand: you write the expression inside the braces, and the compiler does the rest.
Each placeholder has the form {index[,alignment][:formatString]}. The alignment sets a minimum width (negative means left-aligned) and the format string controls how the value is converted, for example F2 for two decimals. The same syntax is used by Console.WriteLine, StringBuilder.AppendFormat and TextWriter.WriteLine overloads that take a format string.
string a = string.Format("{0} has {1} items", "Cart", 3); string b = $"{"Cart"} has {3} items";
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Syntax
public static string Format(string format, object? arg0) public static string Format(string format, object? arg0, object? arg1) public static string Format(string format, params object?[] args) public static string Format(string format, params ReadOnlySpan<object?> args) public static string Format(IFormatProvider? provider, string format, params object?[] args) public static string Format(IFormatProvider? provider, CompositeFormat format, params object?[] args)
Placeholder grammar: {index[,alignment][:formatString]}. Write {{ and }} for literal braces.
| Name | Description |
|---|---|
format |
The template with placeholders. |
args |
The values; refers to the first. |
provider |
Supplies culture rules (decimal separator, currency symbol, date patterns). null means the current culture. |
alignment |
Minimum field width; positive pads on the left, negative on the right. |
formatString |
Passed to the value's ToString(string, IFormatProvider). See Format specifiers. |
Returns: the formatted string.
Errors / undefined behavior: ArgumentNullException if format is null. FormatException if the template is malformed or refers to an index with no argument.
Usage notes
- Prefer interpolation for readability: the value sits where it appears, and the compiler checks the expressions. Use
string.Formatwhen the template comes from a resource file or a database, where the text and the arguments are separate. - Culture. Without a provider the current culture decides the decimal separator and currency symbol. Passing
CultureInfo.InvariantCulturegives stable output for logs and files. For interpolated strings usestring.Create(CultureInfo.InvariantCulture, $"...")orFormattableString.Invariant($"..."). Our runner uses invariant globalization, so all cultures behave like invariant here. - Indexes are zero-based and can repeat or appear in any order. Unused arguments are silently ignored; missing ones throw.
- Boxing. Each value-type argument is boxed into
object, which costs an allocation.CompositeFormat(parse once, format many times) and interpolated string handlers avoid much of that. - Alignment is padding, not truncation. A value longer than the width is written in full.
- Logging frameworks use message templates like
that look similar but are not the same syntax. Do not pass them tostring.Format. - User-supplied templates are risky. A format string from outside can throw
FormatExceptionor reveal data from objects you pass. Never format with an untrusted template and rich objects.