$ を使う文字列補間

$ 文字は、文字列リテラルを補間された文字列として識別します。 挿入文字列は、補間式が含まれている可能性がある文字列リテラルです。 補間された文字列が結果の文字列に解決されると、コンパイラは補間式を含む項目を、式の結果の文字列表現で置き換えます。

文字列補間により、より読みやすく便利な構文で文字列を書式設定できます。 文字列の複合書式設定よりも読みやすくなります。 次の例では、両方の機能を使用して、同じ出力を生成します。

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.

C# 10 以降では、補間された文字列を使用して定数文字列を初期化できます。 これは、補間された文字列内のすべての補間式が定数文字列でもある場合にのみ実行できます。

挿入文字列の構造

文字列リテラルを挿入文字列として識別するため、先頭に $ の記号を追加してください。 $ と文字列リテラルを開始する " の間に空白を入れることはできません。

補間式を含む項目の構造は、次のとおりです。

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

角かっこ内の要素は省略可能です。 次の表は、それぞれの要素の説明です。

要素	説明
interpolationExpression	書式設定される結果を生成する式です。 null のような式の場合、出力結果は空文字列 (String.Empty) になります。
alignment	式の結果の文字列表現で、最小文字数を定義する値を持つ定数式です。 正の場合は、文字列表現は右揃えで配置され、負の場合は、左揃えで配置されます。 詳細については、「複合書式設定」の記事の「アラインメント コンポーネント」のセクションを参照してください。
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}

前の例では、補間された生文字列リテラルは 2 つの $ 文字で始まっています。 二重中かっこ ({{ と }}) の間にすべての補間式を配置する必要があります。 結果文字列には 1 つの中かっこが埋め込まれます。 繰り返し { または } の文字を結果文字列に埋め込む必要がある場合は、$ より多い数の文字を適切に使用して、補間された生文字列リテラルを指定します。 文字列リテラルの中で、中かっこが $ 文字の数よりも多く繰り返される場合、{ と } 文字は内側から外側にグループ化されます。 前の例では、リテラル The point {{{X}}, {{Y}}} は {{X}} と {{Y}} を補間式として解釈します。 外側の { と } は、出力文字列にそのまま含まれます。

特殊文字

挿入文字列で生成された文字列にかっこ "{" または "}" を含めるには、2 つのかっこ "{{" または "}}" を使用します。 詳細については、「複合書式設定」の記事の「エスケープ中かっこ ({})」のセクションを参照してください。

コロン (":") は補間式の項目で特別な意味を持つため、補間式で条件演算子を使用するには、 その式を丸かっこで囲みます。

次の例は、結果の文字列にかっこを含める方法を示しています。 また、条件演算子の使用方法も示しています。

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.

補間された verbatim 文字列は、$ と @ の両方の文字で始まります。 $ と @ は任意の順序で使用できます。$@"..." と @$"..." はどちらも有効な verbatim 補間文字列です。 逐語的文字列の詳細については、string と逐語的識別子に関する記事を参照してください。

カルチャ固有の形式

既定では、挿入文字列は、すべての書式設定操作に対して 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# の文字列補完に関する対話形式チュートリアルを参照してください。 また、別の「C# における文字列補間」チュートリアルを参照することもできます。 このチュートリアルでは、補間された文字列を使用して書式設定された文字列を生成する方法が示されています。

補完文字列のコンパイル

C# 10 と .NET 6 以降では、補間された文字列が補間された文字列ハンドラー パターンを満たす型に代入されているかどうかがコンパイラによって確認されます。 補間された文字列ハンドラーは、補間された文字列を結果文字列に変換する型です。 補間された文字列の型が string である場合は、System.Runtime.CompilerServices.DefaultInterpolatedStringHandler によって処理されます。 カスタム文字列補間ハンドラーの例については、「カスタム文字列補間ハンドラーを記述する」のチュートリアルを参照してください。 補間された文字列ハンドラーの使用は高度なシナリオであり、通常はパフォーマンス上の理由で使用されます。

Note

補間された文字列ハンドラーの副作用の 1 つは、System.Runtime.CompilerServices.DefaultInterpolatedStringHandler を含むカスタム ハンドラーでは、すべての条件下で、補間された文字列内のすべての補間式が評価されない可能性があることです。 つまり、それらの式の副作用が発生しない可能性があります。

C# 10 より前では、補間された文字列が string 型の場合、通常は String.Format メソッド呼び出しに変換されます。 分析後の動作が連結と等しくなるようであれば、コンパイラでは、String.Format を String.Concat に置換する場合があります。

補間文字列の型が IFormattable または FormattableString の場合、コンパイラは FormattableStringFactory.Create メソッドの呼び出しを生成します。

C# 言語仕様

詳細については、C# 言語仕様に関する記事の補間された文字列式に関するセクションと、次の新機能の仕様を参照してください。

• C# 10 - 補間された文字列の改善
• C# 11 - 未加工の文字列リテラル
• C# 11 - 文字列補間の改行

関連項目

• C# 特殊文字
• 文字列
• 標準の数値書式指定文字列
• 複合書式指定
• String.Format
• 補間を簡略化する (スタイル規則 IDE0071)
• C# 10 および .NET 6 での文字列補間 (.NET ブログ)