$ kullanılarak dize interpolasyonu

Dize değişmez $ değerlerini ilişkilendirilmiş bir dize olarak tanımlamak için karakterini kullanın. Ara dize, ilişkilendirme ifadeleri içerebilen bir dize sabitidir. İlişkili bir dizeyi bir sonuç dizesine çözümlediğinizde, derleyici ifade sonuçlarının dize gösterimleriyle öğeleri ilişkilendirme ifadeleriyle değiştirir.

C# dili başvuru belgesi, C# dilinin en son yayımlanan sürümünü gösterir. Ayrıca, yaklaşan dil sürümü için genel önizlemelerdeki özelliklere yönelik ilk belgeleri içerir.

Belgelerde ilk olarak dilin son üç sürümünde veya geçerli genel önizlemelerde sunulan tüm özellikler tanımlanır.

Tavsiye

Bir özelliğin C# dilinde ilk tanıtıldığı zamanları bulmak için C# dil sürümü geçmişi makalesine bakın.

Dize ilişkilendirmesi, dizeleri biçimlendirmek için daha okunabilir ve kullanışlı bir söz dizimi sağlar. Okuması, dize bileşik biçimlendirmesinden daha kolaydır. Aşağıdaki örnek, aynı çıkışı oluşturmak için her iki özelliği de kullanır:

var name = "Mark";
var date = DateTime.Now;

// Composite formatting:
Console.WriteLine("Hello, {0}! Today is {1}, it's {2:HH:mm} now.", name, date.DayOfWeek, date);
// String interpolation:
Console.WriteLine($"Hello, {name}! Today is {date.DayOfWeek}, it's {date:HH:mm} now.");
// Both calls produce the same output that is similar to:
// Hello, Mark! Today is Wednesday, it's 19:40 now.

sabit dizesini başlatmak için interpolasyonlu bir dize kullanabilirsiniz. Bunu yalnızca, ilişkilendirilmiş dizedeki tüm ilişkilendirme ifadeleri de sabit dizelerse yapabilirsiniz.

İlişkili dizenin yapısı

Dize sabitini ilişkilendirilmiş bir dize yapmak için, simgeyi $ en başa ekleyin. ile arasında $" dize değişmez değeri başlatan boşluk eklemeyin.

İlişkilendirme ifadesi olan bir öğenin yapısı aşağıdaki gibidir:

{<interpolationExpression>[,<width>][:<formatString>]}

Köşeli ayraç içindeki öğeler isteğe bağlıdır. Aşağıdaki tabloda her öğe açıklanmaktadır:

Öğe	Açıklama
interpolationExpression	Biçimlendirilecek bir sonuç üreten ifade. ifadesi olduğunda null, çıkış boş dizedir (String.Empty).
width	Değeri ifade sonucunun dize gösterimindeki en az karakter sayısını tanımlayan sabit ifade. Pozitifse, dize gösterimi sağa hizalanır; negatifse, sola hizalı. Daha fazla bilgi için Birleşik biçimlendirme makalesinin Genişlik bileşeni bölümüne bakınız.
formatString	İfade sonucunun türü tarafından desteklenen bir biçim dizesi. Daha fazla bilgi için Birleşik biçimlendirme makalesinin Biçim dizesi bileşeni bölümüne bakın.

Aşağıdaki örnek, önceki tabloda açıklanan isteğe bağlı biçimlendirme bileşenlerini kullanır:

Console.WriteLine($"|{"Left",-7}|{"Right",7}|");

const int FieldWidthRightAligned = 20;
Console.WriteLine($"{Math.PI,FieldWidthRightAligned} - default formatting of the pi number");
Console.WriteLine($"{Math.PI,FieldWidthRightAligned:F3} - display only three decimal digits of the pi number");
// Output is:
// |Left   |  Right|
//     3.14159265358979 - default formatting of the pi number
//                3.142 - display only three decimal digits of the pi number

Kodu daha okunabilir hale getirmek için ilişkilendirme ifadesi içinde yeni satırlar kullanın. Aşağıdaki örnekte, yeni satırların desen eşleştirme içeren bir ifadenin okunabilirliğini nasıl artırabileceği gösterilmektedir:

string message = $"The usage policy for {safetyScore} is {
    safetyScore switch
    {
        > 90 => "Unlimited usage",
        > 80 => "General usage, with daily safety check",
        > 70 => "Issues must be addressed within 1 week",
        > 50 => "Issues must be addressed within 1 day",
        _ => "Issues must be addressed before continued use",
    }
    }";

Enterpolasyonlu ham dize değişmezleri

Aşağıdaki örnekte gösterildiği gibi, ilişkilendirilmiş ham dize değişmez değerini kullanabilirsiniz:

int X = 2;
int Y = 3;

var pointMessage = $"""The point "{X}, {Y}" is {Math.Sqrt(X * X + Y * Y):F3} from the origin""";

Console.WriteLine(pointMessage);
// Output is:
// The point "2, 3" is 3.606 from the origin

Sonuç dizesine { ve } karakterlerini gömmek için, birden fazla $ karakter içeren ilişkilendirilmiş bir ham dize değişmez değeri başlatın. Bunu yaptığınızda, { veya } karakterlerinden oluşan ve $ karakter sayısından daha kısa olan herhangi bir dizi sonuç dizesine gömülür. Bu dizenin içindeki ilişkilendirme ifadelerini içine almak için, aşağıdaki örnekte gösterildiği gibi karakter sayısıyla aynı sayıda $ ayraç kullanmanız gerekir:

int X = 2;
int Y = 3;

var pointMessage = $$"""{The point {{{X}}, {{Y}}} is {{Math.Sqrt(X * X + Y * Y):F3}} from the origin}""";
Console.WriteLine(pointMessage);
// Output is:
// {The point {2, 3} is 3.606 from the origin}

Yukarıdaki örnekte, ilişkilendirilmiş bir ham dize değişmez değeri iki $ karakterle başlar. Her ilişkilendirme ifadesini çift ayraçlar ({{ ve }}) arasına yerleştirmeniz gerekir. Sonuç dizisine tek bir küme ayracı gömülür. Bir sonuç dizesine yinelenen { veya } karakter eklemeniz gerekiyorsa, ilişkilendirilmiş ham dize değişmez değerini ayarlamak için uygun sayıda $ karakter kullanın. Dize değişmez değerdeki yinelenen küme ayracı sayısı $ karakteri sayısından fazlaysa, { ve } karakterleri içeriden dışarıya doğru gruplandırılır. Önceki örnekte, doğrudan The point {{{X}}, {{Y}}} ve {{X}}, {{Y}} ifadelerini ilişkilendirilmiş ifadeler olarak yorumlar. Dış { ve } , çıkış dizesine eksiksiz olarak eklenir.

Tavsiye

Visual Studio ve C# Dev Kit, ham dize değişmez değerleri JSON verileri veya normal ifadeler içerdiğinde bazı doğrulama ve söz dizimi vurgulamaları sağlar.

Araçlar metni ayrıştırma. Araçlarda metnin JSON veya normal ifadeyi temsil ettiği konusunda güven varsa, düzenleyici söz dizimi renklendirmesi sağlar.

Bildirimin üzerine biçimi belirten bir açıklama ekleyerek bu deneyimi geliştirebilirsiniz:

• // lang=json ham dize değişmez değerinin JSON verilerini temsil eder.
• // lang=regex ham dize değişmez değerinin normal bir ifadeyi temsil eder.

Bir ham dize değişmez değeri, parametresinin biçimini belirtmek için öğesini System.Diagnostics.CodeAnalysis.StringSyntaxAttribute kullandığı bir bağımsız değişken olarak kullanıldığında, bu araçlar bazı biçim türleri için ham dize değişmez değerini doğrular. Hem JSON hem de regex desteklenir.

Bazı biçimler için açıklama veya öznitelik, biçime göre dize değişmez değerleri için düzeltmeler sunan kod önerileri sağlar.

Özel karakterler

Interpolasyonlu dize ile üreteceğiniz metne "{" veya "}" eklemek amacıyla iki ayraç kullanın: "{{" veya "}}". Daha fazla bilgi için Birleşik biçimlendirme makalesinin Süslü parantezlerden kaçış bölümüne bakın.

İki nokta üst üste (":") bir ilişkilendirme ifade öğesinde özel bir anlama sahiptir. bir ilişkilendirme ifadesinde koşullu işleç kullanmak için, bu ifadeyi parantez içine alın.

Aşağıdaki örnekte, bir sonuç dizesine ayraç ekleme gösterilmektedir. Ayrıca koşullu işlecin nasıl kullanılacağını da gösterir:

string name = "Horace";
int age = 34;
Console.WriteLine($"He asked, \"Is your name {name}?\", but didn't wait for a reply :-{{");
Console.WriteLine($"{name} is {age} year{(age == 1 ? "" : "s")} old.");
// Output is:
// He asked, "Is your name Horace?", but didn't wait for a reply :-{
// Horace is 34 years old.

Ara yerleştirilmiş bir düz metin dizesi $ ve @ karakterleriyle başlar. $ ve @ etiketlerini herhangi bir sıra ile kullanabilirsiniz: hem $@"..." hem de @$"..." geçerli iç içe geçmiş özgün dizelerdir. Ayrıntılı dizeler hakkında daha fazla bilgi için dize ve ayrıntılı tanımlayıcı makalelerine bakın.

Kültüre özgü biçimlendirme

Varsayılan olarak, bir interpolated dize, tüm biçimlendirme işlemleri için CultureInfo.CurrentCulture özelliği tarafından tanımlanan mevcut kültürü kullanır.

Kültüre özel bir sonuç dizesine ulaşmak için, .NET 6 ile birlikte sunulan String.Create(IFormatProvider, DefaultInterpolatedStringHandler) yöntemini kullanın. Aşağıdaki örnek bunun nasıl yapılacağını gösterir:

double speedOfLight = 299792.458;

System.Globalization.CultureInfo.CurrentCulture = System.Globalization.CultureInfo.GetCultureInfo("nl-NL");
string messageInCurrentCulture = $"The speed of light is {speedOfLight:N3} km/s.";

var specificCulture = System.Globalization.CultureInfo.GetCultureInfo("en-IN");
string messageInSpecificCulture = string.Create(
    specificCulture, $"The speed of light is {speedOfLight:N3} km/s.");

string messageInInvariantCulture = string.Create(
    System.Globalization.CultureInfo.InvariantCulture, $"The speed of light is {speedOfLight:N3} km/s.");

Console.WriteLine($"{System.Globalization.CultureInfo.CurrentCulture,-10} {messageInCurrentCulture}");
Console.WriteLine($"{specificCulture,-10} {messageInSpecificCulture}");
Console.WriteLine($"{"Invariant",-10} {messageInInvariantCulture}");
// Output is:
// nl-NL      The speed of light is 299.792,458 km/s.
// en-IN      The speed of light is 2,99,792.458 km/s.
// Invariant  The speed of light is 299,792.458 km/s.

.NET 5 ve önceki .NET sürümlerinde, interpolasyonlu bir dizenin bir FormattableString örneğine dönüştürülmesi için örtük dönüşümü kullanın. Ardından, kültüre özgü bir sonuç dizesi oluşturmak için bir örnek FormattableString.ToString(IFormatProvider) yöntemi veya statik FormattableString.Invariant bir yöntem kullanabilirsiniz. Aşağıdaki örnek bunun nasıl yapılacağını gösterir:

double speedOfLight = 299792.458;
FormattableString message = $"The speed of light is {speedOfLight:N3} km/s.";

var specificCulture = System.Globalization.CultureInfo.GetCultureInfo("en-IN");
string messageInSpecificCulture = message.ToString(specificCulture);
Console.WriteLine(messageInSpecificCulture);
// Output:
// The speed of light is 2,99,792.458 km/s.

string messageInInvariantCulture = FormattableString.Invariant(message);
Console.WriteLine(messageInInvariantCulture);
// Output is:
// The speed of light is 299,792.458 km/s.

Özel biçimlendirme hakkında daha fazla bilgi için .NET'te biçimlendirme türleri makalesinin ICustomFormatter ile özel biçimlendirme bölümüne bakın.

Diğer kaynaklar

Dize ilişkilendirmeyi yeni kullanıyorsanız C# dilinde dize ilişkilendirme öğreticisine bakın. Bu öğreticide, biçimlendirilmiş dizeler oluşturmak için ilişkilendirilmiş dizelerin nasıl kullanılacağı gösterilmektedir.

Ara dizelerin derlenmesi

Derleyici, ilişkilendirilmiş dizeninilişkilendirilmiş dize işleyici desenini karşılayan bir türe atandığını denetler. İlişkili dize işleyicisi, ilişkilendirilmiş dizeyi bir sonuç dizesine dönüştüren bir türdür. İlişkili bir dize türüne stringSystem.Runtime.CompilerServices.DefaultInterpolatedStringHandler sahip olduğunda, bunu işler. Özel ilişkilendirilmiş dize işleyicisi örneği için Bkz. Özel dize ilişkilendirme işleyicisi yazma öğreticisi . İnterpolasyonlu dize işleyicisi kullanımı, genellikle performans nedenleriyle gerekli olan gelişmiş bir durumdur.

Uyarı

Ara dize işleyicilerinin bir yan etkisi, System.Runtime.CompilerServices.DefaultInterpolatedStringHandler dahil olmak üzere özel bir işleyicinin tüm koşullar altında ara dize içindeki tüm ilişkilendirme ifadelerini değerlendirmeyebileceğidir. Bu davranış, bu ifadelerin yan etkilerinin oluşmayabileceği anlamına gelir.

İlişkili dize türüne stringsahipse, derleyici bunu genellikle bir String.Format yöntem çağrısına dönüştürür. Derleyici, çözümlenen davranışın birleştirmeye eşdeğer olması durumunda String.Format öğesini String.Concat ile değiştirebilir.

İliştirilen dize IFormattable veya FormattableString türüne sahipse, derleyici FormattableStringFactory.Create yöntemine bir çağrı oluşturur.

C# dil belirtimi

Daha fazla bilgi için C# dil belirtimininİlişkili dize ifadeleri bölümüne ve aşağıdaki yeni özellik belirtimlerine bakın:

• geliştirilmiş interpolasyonlu dizeler
• Ham dize değişmez değerleri
• Dize ilişkilendirmelerinde yeni satırlar

Ayrıca bakınız

• C# özel karakterleri
• String
• Standart sayısal biçim dizeleri
• Bileşik biçimlendirme
• String.Format
• İlişkilendirmeyi basitleştirme (stil kuralı IDE0071)
• C# 10 ve .NET 6'da dize ilişkilendirme (.NET blogu)