Letterali di stringa grezza

Tip

Questo articolo fa parte della sezione Nozioni fondamentali per gli sviluppatori che già conoscono almeno un linguaggio di programmazione e stanno imparando C#. Se non si ha familiarità con la programmazione, iniziare prima con le esercitazioni introduttive . Per la grammatica completa, vedere le informazioni di riferimento sulla lingua.

Venire da un'altra lingua? I letterali di stringa non elaborati di C# svolgono lo stesso ruolo delle stringhe di Python e Rust r"...", dei blocchi di testo di Java ("""...""") e delle stringhe template racchiuse tra backtick in JavaScript, TypeScript e Go. La sintassi C# è più vicina ai blocchi di testo di Java, con regole aggiuntive per delimitatori a lunghezza variabile e interpolazione.

Un valore letterale stringa non elaborato è delimitato da tre o più virgolette doppie. All'interno dei delimitatori, ogni carattere viene interpretato letteralmente. Le virgolette e le barre rovesciata non richiedono l'escape e le righe nuove vengono mantenute come scritte. Usare stringhe non elaborate per qualsiasi stringa contenente virgolette, barre rovesciata o più righe: JSON, XML, SQL, espressioni regolari, percorsi di file ed esempi di codice.

Avvertimento

Una stringa letterale raw rende SQL più facile da leggere, ma non rende SQL più sicuro. Non concatenare o interpolare mai i valori forniti dall'utente in un comando SQL. Questa pratica espone l'applicazione a SQL injection. Usare invece comandi con parametri: DbCommand.CreateParameter con DbParameterCollection.Add o gli helper di livello superiore in Entity Framework Core e Dapper. La stessa cautela si applica ad altri formati soggetti a inserimento, ad esempio comandi della shell, filtri LDAP e HTML.

Un letterale che contiene virgolette e barre rovesciate

Un letterale normale richiede sequenze di escape per " e \. Un letterale verbatim richiede comunque "" per includere una virgoletta. Un valore letterale non elaborato non ha bisogno di:

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

Ogni modulo produce la stessa stringa, ma la versione non elaborata legge esattamente come il codice JSON rappresentato.

Stringhe grezze su una sola riga

I delimitatori di apertura e chiusura sono ognuno di almeno tre virgolette doppie e il delimitatore di chiusura deve utilizzare lo stesso numero di virgolette del delimitatore di apertura. Il contenuto si trova tra di essi sulla stessa riga. Le virgolette e le barre rovesciate nel contenuto sono letterali:

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

Una stringa non elaborata a riga singola non può essere vuota tra i delimitatori. Può terminare con una virgoletta doppia, ma non può iniziare con uno. Il compilatore considera una virgoletta doppia iniziale come carattere delimitatore di apertura aggiuntivo. Se il contenuto deve iniziare con una virgoletta, usa invece un letterale raw di stringa su più righe, che colloca il contenuto su una riga separata, dove una virgoletta iniziale non è ambigua.

Stringhe non elaborate su più righe

Per il contenuto su più righe, il delimitatore di apertura termina la riga e il delimitatore di chiusura inizia da solo. Come per le stringhe non elaborate a riga singola, il delimitatore è costituito da tre o più virgolette doppie e il delimitatore di chiusura deve usare lo stesso numero di virgolette dell'apertura. Tre virgolette sono il caso comune, ma è possibile usare quattro, cinque o più quando il contenuto stesso contiene un'esecuzione di """. Tutti gli elementi tra i due delimitatori sono il valore della stringa, esattamente come scritto:

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

La nuova riga immediatamente dopo l'apertura """ e la nuova riga immediatamente prima della chiusura """ non fanno parte del valore. Sono spazi vuoti delimitatori. Analogamente, il compilatore rimuove tutti gli spazi vuoti a sinistra della chiusura """ da ogni riga di contenuto, in modo da poter impostare un rientro del valore letterale in modo che corrisponda al blocco di codice che lo racchiude senza che tale rientro venga visualizzato nella stringa. La sezione successiva illustra in dettaglio questa regola.

Se il contenuto stesso contiene un'esecuzione di """, usare quattro o più virgolette per i delimitatori. Il numero di delimitatori deve solo essere superiore alla sequenza più lunga di virgolette nel contenuto. Vedere valori letterali di stringa non elaborati (informazioni di riferimento sul linguaggio) per le regole complete.

Rientro: il delimitatore di chiusura imposta il margine

La colonna della chiusura """ definisce un margine sinistro. Il compilatore rimuove spazi vuoti fino a quella colonna da ogni riga di contenuto. Questa regola consente di far rientrare il letterale in modo che corrisponda al codice circostante senza alterarne il valore:

// 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 una riga di contenuto contiene meno caratteri di spazio vuoto iniziale rispetto alla colonna del delimitatore di chiusura, il compilatore segnala un errore. Mantieni il rientro di tutte le righe del contenuto almeno pari a quello del tag di chiusura """.

Stringhe letterali interpolate non elaborate

Aggiungere un $ prefisso a una stringa non elaborata per abilitare l'interpolazione. Le espressioni nei {} fori vengono valutate e i relativi risultati vengono inseriti nel valore :

// 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 il contenuto interpolato richiede anche i caratteri letterali { o }, vedi Valori letterali di stringa non elaborati (riferimento al linguaggio).

Quando scegliere quale valore letterale usare

Usa una stringa letterale non elaborata ogni volta che il contenuto contiene virgolette, barre rovesciate o più righe. Il risultato è più breve da leggere, più facile da incollare o da estrarre e privo di bug legati alle sequenze di escape.

Usare un letterale di stringa regolare per valori brevi su una sola riga senza virgolette o barre rovesciate, come nomi, messaggi e segnaposto di formattazione.

Usare una stringa letterale verbatim (@"...") solo quando si lavora con codice esistente che le usa. Nel nuovo codice, le stringhe raw coprono tutti i casi coperti dalle stringhe verbatim, con una sintassi più pulita per le virgolette incluse.

Vedere anche

  • Last updated on