Interpolação de strings e String.Format em C#: especificadores de formato, alinhamento, cultura

A interpolação de strings monta uma string a partir de texto literal e expressões. Prefixe o literal com $, coloque qualquer expressão C# entre chaves, e o valor dela é convertido em texto e inserido:

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")}");
    }
}

Saída:

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

A interpolação chegou no C# 6. O compilador a transforma em uma chamada a string.Format ou string.Concat (ou, desde o C# 10, em código de handler mais eficiente), então ela não é mais lenta que montar a string à mão.

A expressão condicional da última linha precisa de parênteses. Dentro de um trecho de interpolação, dois pontos iniciam um especificador de formato, então {x > 10 ? "yes" : "no"} sem parênteses é um erro de compilação.

Especificadores de formato

Depois da expressão, dois pontos e uma string de formato controlam como o valor é escrito. As mesmas strings de formato funcionam com ToString("...") e 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
    }
}

Saída:

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

Os códigos padrão, cada um opcionalmente seguido de um número de precisão:

Padrões personalizados montam um formato a partir de marcadores: 0 é um dígito sempre mostrado, # é um dígito mostrado só se for significativo, . é o ponto decimal, , dentro do número ativa os separadores de grupo, e % multiplica por 100. "0.##" mostra até duas casas decimais e descarta os zeros à direita; "#,##0.00" é o formato contábil clássico.

Toda formatação numérica arredonda o valor exibido; a variável em si não muda. Quando um valor fica exatamente na metade (2.25 mostrado com uma casa decimal), runtimes e tipos diferentes podem arredondar o empate de formas diferentes, então, se a regra importa, arredonde explicitamente antes com Math.Round(value, 1, MidpointRounding.AwayFromZero) e depois formate.

Datas na interpolação

Valores DateTime recebem strings de formato de data do mesmo jeito:

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");
    }
}

Saída:

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

Um formato personalizado de TimeSpan exige que os caracteres literais sejam escapados com uma barra invertida, o que em um literal de string comum se escreve \\:. A lista completa dos códigos de data (yyyy, MM, HH, tt...) e os erros que as pessoas cometem com eles (mm é minutos, MM é meses) estão em formato de DateTime.

Alinhamento e preenchimento

Uma vírgula depois da expressão define uma largura mínima de campo. Um número positivo alinha à direita, um negativo alinha à esquerda. Combinado com um formato, ele alinha tabelas em texto puro:

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}");
        }
    }
}

Saída:

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

A sintaxe é {expression,alignment:format}: primeiro o alinhamento, depois o formato. Um valor maior que a largura não é truncado; ele empurra o resto da linha. PadLeft e PadRight fazem o mesmo preenchimento fora da interpolação.

Escapando chaves

Para imprimir uma chave literal, duplique-a: {{ e }}. Isso aparece quando a saída é JSON, CSS ou código:

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
    }
}

Saída:

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

Montar JSON à mão assim serve para uma linha de log rápida; para JSON de verdade, use um serializador, que trata corretamente aspas e caracteres especiais dentro de name.

string.Format e formatação composta

Antes do C# 6, a formatação era feita com string.Format, que recebe marcadores numerados e uma lista de argumentos. A mesma sintaxe de formatação composta é aceita por Console.WriteLine, StringBuilder.AppendFormat e 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));
    }
}

Saída:

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

Prefira a interpolação no código: os valores ficam onde aparecem, então um marcador não tem como apontar para o argumento errado. string.Format continua sendo a ferramenta certa quando o modelo é um dado, como uma mensagem traduzida carregada de um arquivo de recursos. Um índice de marcador sem argumento correspondente ({2} com dois argumentos) lança uma FormatException em tempo de execução.

Cultura: controlando separadores e moeda

A interpolação, o ToString e o string.Format usam por padrão a cultura atual da thread. Em uma máquina configurada em alemão, {1234.5:N2} produz 1.234,50; nos EUA produz 1,234.50. O formato de moeda C usa o símbolo da cultura. Para escolher a cultura explicitamente, capture a string interpolada como FormattableString e formate-a com um provedor:

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);
    }
}

Saída:

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

Use a cultura do usuário para textos que pessoas leem, e CultureInfo.InvariantCulture para tudo o que outro programa lê. Um CSV gravado com a cultura atual em uma máquina alemã tem vírgulas dentro dos números e fica ilegível em outros lugares. No .NET 6 em diante, string.Create(CultureInfo.InvariantCulture, $"...") faz o mesmo que FormattableString.Invariant, sem o objeto intermediário.

Strings interpoladas verbatim e raw

$ se combina com @ em uma string interpolada verbatim: as barras invertidas são literais e a string pode ocupar várias linhas. O C# 8 em diante aceita as duas ordens ($@ ou @$); o C# 6 e o 7 exigem $@:

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}");
    }
}

Saída:

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

O C# 11 adicionou as raw interpolated strings. Com um $, as chaves marcam expressões como de costume. Com $$, uma chave simples é literal e as expressões precisam de duas chaves, o que deixa legíveis os modelos de JSON e de código:

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

O C# 11 também permite quebras de linha dentro de um trecho de interpolação, então uma expressão longa ou uma expressão switch pode ser dividida em várias linhas.

Erros comuns

• Esquecer o $. "Total: {total}" imprime as chaves literalmente. O compilador não avisa.
• Um ternário sem parênteses dentro das chaves: os dois pontos são lidos como separador de formato.
• Formatar saídas lidas por máquinas com a cultura atual. Vírgulas decimais quebram CSV, JSON e SQL. Use a cultura invariante.
• Usar ToString() sem formato para dinheiro. 2.5m é impresso como 2.5, não 2.50. Use F2, N2 ou C.
• Montar strings grandes com interpolação em um laço. Cada iteração cria uma string nova; use StringBuilder ou string.Join.