Ham dize değişmezleri

Tip

Bu makale, en az bir programlama dili bilen ve C# dilini öğrenen geliştiriciler için Temel Bilgiler bölümünün bir parçasıdır. Programlamaya yeni başladıysanız ilk olarak Başlangıç öğreticileri ile başlayın. Dilin tüm grameri için dil referansına bakın.

Başka bir dilden mi geliyorsunuz? C# ham dize sabitleri, Python ve Rust'taki r"..." dizeleri, Java'nın metin blokları ("""...""") ve JavaScript, TypeScript ile Go'daki ters tırnaklı şablon dizeleriyle aynı işlevi görür. C# söz dizimi, Java metin bloklarına en yakın ve değişken uzunlukta sınırlayıcılar ve ilişkilendirme için ek kurallar içerir.

Bir ham dize sabiti, üç veya daha fazla çift tırnak işaretiyle çevrelenir. Sınırlayıcıların içinde her karakter olduğu gibi yorumlanır. Tırnak işaretleri ve ters eğik çizgilerden kaçış gerekmez ve yeni satırlar yazıldığı gibi korunur. Tırnak işaretleri, ters eğik çizgiler veya birden çok satır içeren herhangi bir dize için ham dizeler kullanın: JSON, XML, SQL, normal ifadeler, dosya yolları ve kod örnekleri.

Warning

Ham dize sabiti, SQL'in okunmasını kolaylaştırır, ancak SQL'i daha güvenli yapmaz. Hiçbir zaman kullanıcı tarafından sağlanan değerleri bir SQL komutuyla birleştirmeyin veya ilişkilendirmeyin. Bu yöntem, uygulamanızı SQL enjeksiyonuna açık hâle getirir. Bunun yerine parametreli komutları kullanın: DbCommand.CreateParameter ile DbParameterCollection.Add veya Entity Framework Core ve Dapper içindeki üst düzey yardımcılar. Aynı dikkat, kabuk komutları, LDAP filtreleri ve HTML gibi enjeksiyona açık diğer formatlar için de geçerlidir.

Tırnak işaretleri ve ters eğik çizgiler içeren sabit

Normal bir değişmez değer, " ve \ için kaçış karakterlerine ihtiyaç duyar. Birebir bir literalin içine tırnak işareti gömmek için yine de "" gerekir. Ham bir literal için hiçbiri gerekmez:

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

Her form aynı dizeyi üretir, ancak ham sürüm tam olarak temsil ettiği JSON gibi okur.

Tek satırlı ham dizeler

Açılış ve kapanış sınırlayıcılarının her biri en az üç çift tırnak işaretinden oluşur ve kapanış sınırlayıcısı, açılış sınırlayıcısıyla aynı sayıda tırnak işareti kullanmalıdır. İçerik, aralarında aynı satırda yer alır. İçeriğin içindeki tırnak işaretleri ve ters eğik çizgiler gerçek anlamdadır:

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

Tek satırlı ham dize, sınırlayıcıları arasında boş olamaz. Çift tırnak işaretiyle bitebilir, ancak bir tırnak işaretiyle başlayamaz. Derleyici, baştaki çift tırnak işaretini ek bir açma sınırlayıcısı karakteri olarak ele alır. İçeriğinizin bir tırnak işaretiyle başlaması gerekiyorsa, bunun yerine çok satırlı bir ham dize sabiti kullanın; bu, içeriği kendi satırına yerleştirerek baştaki tırnak işaretinin açıkça ayırt edilmesini sağlar.

Çok satırlı ham dizeler

Çok satırlı içerik için, açılış sınırlayıcısı satırı sonlandırır ve kapanış sınırlayıcısı kendi başına başlar. Tek satırlı ham dizelerde olduğu gibi ayraç üç veya daha fazla çift tırnak işaretinden oluşur ve kapanış ayracı, açılış ayracıyla aynı sayıda tırnak işareti kullanmalıdır. Üç tırnak en yaygın kullanımdır, ancak içeriğin kendisi bir """ dizisi içerdiğinde dört, beş veya daha fazlasını kullanabilirsiniz. İki sınırlayıcı arasındaki her şey dizenin değeridir ve tam olarak yazılmıştır:

// 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çılış """ sonrasındaki yeni satır ve kapatmadan """ hemen önceki yeni satır değerin bir parçası değildir. Bunlar ayırıcı boşluklardır. Benzer şekilde derleyici, her içerik satırında kapanıştaki """ etiketinin solundaki tüm boşlukları kaldırır; böylece metin sabitini, bu girinti dizgede görünmeden, onu içeren kod bloğuyla hizalı olacak şekilde girintileyebilirsiniz. Sonraki bölümde bu kural ayrıntılı olarak ele alınır.

İçeriğin kendisinde art arda """ bulunuyorsa, sınırlayıcılar için dört veya daha fazla tırnak kullanın. Sınırlayıcı sayısının yalnızca içerikteki en uzun tırnak sayısını aşması gerekir. Tüm kurallar için bkz. Ham dize sabitleri (dil başvurusu).

Girinti: Kapanış sınırlayıcısı kenar boşluğunu ayarlar

Kapanış """ sütunu bir sol kenar boşluğu tanımlar. Derleyici, her içerik satırından bu sütuna kadar boşluk kaldırır. Bu kural, değeri bozmadan literal’i çevresindeki kodla hizalı olacak şekilde girintilemenizi sağlar:

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

Bir içerik satırında, kapanış sınırlayıcısının bulunduğu sütundan daha az sayıda baştaki boşluk karakteri varsa, derleyici bir hata bildirir. Tüm içerik satırlarını en az kapanış """kadar girintili tutun.

Ham ilişkilendirilmiş dizeler

$ İlişkilendirmeyi etkinleştirmek için ham dizeye bir ön ek ekleyin. Deliklerdeki {} ifadeler değerlendirilir ve sonuçları değere eklenir:

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

Yerleştirilen içeriğinizin { veya } karakterlerini düz olarak içermesi de gerekiyorsa, bkz. Ham dize sabitleri (dil başvurusu).

Hangi sabit değer ne zaman seçilir?

İçerik tırnak işaretleri, ters eğik çizgiler veya birden çok satır içeriyorsa ham dize sabiti kullanın. Sonuç, okunması daha kısa, içine veya dışına yapıştırılması daha kolay ve kaçış dizilerinden kaynaklanan hatalardan arındırılmıştır.

Adlar, iletiler ve biçimlendirme yer tutucuları gibi tırnak işareti ya da ters eğik çizgi bulunmayan kısa, tek satırlı değerler için normal dize sabiti kullanın.

Yalnızca bunları kullanan mevcut kodla çalışırken verbatim dize değişmezini (@"...") kullanın. Yeni kod için ham dizeler, ayrıntılı dizelerin kapsadığı her olayı kapsar ve eklenmiş tırnak işaretleri için daha temiz söz dizimi sağlar.

Ayrıca bakınız

  • Last updated on