Nyers szöveges literálok

Jótanács

Ez a cikk az Alapismeretek szakasz része azon fejlesztők számára, akik már legalább egy programozási nyelvet ismernek, és c#-t tanulnak. Ha még csak most ismerkedik a programozással, először az Első lépések oktatóanyagokkal kezdje. A teljes nyelvhelyességért tekintse meg a nyelvi referenciát.

Más nyelvről jön? A C# nyers sztringliteráljai ugyanazt a szerepet töltik be, mint a Python és a Rust r"..." sztringjei, a Java szövegblokkjai ("""..."""), valamint a JavaScript, a TypeScript és a Go backtickes sablonsztringjei. A C#-szintaxis Java szövegblokkaihoz áll legközelebb, a változó hosszúságú elválasztójelekre és az interpolációra vonatkozó további szabályokkal.

A nyers sztringkonstansokat három vagy több dupla idézőjel tagolja. A határolójelek között minden karakter literálként értelmeződik. Az idézőjelek és a fordított perjelek nem igényelnek menekülést, és az új vonalak megőrződnek az írott módon. Használjon nyers sztringeket minden olyan sztringhez, amely idézőjeleket, fordított perjeleket vagy több sort tartalmaz: JSON, XML, SQL, reguláris kifejezések, fájlelérési utak és kódminták.

Warning

A nyers sztringkonstans megkönnyíti az SQL olvasását, de nem teszi biztonságosabbá az SQL-t. A felhasználó által megadott értékeket soha nem fűzheti össze vagy interpolálhatja sql-parancsba. Ez a gyakorlat sql-injektáláshoz nyitja meg az alkalmazást. Ehelyett használjon paraméteres parancsokat: DbCommand.CreateParameterDbParameterCollection.Add, vagy a Entity Framework Core és Dapper magasabb szintű segítői. Ugyanez az óvatosság vonatkozik más injektálási formátumokra, például a rendszerhéjparancsokra, az LDAP-szűrőkre és a HTML-ekre is.

Idézőjeleket és visszaperjeleket tartalmazó literál

A reguláris literálnak menekülnie kell, " és \. A szó szerinti literálnak továbbra is idézőjelet kell "" beágyaznia. Egy nyers literál egyiket sem igényli:

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

Mindegyik forma ugyanazt a karakterláncot állítja elő, de a nyers változat pontosan úgy olvasható, mint az általa reprezentált JSON.

Egysoros nyers sztringek

A nyitó és záró elválasztójelek legalább három dupla idézőjelből állnak, a záró elválasztónak pedig ugyanolyan számú idézőjelet kell használnia, mint a nyitó elválasztójel. A tartalom közöttük, ugyanazon a soron helyezkedik el. A tartalomban lévő idézőjelek és fordított perjelek szó szerint értendők:

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

Az egysoros nyers sztring nem lehet üres a határolók között. Dupla idézőjellel végződhet, de nem kezdődhet vele. A fordító a sor eleji dupla idézőjelet egy további nyitó elhatároló karakterként kezeli. Ha a tartalomnak idézőjellel kell kezdődnie, használjon inkább többsoros nyers karakterlánc-literált, amely a tartalmat külön sorba helyezi, ahol a nyitó idézőjel egyértelműen értelmezhető.

Többsoros nyers sztringek

Többsoros tartalom esetén a nyitó határoló zárja a sort, a záró határoló pedig külön sort kezd. Az egysoros nyers sztringekhez hasonlóan a határoló három vagy több dupla idézőjel, és a záró határolónak ugyanannyi idézőjelből kell állnia, mint a nyitó határolónak. A három idézőjel a megszokott, de használhat négyet, ötöt vagy még többet is, ha a tartalom maga egymást követő """ jelek sorozatát tartalmazza. A két elválasztójel közötti minden a sztring értéke, pontosan úgy, ahogy le van írva:

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

Az új vonal közvetlenül a megnyitás """ után, az új vonal pedig közvetlenül a zárás """ előtt nem része az értéknek. Azok elválasztó üres karakterek. Hasonlóképpen, a fordítóprogram minden tartalomsorban eltávolítja a záró """ jeltől balra eső üres helyeket, így a literált úgy igazíthatja a környező kódblokk behúzásához, hogy ez a behúzás ne jelenjen meg a karakterláncban. A következő szakasz részletesen ismerteti ezt a szabályt.

Ha maga a tartalom tartalmaz egy """ karaktersorozatot, használjon négy vagy több idézőjelet határolóként. Az elválasztójelek számának csak meg kell haladnia a tartalomban lévő idézőjelek leghosszabb megszakítás nélküli sorozatát. A szabályok teljes leírását lásd: Nyers karakterlánc-literálok (nyelvi referencia).

Behúzás: a záróhatároló határozza meg a margót

A záró """ oszlop bal margót határoz meg. A fordító minden tartalomsor elejéről eltávolítja az adott oszlopig terjedő üres helyeket. Ez a szabály lehetővé teszi a literál behúzását, hogy megfeleljen a környező kódnak az érték szennyezése nélkül:

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

Ha egy tartalomsor elején kevesebb üres karakter van, mint a záró határoló oszloppozíciója, a fordítóprogram hibát jelez. Minden tartalomsor legyen legalább annyira behúzva, mint a záró """.

Nyers interpolált karakterláncok

Adjon hozzá egy előtagot $ egy nyers sztringhez az interpoláció engedélyezéséhez. A {} helyőrzőkben lévő kifejezéseket a rendszer kiértékeli, és az eredményeket beszúrja az értékbe:

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

Ha az interpolált tartalomnak a(z) { vagy } literális karakterekre is szüksége van, lásd: Nyers sztringliterálok (nyelvi referencia).

Mikor melyik literált válasszuk

Használjon nyers karakterláncliterált, ha a tartalom idézőjeleket, fordított perjeleket vagy több sorból áll. Az eredmény rövidebb, könnyebben olvasható, könnyebb beilleszteni és kimásolni belőle, valamint mentes az escape-szekvenciákkal kapcsolatos hibáktól.

Rövid, egysoros, idézőjeleket vagy fordított perjeleket nem tartalmazó értékekhez, például nevekhez, üzenetekhez és formátumhelyőrzőkhöz használjon normál karakterlánc-literált.

Csak akkor használjon verbatim sztringliterált (@"..."), ha meglévő, ezt használó kóddal dolgozik. Új kód esetén a nyers sztringek minden olyan esetet lefednek, amely szó szerinti sztringeket fed le, a beágyazott idézőjelek tisztább szintaxisával.

Lásd még

  • Last updated on