Edit

Interpolated Strings (Visual Basic Reference)

  • Article

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. This feature is available in Visual Basic 14 and later versions.

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".

Important

You cannot have any white space between the $ and the " that starts the string. Doing so causes a compiler error.

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:

Public Module Example
   Public Sub Main()
      Dim name = "Horace"
      Dim age = 34
      Dim s1 = $"He asked, ""Is your name {name}?"", but didn't wait for a reply."
      Console.WriteLine(s1)
      
      Dim s2 = $"{name} is {age:D3} year{If(age = 1, "", "s")} old."
      Console.WriteLine(s2) 
   End Sub
End Module
' 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:

    Public Module Example
   Public Sub Main()
      Dim name = "Bartholomew"
      Dim s1 = $"Hello, {name}!"  
      Console.WriteLine(s1)
   End Sub
End Module
' The example displays the following output:
'      Hello, Bartholomew!
' </Snippet1>

    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 Console.WriteLine(String) method.

    Imports System.Globalization
Imports System.Reflection

Public Module Example
   Public Sub Main()
      Dim price = 1000
      Dim s2 As IFormattable = $"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)      
   End Sub

   Private Sub ShowInfo(obj As Object)
      Console.WriteLine($"Displaying member information:{vbCrLf}")
      Dim t = obj.GetType()
      Dim flags = BindingFlags.Public Or BindingFlags.Instance Or BindingFlags.Static Or BindingFlags.NonPublic
      For Each m In t.GetMembers(flags) 
         Console.Write($"   {m.Name} {m.MemberType}")   
         If m.MemberType = MemberTypes.Property Then
            Dim p = t.GetProperty(m.Name, flags)
            Console.Write($"   Value: {p.GetValue(obj)}")         
         End If
         If m.MemberType = MemberTypes.Field Then
            Dim f = t.GetField(m.Name, flags)
            Console.Write($"   Value: {f.GetValue(obj)}")
         End If
         Console.WriteLine()
      Next
      Console.WriteLine($"-------{vbCrLf}")
   End Sub
End Module
' 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 €.
' </Snippet1>

    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 a 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. A FormattableString also includes:

    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.

    Imports System.Globalization

Public Module Example
   Public Sub Main()
      Dim name = "Bartholomew"
      Dim s3 As FormattableString = $"Hello, {name}!"  
      Console.WriteLine($"String: '{s3.Format}'")
      Console.WriteLine($"Arguments: {s3.ArgumentCount}")
      Console.WriteLine($"Result string: {s3}")
   End Sub
End Module
' The example displays the following output:
'       String: 'Hello, {0}!'
'       Arguments: 1
'       Result string: Hello, Bartholomew!

See also