Nezpracované řetězcové literály

Tip

Tento článek je součástí části Základy pro vývojáře, kteří už znají aspoň jeden programovací jazyk a učí se jazyk C#. Pokud s programováním teprve začínáte, začněte nejprve kurzy Začínáme . Úplnou gramatiku najdete v referenčních informacích k jazyku.

Pochází z jiného jazyka? Syrové řetězcové literály jazyka C# plní stejnou roli jako řetězce v Pythonu a řetězce r"..." v Rustu, textové bloky v Javě ("""...""") a šablonové řetězce se zpětnými apostrofy v jazycích JavaScript, TypeScript a Go. Syntaxe jazyka C# je nejblíže k textovým blokům Java s dodatečnými pravidly pro oddělovače délky proměnných a interpolaci.

Nezpracovaný řetězcový literál je oddělený třemi nebo více dvojitými uvozovkami. Uvnitř oddělovačů se každý znak bere doslovně. Uvozovky a zpětné lomítka nepotřebují uvozovky a nové čáry se zachovají jako napsané. U všech řetězců, které obsahují uvozovky, zpětná lomítka nebo více řádků, používejte raw řetězce: JSON, XML, SQL, regulární výrazy, cesty k souborům a ukázky kódu.

Warning

Nezpracovaný řetězcový literál usnadňuje čtení SQL, ale neznamená to, že SQL bude bezpečnější. Nikdy nezřetězujte ani nevkládejte hodnoty zadané uživatelem do příkazu SQL. Tento postup vystavuje vaši aplikaci útokům typu SQL injection. Místo toho použijte parametrizované příkazy: DbCommand.CreateParameter s DbParameterCollection.Add nebo pomocné rutiny vyšší úrovně v Entity Framework Core a Dapper. Stejná obezřetnost platí i pro jiné formáty náchylné k injektáži, jako jsou příkazy shellu, filtry LDAP a HTML.

Literál, který obsahuje uvozovky a zpětná lomítka

Obyčejný literál vyžaduje escape sekvence pro " a \. Doslovný řetězec stále potřebuje "", aby bylo možné vložit text do uvozovek. Surový literál nepotřebuje ani jedno z následujícího:

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

Každý formulář vytvoří stejný řetězec, ale nezpracovaná verze se čte stejně jako JSON, který představuje.

Nezpracované řetězce s jedním řádkem

Počáteční i koncový oddělovač jsou tvořeny alespoň třemi dvojitými uvozovkami a koncový oddělovač musí mít stejný počet uvozovek jako počáteční oddělovač. Obsah se nachází mezi nimi na stejném řádku. Uvozovky a zpětná lomítka v obsahu mají doslovný význam:

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

Nezpracovaný řetězec s jedním řádkem nemůže být mezi jeho oddělovači prázdný. Může končit dvojitou uvozovkou, ale nemůže začínat jednou. Kompilátor považuje úvodní dvojitou uvozovku za další počáteční znak oddělovače. Pokud váš obsah musí začínat uvozovkou, použijte místo toho víceřádkový nezpracovaný řetězcový literál, který umístí obsah na vlastní řádek, kde je úvodní uvozovka jednoznačná.

Víceřádkové nezpracované řetězce

U víceřádkového obsahu počáteční oddělovač ukončuje řádek a koncový oddělovač začíná na samostatném řádku. Stejně jako u jednořádkových nezpracovaných řetězců tvoří oddělovač tři nebo více dvojitých uvozovek a uzavírací oddělovač musí používat stejný počet uvozovek jako otevírací. Tři uvozovky jsou běžná varianta, ale můžete použít čtyři, pět nebo i více, pokud samotný obsah obsahuje sekvenci """. Všechno mezi těmito dvěma oddělovači je hodnota řetězce, přesně tak, jak je napsaná:

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

Nový řádek bezprostředně za otevírací značkou """ a nový řádek bezprostředně před uzavírací značkou """ nejsou součástí hodnoty. Jsou to bílé znaky jako oddělovače. Stejně tak kompilátor z každého řádku obsahu odstraní všechny bílé znaky nalevo od uzavírací značky """, takže literál můžete odsadit tak, aby odpovídal okolnímu bloku kódu, aniž by se toto odsazení objevilo v řetězci. Další část podrobně popisuje toto pravidlo.

Pokud se v samotném obsahu vyskytuje """, použijte jako oddělovače čtyři nebo více uvozovek. Stačí, aby počet oddělovačů byl vyšší než nejdelší souvislá posloupnost uvozovek v obsahu. Úplná pravidla najdete v části Nezpracované řetězcové literály (referenční příručka jazyka).

Odsazení: uzavírací oddělovač určuje okraj.

Sloupec závěru """ definuje levý okraj. Kompilátor z každého řádku obsahu odstraní bílé znaky až k danému sloupci. Toto pravidlo umožňuje odsadit literál tak, aby odpovídal okolnímu kódu bez znečisťování hodnoty:

// 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>
 */

Pokud řádek obsahu obsahuje méně úvodních prázdných znaků než sloupec koncového oddělovače, kompilátor hlásí chybu. Ponechte všechny řádky s obsahem odsazené alespoň stejně jako uzavírací """.

Nezpracované interpolované řetězce

$ Přidání předpony do nezpracovaného řetězce pro povolení interpolace Výrazy v {} dírách se vyhodnocují a jejich výsledky se vloží do hodnoty:

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

Pokud interpolovaný obsah také obsahuje doslovné znaky { nebo }, viz Nezpracované řetězcové literály (referenční příručka jazyka).

Kdy zvolit který literál

Použijte doslovný řetězcový literál vždy, když obsahuje uvozovky, zpětná lomítka nebo více řádků. Výsledek je kratší, snáze se čte, snáze se do něj vkládá text a kopíruje z něj a neobsahuje chyby způsobené escape sekvencemi.

Použijte obyčejný řetězcový literál pro krátké jednořádkové hodnoty bez uvozovek a zpětných lomítek, například názvy, zprávy a zástupné symboly formátu.

Řetězcový literál verbatim (@"...") používejte pouze při práci se stávajícím kódem, který je používá. Pro nový kód nezpracované řetězce pokrývají každý případ, který doslovné řetězce pokrývají, s čistější syntaxí pro vložené uvozovky.

Viz také

  • Last updated on