Unformatierten Zeichenfolgenliterale

Tip

Dieser Artikel ist Teil des Abschnitts "Grundlagen" für Entwickler, die bereits mindestens eine Programmiersprache kennen und C# erlernen. Wenn Sie noch nicht mit der Programmierung vertraut sind, beginnen Sie zuerst mit den Lernprogrammen " Erste Schritte ". Die vollständige Grammatik finden Sie in der Sprachreferenz.

Kommen Sie aus einer anderen Sprache? C#-Rohzeichenfolgenliterale erfüllen dieselbe Funktion wie die r"..."-Zeichenfolgen von Python und Rust, Javas Textblöcke ("""...""") und die in Backticks eingeschlossenen Template-Strings in JavaScript, TypeScript und Go. Die C#-Syntax ist den Textblöcken Java am nächsten, mit zusätzlichen Regeln für Trennzeichen mit variabler Länge und Interpolation.

Ein Raw-String-Literal wird durch drei oder mehr doppelte Anführungszeichen begrenzt. Innerhalb der Trennzeichen wird jedes Zeichen wörtlich genommen. Anführungszeichen und Backslashes müssen nicht maskiert werden, und Zeilenumbrüche werden wie geschrieben beibehalten. Verwenden Sie unformatierte Zeichenfolgen für eine beliebige Zeichenfolge, die Anführungszeichen, umgekehrte Schrägstriche oder mehrere Zeilen enthält: JSON, XML, SQL, reguläre Ausdrücke, Dateipfade und Codebeispiele.

Warnung

Ein unformatiertes Zeichenfolgenliteral erleichtert das Lesen von SQL, macht SQL aber nicht sicherer. Verketten oder interpolieren Sie niemals vom Benutzer bereitgestellte Werte in einen SQL-Befehl. Diese Vorgehensweise öffnet Ihre Anwendung zur SQL-Einfügung. Verwenden Sie stattdessen parametrisierte Befehle: DbCommand.CreateParameter mit DbParameterCollection.Add oder den Hilfsern auf höherer Ebene in Entity Framework Core und Dapper. Die gleiche Vorsicht gilt für andere einfügeanfällige Formate wie Shellbefehle, LDAP-Filter und HTML.

Ein Literal, das Anführungszeichen und Backslashes enthält

Ein reguläres Literal benötigt Escapezeichen für " und \. Ein verbatim literal benötigt weiterhin "", um ein Anführungszeichen einzubetten. Ein unformatiertes Literal benötigt weder:

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

Jedes Formular erzeugt dieselbe Zeichenfolge, aber die unformatierte Version liest genau wie der JSON-Code, den es darstellt.

Einzeilige unformatierte Zeichenfolgen

Die öffnenden und schließenden Begrenzer bestehen jeweils aus mindestens drei doppelten Anführungszeichen, und der schließende Begrenzer muss dieselbe Anzahl an Anführungszeichen wie der öffnende verwenden. Der Inhalt befindet sich zwischen ihnen in derselben Zeile. Anführungszeichen und Backslashes im Inhalt sind wörtlich zu verstehen:

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

Ein einzeiliger Raw-String darf zwischen seinen Begrenzungszeichen nicht leer sein. Es kann mit einem doppelten Anführungszeichen enden, aber es kann nicht mit einem beginnen. Der Compiler behandelt ein führendes doppeltes Anführungszeichen als zusätzliches öffnendes Trennzeichen. Wenn Ihr Text mit einem Anführungszeichen beginnen muss, verwenden Sie stattdessen ein mehrzeiliges Raw-String-Literal, das den Text in eine eigene Zeile setzt, wo ein führendes Anführungszeichen eindeutig zuzuordnen ist.

Mehrzeilige Rohzeichenfolgen

Bei mehrzeiligen Inhalten steht das öffnende Trennzeichen am Ende der Zeile, und das schließende Trennzeichen beginnt eine eigene Zeile. Wie bei einzeiligen Raw-Strings besteht das Trennzeichen aus drei oder mehr doppelten Anführungszeichen, und das schließende Trennzeichen muss dieselbe Anzahl von Anführungszeichen wie das öffnende Trennzeichen verwenden. Drei Anführungszeichen sind der Regelfall, aber Sie können vier, fünf oder mehr verwenden, wenn der Inhalt selbst eine Folge von """ enthält. Alles zwischen den beiden Trennzeichen ist der Wert der Zeichenfolge, exakt wie angegeben:

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

Der Zeilenumbruch direkt nach dem öffnenden """ und der Zeilenumbruch direkt vor dem schließenden """ sind nicht Teil des Werts. Es handelt sich um Trenn-Leerzeichen. Ebenso entfernt der Compiler in jeder Inhaltszeile alle Leerzeichen links vom abschließenden """, sodass Sie das Literal so einrücken können, dass es dem umgebenden Codeblock entspricht, ohne dass diese Einrückung in der Zeichenfolge erscheint. Im nächsten Abschnitt wird diese Regel ausführlich behandelt.

Wenn der Inhalt selbst eine Ausführung """enthält, verwenden Sie vier oder mehr Anführungszeichen für die Trennzeichen. Die Anzahl der Trennzeichen muss nur die längste Anzahl von Anführungszeichen im Inhalt überschreiten. Die vollständigen Regeln finden Sie unter Rohzeichenfolgenliterale (Sprachreferenz).

Einzug: Das schließende Trennzeichen legt den Rand fest.

Die Spalte des Schließens """ definiert einen linken Rand. Der Compiler entfernt Leerzeichen bis zu dieser Spalte aus jeder Inhaltszeile. Mit dieser Regel können Sie das Literal so einziehen, dass es mit dem umgebenden Code übereinstimmt, ohne den Wert zu verunreinigen:

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

Wenn eine Inhaltszeile weniger führende Leerzeichen als die Spalte des schließenden Trennzeichens enthält, meldet der Compiler einen Fehler. Halten Sie alle Inhaltszeilen mindestens so weit eingerückt wie das schließende """.

Interpolierte Rohzeichenfolgen

Fügen Sie einer unformatierten Zeichenfolge ein $ Präfix hinzu, um die Interpolation zu aktivieren. Die Ausdrücke in {} Löchern werden ausgewertet, und ihre Ergebnisse werden in den Wert eingefügt:

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

Wenn Ihr interpolierter Inhalt auch die Zeichen { oder } wörtlich enthalten muss, siehe Unformatierte Zeichenfolgenliterale (Sprachreferenz).

Wann welches Literal gewählt werden sollte

Verwenden Sie ein unformatiertes Zeichenfolgenliteral , wenn der Inhalt Anführungszeichen, umgekehrte Schrägstriche oder mehrere Zeilen enthält. Das Ergebnis ist kürzer, lässt sich leichter einfügen oder herauskopieren und ist frei von Fehlern durch Escape-Sequenzen.

Verwenden Sie ein reguläres String-Literal für kurze, einzeilige Werte, die keine Anführungszeichen oder Backslashes enthalten, beispielsweise Namen, Nachrichten oder Formatplatzhalter.

Verwenden Sie ein Verbatim-Zeichenfolgenliteral (@"...") nur, wenn Sie mit vorhandenem Code arbeiten, der sie verwendet. Bei neuem Code decken Rohzeichenfolgen alle Fälle ab, die auch wörtliche Zeichenfolgen abdecken, und bieten dabei eine klarere Syntax für eingebettete Anführungszeichen.

Siehe auch

  • Last updated on