Interpolacja stringów i String.Format w C#: formaty, wyrównanie, kultura

Interpolacja stringów buduje string z dosłownego tekstu i wyrażeń. Poprzedź literał znakiem $, umieść dowolne wyrażenie C# w nawiasach klamrowych, a jego wartość zostanie zamieniona na tekst i wstawiona:

using System;

class Program
{
    static void Main()
    {
        string customer = "Maya";
        int items = 3;
        decimal price = 4.5m;

        Console.WriteLine($"Hello, {customer}!");
        Console.WriteLine($"{items} items at {price} = {items * price}");
        Console.WriteLine($"Name has {customer.Length} letters, upper: {customer.ToUpper()}");
        Console.WriteLine($"Free shipping: {(items * price > 10 ? "yes" : "no")}");
    }
}

Wynik:

Hello, Maya!
3 items at 4.5 = 13.5
Name has 4 letters, upper: MAYA
Free shipping: yes

Interpolacja pojawiła się w C# 6. Kompilator zamienia ją na wywołanie string.Format albo string.Concat (a od C# 10 na wydajniejszy kod z handlerem), więc nie jest wolniejsza niż ręczne budowanie stringu.

Wyrażenie warunkowe w ostatniej linii wymaga nawiasów. Wewnątrz miejsca interpolacji dwukropek rozpoczyna specyfikator formatu, więc {x > 10 ? "yes" : "no"} bez nawiasów to błąd kompilacji.

Specyfikatory formatu

Po wyrażeniu dwukropek i string formatu określają, jak wartość zostanie zapisana. Te same stringi formatu działają z ToString("...") i string.Format.

using System;

class Program
{
    static void Main()
    {
        decimal total = 1234567.891m;
        int orderId = 42;
        double ratio = 0.8127;

        Console.WriteLine($"{total:F2}");     // fixed-point, 2 decimals
        Console.WriteLine($"{total:N2}");     // with thousands separators
        Console.WriteLine($"{total:N0}");     // no decimals, rounded
        Console.WriteLine($"{orderId:D5}");   // integer padded to 5 digits
        Console.WriteLine($"{255:X}");        // hexadecimal
        Console.WriteLine($"{255:x4}");       // lowercase hex, 4 digits
        Console.WriteLine($"{total:E2}");     // scientific
        Console.WriteLine($"{ratio:F3}");
        Console.WriteLine($"{ratio:0.0%}");   // custom: percent with 1 decimal
        Console.WriteLine($"{total:#,##0.00}"); // custom pattern
        Console.WriteLine($"{7.5:000.0}");    // leading zeros
        Console.WriteLine($"{3.10m:0.##}");   // drop trailing zeros
    }
}

Wynik:

1234567.89
1,234,567.89
1,234,568
00042
FF
00ff
1.23E+006
0.813
81.3%
1,234,567.89
007.5
3.1

Standardowe kody, każdy opcjonalnie z liczbą określającą precyzję:

Wzorce niestandardowe budują format z symboli zastępczych: 0 to cyfra zawsze wyświetlana, # to cyfra wyświetlana tylko wtedy, gdy jest znacząca, . to separator dziesiętny, , wewnątrz liczby włącza separatory grup, a % mnoży przez 100. "0.##" pokazuje do dwóch miejsc po przecinku i pomija końcowe zera; "#,##0.00" to klasyczny format księgowy.

Każde formatowanie liczb zaokrągla wyświetlaną wartość; sama zmienna się nie zmienia. Gdy wartość leży dokładnie w połowie (2.25 pokazane z jednym miejscem po przecinku), różne środowiska uruchomieniowe i typy mogą różnie rozstrzygać remis, więc jeśli reguła ma znaczenie, najpierw zaokrąglij jawnie przez Math.Round(value, 1, MidpointRounding.AwayFromZero), a potem formatuj.

Daty w interpolacji

Wartości DateTime przyjmują stringi formatu dat w ten sam sposób:

using System;

class Program
{
    static void Main()
    {
        var shipped = new DateTime(2026, 9, 24, 16, 5, 0);

        Console.WriteLine($"{shipped:yyyy-MM-dd}");
        Console.WriteLine($"{shipped:dd/MM/yyyy HH:mm}");
        Console.WriteLine($"{shipped:ddd, MMM d}");
        Console.WriteLine($"Shipped at {shipped:HH:mm} on {shipped:dddd}");

        TimeSpan eta = TimeSpan.FromMinutes(130);
        Console.WriteLine($"ETA {eta:hh\\:mm}");
        Console.WriteLine($"{eta.TotalHours:F1} hours");
    }
}

Wynik:

2026-09-24
24/09/2026 16:05
Thu, Sep 24
Shipped at 16:05 on Thursday
ETA 02:10
2.2 hours

Niestandardowy format TimeSpan wymaga poprzedzenia znaków dosłownych ukośnikiem wstecznym, co w zwykłym literale stringu zapisuje się jako \\:. Pełną listę kodów dat (yyyy, MM, HH, tt...) i błędów, jakie się z nimi popełnia (mm to minuty, MM to miesiące), znajdziesz na stronie formatowanie DateTime.

Wyrównanie i dopełnianie

Przecinek po wyrażeniu ustawia minimalną szerokość pola. Liczba dodatnia wyrównuje do prawej, ujemna do lewej. W połączeniu z formatem pozwala wyrównać tabele w zwykłym tekście:

using System;

class Program
{
    static void Main()
    {
        var names = new[] { "Espresso", "Latte", "Hot chocolate" };
        var prices = new[] { 2.4m, 3.6m, 4.25m };
        var sold = new[] { 118, 64, 9 };

        Console.WriteLine($"{"Item",-14}|{"Price",7}|{"Sold",5}");
        Console.WriteLine(new string('-', 28));
        for (int i = 0; i < names.Length; i++)
        {
            Console.WriteLine($"{names[i],-14}|{prices[i],7:F2}|{sold[i],5}");
        }
    }
}

Wynik:

Item          |  Price| Sold
----------------------------
Espresso      |   2.40|  118
Latte         |   3.60|   64
Hot chocolate |   4.25|    9

Składnia to {expression,alignment:format}: najpierw wyrównanie, potem format. Wartość dłuższa niż szerokość pola nie jest obcinana; przesuwa resztę linii. PadLeft i PadRight robią to samo dopełnianie poza interpolacją.

Escapowanie nawiasów klamrowych

Żeby wypisać dosłowny nawias klamrowy, podwój go: {{ i }}. Przydaje się to, gdy wynikiem jest JSON, CSS albo kod:

using System;

class Program
{
    static void Main()
    {
        int id = 42;
        string name = "Ana";

        Console.WriteLine($"{{ \"id\": {id}, \"name\": \"{name}\" }}");
        Console.WriteLine($"Set literal: {{1, 2, 3}}");
        Console.WriteLine($"{{{id}}}");   // a value wrapped in braces
    }
}

Wynik:

{ "id": 42, "name": "Ana" }
Set literal: {1, 2, 3}
{42}

Ręczne budowanie JSON w ten sposób jest w porządku przy szybkiej linii logu; do prawdziwego JSON używaj serializatora, który poprawnie obsługuje cudzysłowy i znaki specjalne wewnątrz name.

string.Format i formatowanie złożone

Przed C# 6 formatowało się za pomocą string.Format, który przyjmuje numerowane symbole zastępcze i listę argumentów. Tę samą składnię formatowania złożonego akceptują Console.WriteLine, StringBuilder.AppendFormat i TextWriter.Write:

using System;

class Program
{
    static void Main()
    {
        string item = "Notebook";
        decimal price = 3.5m;
        int qty = 4;

        string line = string.Format("{0} x{1}: {2:F2}", item, qty, price * qty);
        Console.WriteLine(line);

        Console.WriteLine("{0,-10}|{1,6:F2}", item, price);   // alignment and format
        Console.WriteLine("{0} {0} {1}", "echo", "!");        // an index can repeat

        string template = "Dear {0}, your order #{1:D6} has shipped.";
        Console.WriteLine(string.Format(template, "Leo", 731));
    }
}

Wynik:

Notebook x4: 14.00
Notebook  |  3.50
echo echo !
Dear Leo, your order #000731 has shipped.

W kodzie wybieraj interpolację: wartości stoją tam, gdzie się pojawiają, więc symbol zastępczy nie może wskazać złego argumentu. string.Format pozostaje właściwym narzędziem, gdy szablon jest danymi, na przykład przetłumaczonym komunikatem wczytanym z pliku zasobów. Indeks symbolu zastępczego bez pasującego argumentu ({2} przy dwóch argumentach) rzuca FormatException w czasie działania.

Kultura: kontrola separatorów i waluty

Interpolacja, ToString i string.Format domyślnie używają bieżącej kultury wątku. Na komputerze ustawionym na niemiecki {1234.5:N2} daje 1.234,50; w USA daje 1,234.50. Format waluty C używa symbolu danej kultury. Żeby wybrać kulturę jawnie, przechwyć interpolowany string jako FormattableString i sformatuj go z dostawcą formatu:

using System;
using System.Globalization;

class Program
{
    static void Main()
    {
        decimal amount = 1234.5m;
        var us = new CultureInfo("en-US");
        var de = new CultureInfo("de-DE");

        FormattableString line = $"Total: {amount:N2}";
        Console.WriteLine(line.ToString(us));
        Console.WriteLine(line.ToString(de));

        Console.WriteLine(amount.ToString("C", us));
        Console.WriteLine(string.Format(de, "{0:N2}", amount));

        // For files, logs and URLs: always the invariant culture
        string csv = FormattableString.Invariant($"{amount},{0.75}");
        Console.WriteLine(csv);
    }
}

Wynik:

Total: 1,234.50
Total: 1.234,50
$1,234.50
1.234,50
1234.5,0.75

Dla tekstu czytanego przez ludzi używaj kultury użytkownika, a dla wszystkiego, co czyta inny program, CultureInfo.InvariantCulture. CSV zapisany z bieżącą kulturą na niemieckim komputerze ma przecinki wewnątrz liczb i gdzie indziej jest nieczytelny. W .NET 6 i nowszych string.Create(CultureInfo.InvariantCulture, $"...") robi to samo co FormattableString.Invariant, bez obiektu pośredniego.

Dosłowne i surowe stringi interpolowane

$ łączy się z @ w dosłowny string interpolowany: ukośniki wsteczne są dosłowne, a string może obejmować wiele linii. C# 8 i nowsze akceptują dowolną kolejność ($@ lub @$); C# 6 i 7 wymagają $@:

using System;

class Program
{
    static void Main()
    {
        string user = "ana";
        int year = 2026;
        Console.WriteLine($@"C:\Users\{user}\Reports\{year}\summary.txt");
        Console.WriteLine($@"Report for {user}
Year: {year}");
    }
}

Wynik:

C:\Users\ana\Reports\2026\summary.txt
Report for ana
Year: 2026

C# 11 dodał surowe stringi interpolowane. Z jednym $ nawiasy klamrowe jak zwykle oznaczają wyrażenia. Z $$ pojedynczy nawias jest dosłowny, a wyrażenia wymagają dwóch nawiasów, co sprawia, że szablony JSON i kodu dają się czytać:

// C# 11 and later
int id = 42;
string name = "Ana";
string json = $$"""
    {
      "id": {{id}},
      "name": "{{name}}"
    }
    """;

C# 11 pozwala też na znaki nowej linii wewnątrz miejsca interpolacji, więc długie wyrażenie albo wyrażenie switch można rozbić na kilka linii.

Typowe błędy

• Zapomniany $. "Total: {total}" wypisuje nawiasy dosłownie. Kompilator nie ostrzega.
• Operator trójargumentowy bez nawiasów wewnątrz nawiasów klamrowych: dwukropek jest odczytywany jako separator formatu.
• Formatowanie wyjścia czytanego przez maszyny z bieżącą kulturą. Przecinki dziesiętne psują CSV, JSON i SQL. Używaj kultury niezmiennej.
• Używanie ToString() bez formatu dla kwot pieniędzy. 2.5m wypisuje się jako 2.5, a nie 2.50. Użyj F2, N2 albo C.
• Budowanie dużych stringów przez interpolację w pętli. Każda iteracja tworzy nowy string; użyj StringBuilder albo string.Join.