共用方式為

使用 $ 的字串插值

$ 字元會將字串常值識別為「差補字串」。 插值字串是可能包含插值運算式的字串常值。 當插入字串被轉換為結果字串時，編譯器會將包含內插運算式的項目替換為運算結果的字串表示。

字串插補提供更易於讀取且更便利的語法來格式化字串。 比字串複合格式更容易於讀取。 下列範例會使用這兩項功能，產生相同的輸出：

var name = "Mark";
var date = DateTime.Now;

// Composite formatting:
Console.WriteLine("Hello, {0}! Today is {1}, it's {2:HH:mm} now.", name, date.DayOfWeek, date);
// String interpolation:
Console.WriteLine($"Hello, {name}! Today is {date.DayOfWeek}, it's {date:HH:mm} now.");
// Both calls produce the same output that is similar to:
// Hello, Mark! Today is Wednesday, it's 19:40 now.

您可以使用內插字串來初始化 常數 字串。 只有當差補字串內的所有內插補點運算式都是常數字串時，您才能這麼做。

插入字串的結構

若要將字串常值標示為插值字串，請在其前面加上 $ 符號。 字串文字開頭的 $ 跟 " 之間不能有任何空白字元。

具有內插補點運算式的項目結構如下所示：

{<interpolationExpression>[,<width>][:<formatString>]}

在方括號中的元素是選擇性的元素。 下表說明每個元素：

元素 描述
interpolationExpression 產生要格式化之結果的運算式。 當運算式為 null 時，輸出是空白字串 (String.Empty)。
width 常數的運算式，其值定義運算式結果的字串表示法的字元數最小值。 如果是正數，則字串表示是靠右對齊；如果是負數，其為靠左對齊。 如需詳細資訊，請參閱複合格式設定一文的 Width 元件一節。
formatString 運算式結果的類型所支援的格式字串。 如需詳細資訊，請參閱複合格式主題的格式字串元件一節。

下列範例會使用上表中所述的選擇性格式化元件：

Console.WriteLine($"|{"Left",-7}|{"Right",7}|");

const int FieldWidthRightAligned = 20;
Console.WriteLine($"{Math.PI,FieldWidthRightAligned} - default formatting of the pi number");
Console.WriteLine($"{Math.PI,FieldWidthRightAligned:F3} - display only three decimal digits of the pi number");
// Output is:
// |Left   |  Right|
//     3.14159265358979 - default formatting of the pi number
//                3.142 - display only three decimal digits of the pi number

從 C# 11 開始，您可以在字串插值運算式內使用換行，使運算式的程式碼更具可讀性。 下列範例顯示換行符號如何改善涉及模式比對的運算式可讀性：

string message = $"The usage policy for {safetyScore} is {
    safetyScore switch
    {
        > 90 => "Unlimited usage",
        > 80 => "General usage, with daily safety check",
        > 70 => "Issues must be addressed within 1 week",
        > 50 => "Issues must be addressed within 1 day",
        _ => "Issues must be addressed before continued use",
    }
    }";

插入的原始字串常值

從 C# 11 開始，您可以使用插入的原始字串常值，如下列範例所示：

int X = 2;
int Y = 3;

var pointMessage = $"""The point "{X}, {Y}" is {Math.Sqrt(X * X + Y * Y):F3} from the origin""";

Console.WriteLine(pointMessage);
// Output is:
// The point "2, 3" is 3.606 from the origin

若要在結果字串中內嵌 { 和 } 字元，請使用多個 $ 字元啟動插入的原始字串常值。 執行此操作時，任何短於 { 字元數的 } 或 $ 字元序列都會內嵌到結果字串中。 若要在該字串中括住任何內插補點運算式，您必須使用與 $ 字元數相同的大括號數目，如下列範例所示：

int X = 2;
int Y = 3;

var pointMessage = $$"""{The point {{{X}}, {{Y}}} is {{Math.Sqrt(X * X + Y * Y):F3}} from the origin}""";
Console.WriteLine(pointMessage);
// Output is:
// {The point {2, 3} is 3.606 from the origin}

在上述範例中，插入的原始字串常值會以兩個 $ 字元開頭。 您必須將每個插補運算式放置在雙大括號 ({{ 和 }}) 之間。 單一大括號會內嵌到結果字串中。 如果您需要將重複的 { 或 } 字元內嵌至結果字串，請使用適當數目的 $ 字元來指定插入的原始字符串字面量。 如果字串字面值中的重複大括號數量多於 $ 字元的數目，那麼 { 和 } 字元將會從內到外進行分組。 在上述範例中，常值 The point {{{X}}, {{Y}}} 會將 {{X}} 和 {{Y}} 解譯為插補運算式。 外部 { 和 } 會逐字包含在輸出字串中。

特殊字元

若要在插入字串所產生的文字中包含大括弧 "{" 或 "}"，請使用雙大括弧 "{{" 或 "}}"。 如需詳細資訊，請參閱複合格式文章中的逸出大括號一節。

因為冒號 (":")　在內插補點運算式項目中具有特殊意義，為了在內插補點運算式中使用條件運算子。 請用括號將運算式括起來。

下列範例顯示如何在結果字串中包含大括號。 它也會示範如何使用條件運算子：

string name = "Horace";
int age = 34;
Console.WriteLine($"He asked, \"Is your name {name}?\", but didn't wait for a reply :-{{");
Console.WriteLine($"{name} is {age} year{(age == 1 ? "" : "s")} old.");
// Output is:
// He asked, "Is your name Horace?", but didn't wait for a reply :-{
// Horace is 34 years old.

插入的逐字字串會以 $ 和 @ 字元開頭。 您可以依任何順序使用 $ 和 @：$@"..." 和 @$"..." 都是有效的差補逐字字串。 如需逐字字串的詳細資訊，請參閱字串和逐字識別碼一文。

文化特定的格式

預設情況下，內插字串會使用 CultureInfo.CurrentCulture 屬性為所有格式化作業所定義的當前文化特性。

若要將差補字串解析為特定文化特性的結果字串，請使用 String.Create(IFormatProvider, DefaultInterpolatedStringHandler) 方法，該方法從 .NET 6 開始提供。 下列範例顯示如何執行該項工作：

double speedOfLight = 299792.458;

System.Globalization.CultureInfo.CurrentCulture = System.Globalization.CultureInfo.GetCultureInfo("nl-NL");
string messageInCurrentCulture = $"The speed of light is {speedOfLight:N3} km/s.";

var specificCulture = System.Globalization.CultureInfo.GetCultureInfo("en-IN");
string messageInSpecificCulture = string.Create(
    specificCulture, $"The speed of light is {speedOfLight:N3} km/s.");

string messageInInvariantCulture = string.Create(
    System.Globalization.CultureInfo.InvariantCulture, $"The speed of light is {speedOfLight:N3} km/s.");

Console.WriteLine($"{System.Globalization.CultureInfo.CurrentCulture,-10} {messageInCurrentCulture}");
Console.WriteLine($"{specificCulture,-10} {messageInSpecificCulture}");
Console.WriteLine($"{"Invariant",-10} {messageInInvariantCulture}");
// Output is:
// nl-NL      The speed of light is 299.792,458 km/s.
// en-IN      The speed of light is 2,99,792.458 km/s.
// Invariant  The speed of light is 299,792.458 km/s.

在 .NET 5 和早期版本的 .NET 中，使用插值字串隱式轉換成 FormattableString 執行個體。 然後，您可以使用執行個體 FormattableString.ToString(IFormatProvider) 方法或靜態 FormattableString.Invariant 方法來產生特定文化特性的結果字串。 下列範例顯示如何執行該項工作：

double speedOfLight = 299792.458;
FormattableString message = $"The speed of light is {speedOfLight:N3} km/s.";

var specificCulture = System.Globalization.CultureInfo.GetCultureInfo("en-IN");
string messageInSpecificCulture = message.ToString(specificCulture);
Console.WriteLine(messageInSpecificCulture);
// Output:
// The speed of light is 2,99,792.458 km/s.

string messageInInvariantCulture = FormattableString.Invariant(message);
Console.WriteLine(messageInInvariantCulture);
// Output is:
// The speed of light is 299,792.458 km/s.

如需自訂格式的詳細資訊，請參閱 .NET 中的格式設定類型文章中的使用 ICustomFormatter 自訂格式一節。

其他資源

如果您是字串插補的新手，請參閱 C# 中的字串插補互動式教學課程。 該教學課程會示範如何使用差補字串產生格式化的字串。

內插字串的編譯

編譯器會檢查插值字串是否被指派給符合 插值字串處理器模式的類型，。 差補字串處理常式是一種型別，可將差補字串轉換成結果字串。 當差補字串具有 string 型別時，會由 System.Runtime.CompilerServices.DefaultInterpolatedStringHandler 處理。 如需自訂插補字串處理常式的範例，請參閱寫自訂字串插補處理常式的逐步教學。 使用差補字串處理常式是進階案例，通常出於效能原因而需要。

注意

插補字串處理程式的一個副作用是，自定義處理程式，包括 System.Runtime.CompilerServices.DefaultInterpolatedStringHandler，可能不會在所有條件下評估插補字串內的所有插補表達式。 這表示這些表達式的副作用可能不會發生。

如果插入字串的類型是 string時，通常會轉換成 String.Format 方法呼叫。 如果分析的行為相當於串連，則編譯器可將 String.Format 取代為 String.Concat。

如果內插字串的類型為 IFormattable 或 FormattableString，編譯器會產生 FormattableStringFactory.Create 方法的呼叫。

C# 語言規格

如需詳細資訊，請參閱 C# 語言規格的差補字串運算式一節，以及下列新功能規格：

另請參閱