Literais brutos de cadeia de caracteres

Gorjeta

Este artigo faz parte da seção Conceitos Básicos para desenvolvedores que já conhecem pelo menos uma linguagem de programação e estão aprendendo C#. Se você é novo em programação, comece com os tutoriais Comece agora. Para obter a gramática completa, consulte a referência de idioma.

Vindo de outro idioma? Os literais de cadeia de caracteres brutas do C# desempenham o mesmo papel que as cadeias de caracteres r"..." de Python e Rust, os blocos de texto do Java ("""...""") e as cadeias de caracteres de modelo delimitadas por acento grave em JavaScript, TypeScript e Go. A sintaxe C# é mais próxima dos blocos de texto de Java, com regras extras para delimitadores de comprimento variável e interpolação.

Um literal de string bruta é delimitado por três ou mais aspas duplas. Dentro dos delimitadores, cada caractere é interpretado literalmente. Aspas e cílios invertidos não precisam de escape, e as novas linhas são preservadas como escritas. Use cadeias de caracteres brutas para qualquer cadeia de caracteres que contenha aspas, barras invertidas ou várias linhas: JSON, XML, SQL, expressões regulares, caminhos de arquivo e exemplos de código.

Aviso

Um literal de string bruta facilita a leitura do SQL, mas não torna o SQL mais seguro. Nunca concatene ou interpole valores fornecidos pelo usuário em um comando SQL. Essa prática abre seu aplicativo para injeção de SQL. Em vez disso, use comandos parametrizados: DbCommand.CreateParameter com DbParameterCollection.Add ou auxiliares de nível superior no Entity Framework Core e Dapper. O mesmo cuidado se aplica a outros formatos propensos a injeção, como comandos de shell, filtros LDAP e HTML.

Um literal que contém aspas e barras invertidas

Um literal comum precisa de sequências de escape para " e \. Um literal verbatim ainda precisa de "" para inserir uma citação. Um literal raw não precisa de nenhum deles:

// Same JSON value, three ways:
string regular  = "{ \"name\": \"Ada\", \"path\": \"C:\\\\src\" }";
string verbatim = @"{ ""name"": ""Ada"", ""path"": ""C:\\src"" }";
string raw      = """{ "name": "Ada", "path": "C:\\src" }""";

Console.WriteLine(regular  == raw);   // True
Console.WriteLine(verbatim == raw);   // True

Cada formulário produz a mesma string, mas a versão bruta é lida exatamente como o JSON que representa.

Cadeias de caracteres brutas de linha única

Os delimitadores de abertura e de fechamento devem ter, cada um, no mínimo três aspas duplas, e o delimitador de fechamento deve usar o mesmo número de aspas que o delimitador de abertura. O conteúdo fica entre eles na mesma linha. Aspas e barras invertidas dentro do conteúdo são literais:

// A raw string literal starts and ends with at least three quotes.
// Inside, " and \ are literal — no escaping required.
string message = """She said "hi" and left.""";
string regex   = """\d{3}-\d{4}""";

Console.WriteLine(message);   // She said "hi" and left.
Console.WriteLine(regex);     // \d{3}-\d{4}

Uma cadeia de caracteres bruta de linha única não pode estar vazia entre seus delimitadores. Pode terminar com uma aspa dupla, mas não pode começar com uma. O compilador trata uma aspa dupla inicial como um caractere adicional de delimitador de abertura. Se o conteúdo precisar começar com uma aspa, use um literal de cadeia de caracteres bruta de várias linhas, que coloca o conteúdo em sua própria linha em que uma aspa principal é inequívoca.

Cadeias de caracteres brutas de várias linhas

Para conteúdo multilinha, o delimitador de abertura termina a linha e o delimitador de fechamento inicia seu próprio. Assim como nas strings brutas de linha única, o delimitador consiste em três ou mais aspas duplas, e o delimitador de fechamento deve usar o mesmo número de aspas que o delimitador de abertura. Três aspas são o caso comum, mas você pode usar quatro, cinco ou mais quando o conteúdo em si contiver uma execução de """. Tudo entre os dois delimitadores é o valor da string, exatamente como está escrito:

// The opening """ and closing """ each sit on their own line.
// The content between them is the value, exactly as written.
string sql = """
    SELECT id, name
    FROM customers
    WHERE active = 1
    """;

Console.WriteLine(sql);

A nova linha imediatamente após a abertura """ e a nova linha imediatamente antes do fechamento """ não fazem parte do valor. Eles são delimitados por espaços em branco. Da mesma forma, o compilador remove qualquer espaço em branco à esquerda do fechamento """ de cada linha de conteúdo, para que você possa recuar o literal para corresponder ao bloco de código delimitador sem que esse recuo apareça na cadeia de caracteres. A próxima seção aborda essa regra em detalhes.

Se o conteúdo em si contiver uma sequência de """, use quatro aspas ou mais para os delimitadores. O número de delimitadores só precisa ser maior que a maior sequência de aspas no conteúdo. Consulte literais de cadeia de caracteres brutos (referência de linguagem) para obter as regras completas.

Indentação: o delimitador de fechamento define a margem

A coluna de fechamento """ define uma margem à esquerda. O compilador remove o espaço em branco até essa coluna de cada linha de conteúdo. Essa regra permite que você indentize o literal para corresponder ao código ao redor sem poluir o valor:

// The column of the closing """ sets a left margin.
// Whitespace up to that column is stripped from every content line.
string xml = """
        <order id="42">
            <item>book</item>
        </order>
        """;

// First content line begins at column 0 of the value:
Console.WriteLine(xml);
/* Output:
   <order id="42">
       <item>book</item>
   </order>
 */

Se uma linha de conteúdo tiver menos caracteres de espaço em branco à esquerda do que a coluna do delimitador de fechamento, o compilador relatará um erro. Mantenha todas as linhas de conteúdo recuadas pelo menos tanto quanto o fechamento """.

Cadeias de caracteres interpoladas brutas

Adicione um $ prefixo a uma cadeia de caracteres bruta para habilitar a interpolação. As expressões nas lacunas {} são avaliadas, e seus resultados são inseridos no valor:

// A single $ before """ enables interpolation: single { and } mark a hole.
// Inside a single-$ raw string, literal braces aren't allowed — use $$ when
// the content also contains literal { or }.
string name = "Ada";
int    score = 95;

string report = $"""
    Player:  {name}
    Score:   {score}
    Updated: {DateTime.UtcNow:yyyy-MM-dd}
    """;

Console.WriteLine(report);

Se o conteúdo interpolado também precisar dos caracteres literais { ou }, consulte literais de cadeia de caracteres não processados (referência da linguagem).

Quando escolher qual literal usar

Use um literal de cadeia de caracteres bruto sempre que o conteúdo contiver aspas, barras invertidas ou várias linhas. O resultado é mais rápido de ler, mais fácil de copiar e colar de um lugar para outro e livre de bugs relacionados a sequências de escape.

Use um literal de string regular para valores curtos em uma única linha, sem aspas nem barras invertidas, como nomes, mensagens e marcadores de posição de formato.

Use um literal de cadeia de caracteres verbatim (@"...") somente ao trabalhar com código existente que faça uso deles. Para um novo código, as cadeias de caracteres brutas abrangem todos os casos que as cadeias de caracteres verbatim abrangem, com sintaxe mais limpa para aspas inseridas.

Consulte também

  • Last updated on