Interpolated Strings (C# Reference)

Used to construct strings. An interpolated string looks like a template string that contains interpolated expressions. An interpolated string returns a string that replaces the interpolated expressions that it contains with their string representations.

The arguments of an interpolated string are easier to understand than a composite format string. For example, the interpolated string

Console.WriteLine($"Name = {name}, hours = {hours:hh}"); 

contains two interpolated expressions, '{name}' and '{hours:hh}'. The equivalent composite format string is:

Console.WriteLine("Name = {0}, hours = {1:hh}", name, hours);  

The structure of an interpolated string is:

$"<text> {<interpolated-expression> [,<field-width>] [:<format-string>] } <text> ..."  

where:

  • field-width is a signed integer that indicates the number of characters in the field. If it is positive, the field is right-aligned; if negative, left-aligned.

  • format-string is a format string appropriate for the type of object being formatted. For example, for a DateTime value, it could be a standard date and time format string such as "D" or "d".

You can use an interpolated string anywhere you can use a string literal. The interpolated string is evaluated each time the code with the interpolated string executes. This allows you to separate the definition and evaluation of an interpolated string.

To include a curly brace ("{" or "}") in an interpolated string, use two curly braces, "{{" or "}}". See the Implicit Conversions section for more details.

If the interpolated string contains other characters with special meaning in an interpolated string, such as the quotation mark ("), colon (:), or comma (,), they should be escaped if they occur in literal text, or they should be included in an expression delimited by parentheses if they are language elements included in an interpolated expression. The following example escapes quotation marks to include them in the result string, and it uses parentheses to delimit the expression (age == 1 ? "" : "s") so that the colon is not interpreted as beginning a format string.

using System;

public class Example
{
   public static void Main()
   {
      var name = "Horace";
      var age = 34;
      var s1 = $"He asked, \"Is your name {name}?\", but didn't wait for a reply.";
      Console.WriteLine(s1);
      
      var s2 = $"{name} is {age:D3} year{(age == 1 ? "" : "s")} old.";
      Console.WriteLine(s2); 
   }
}
// The example displays the following output:
//       He asked, "Is your name Horace?", but didn't wait for a reply.
//       Horace is 034 years old.

Implicit Conversions

There are three implicit type conversions from an interpolated string:

  1. Conversion of an interpolated string to a String. The following example returns a string whose interpolated string expressions have been replaced with their string representations. For example:

    using System;
    
    public class Example
    {
       public static void Main()
       {
          var name = "Bartholomew";
          var s1 = $"Hello, {name}!";  
          Console.WriteLine(s1);
       }
    }
    // The example displays the following output:
    //      Hello, Bartholomew!
    

    This is the final result of a string interpretation. All occurrences of double curly braces ("{{" and "}}") are converted to a single curly brace.

  2. Conversion of an interpolated string to an IFormattable variable that allows you create multiple result strings with culture-specific content from a single IFormattable instance. This is useful for including such things as the correct numeric and date formats for individual cultures. All occurrences of double curly braces ("{{" and "}}") remain as double curly braces until you format the string by explicitly or implicitly calling the ToString() method. All contained interpolation expressions are converted to {0}, {1}, and so on.

    The following example uses reflection to display the members as well as the field and property values of an IFormattable variable that is created from an interpolated string. It also passes the IFormattable variable to the @System.Console(System.String) method.

    using System;
    using System.Globalization;
    using System.Reflection;
    
    public class Example
    {
       public static void Main()
       {
          var price = 1000;
          IFormattable s2 = $"The cost of this item is {price:C}.";  
          ShowInfo(s2);
          CultureInfo.CurrentCulture = new CultureInfo("en-US");
          Console.WriteLine(s2);
          CultureInfo.CurrentCulture = new CultureInfo("fr-FR");
          Console.WriteLine(s2);      
       }
    
       private static void ShowInfo(object obj)
       {
          Console.WriteLine("Displaying member information:\n");
          var t = obj.GetType();
          var flags = BindingFlags.Public | BindingFlags.Instance | BindingFlags.Static | BindingFlags.NonPublic;
          foreach (var m in t.GetMembers(flags)) {
             Console.WriteLine($"{m.Name}: {m.MemberType}");   
             if (m.MemberType == MemberTypes.Property) {
                var p = t.GetProperty(m.Name, flags);
                Console.WriteLine($"   Value: {p.GetValue(obj)}");         
             }
             if (m.MemberType == MemberTypes.Field) {
                var f = t.GetField(m.Name, flags);
                Console.WriteLine($"   Value: {f.GetValue(obj)}");
             }
          }
          Console.WriteLine("-------\n");
       }
    }
    // The example displays the following output:
    //       Displaying member information:
    //       
    //       get_Format: Method
    //       GetArguments: Method
    //       get_ArgumentCount: Method
    //       GetArgument: Method
    //       ToString: Method
    //       System.IFormattable.ToString: Method
    //       ToString: Method
    //       Equals: Method
    //       GetHashCode: Method
    //       GetType: Method
    //       Finalize: Method
    //       MemberwiseClone: Method
    //       .ctor: Constructor
    //       Format: Property
    //          Value: The cost of this item is {0:C}.
    //       ArgumentCount: Property
    //          Value: 1
    //       _format: Field
    //          Value: The cost of this item is {0:C}.
    //       _arguments: Field
    //          Value: System.Object[]
    //       -------
    //       
    //       The cost of this item is $1,000.00.
    //       The cost of this item is 1 000,00 €.
    

    Note that the interpolated string can be inspected only by using reflection. If it is passed to a string formatting method, such as WriteLine(String), its format items are resolved and the result string returned.

  3. Conversion of an interpolated string to an FormattableString variable that represents a composite format string. Inspecting the composite format string and how it renders as a result string might, for example, help you protect against an injection attack if you were building a query. FormattableString also includes ToString() overloads that let you produce result strings for the @System.Globalization.InvariantCulture and @System.Globalization.CurrentCulture. All occurrences of double curly braces ("{{" and "}}") remain as double curly braces, until you format. All contained interpolation expressions are converted to {0}, {1}, and so on.

    using System;
    using System.Globalization;
    
    public class Example
    {
       public static void Main()
       {
          var name = "Bartholomew";
          FormattableString s3 = $"Hello, {name}!";  
          Console.WriteLine($"String: {s3.Format}");
          Console.WriteLine($"Arguments: {s3.ArgumentCount}");
          Console.WriteLine($"Result string: {s3}");
       }
    }
    // The example displays the following output:
    //       String: Hello, {0}!
    //       Arguments: 1
    //       Result string: Hello, Bartholomew!
    

Language Specification

For more information, see the C# Language Specification. The language specification is the definitive source for C# syntax and usage.

See Also

IFormattable
FormattableString
C# Reference
C# Programming Guide