Aracılığıyla paylaş

Kullanarak dize ilişkilendirmesi $

  • Makale

Karakter, $ bir dize sabitini ilişkilendirilmiş bir dize olarak tanımlar. İlişkilendirilmiş dize, ilişkilendirme ifadeleri içerebilen bir dize değişmez değeridir. İlişkili bir dize bir sonuç dizesine çözümlendiğinde, derleyici ifade sonuçlarının dize gösterimleriyle öğeleri ilişkilendirme ifadeleriyle değiştirir.

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.

C# 10 ile başlayarak, sabit bir dize başlatmak için ilişkilendirilmiş bir dize kullanabilirsiniz. Bunu yalnızca, ilişkilendirilmiş dizedeki tüm ilişkilendirme ifadeleri de sabit dizelerse yapabilirsiniz.

İlişkili dizenin yapısı

Bir dize sabitini ilişkilendirilmiş bir dize olarak tanımlamak için, bunu simgesiyle $ ekleyin. ile arasında $ " dize değişmez değeri başlatan boşluk olamaz.

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

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

Köşeli parantezler 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).
alignment 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 Bileşik biçimlendirme makalesinin Hizalama bileşeni bölümüne bakın.
formatString İfade sonucunun türü tarafından desteklenen bir biçim dizesi. Daha fazla bilgi için Bileşik biçimlendirme makalesinin Dize bileşenini biçimlendirme 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

C# 11'den başlayarak, ifadenin kodunu daha okunabilir hale getirmek için bir ilişkilendirme ifadesi içinde yeni satırlar kullanabilirsiniz. Aşağıdaki örnekte, yeni satırların desen eşleştirme içeren bir ifadenin okunabilirliğini nasıl geliştirebileceğ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",
    }
    }";

İlişkili ham dize değişmez değerleri

C# 11'den başlayarak, aşağıdaki örnekte gösterildiği gibi ilişkilendirilmiş bir ham dize değişmez değeri 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 } karakter eklemek { için, birden çok $ karakter içeren ilişkilendirilmiş bir ham dize değişmez değeri başlatın. Bunu yaptığınızda, sonuç dizesine karakter sayısından { $ daha kısa olan veya } karakterlerin herhangi bir dizisi eklenir. 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ç dizesine tek bir küme ayracı eklenir. 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ğeri, karakter sayısından $ daha fazla yinelenen küme ayracına sahipse, { ve } karakterleri içeriden dışarıya gruplandırılır. Yukarıdaki örnekte, değişmez değer The point {{{X}}, {{Y}}} ve {{Y}} değerlerini ilişkilendirilmiş ifadeler olarak yorumlar{{X}}. Dış { ve } , çıkış dizesine ayrıntılı olarak eklenir.

Özel karakterler

İlişkili dize tarafından oluşturulan metne "{" veya "}" ayracı eklemek için iki ayraç kullanın: "{{" veya "}}". Daha fazla bilgi için Bileşik biçimlendirme makalesinin Kaçış ayraçları bölümüne bakın.

İki nokta üst üste (":") bir ilişkilendirme ifadesi öğesinde özel bir anlama sahip olduğundan, ilişkilendirme ifadesinde koşullu işleç kullanmak için kullanılır. 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.

İlişkili bir düz metin dizesi hem hem de $ @ karakterleriyle başlar. ve @ öğesini herhangi bir sırada kullanabilirsiniz$: hem @$"..." hem de $@"..." geçerli ilişkilendirilmiş düz metin dizeleridir. 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, ilişkilendirilmiş dize tüm biçimlendirme işlemleri için özelliği tarafından CultureInfo.CurrentCulture tanımlanan geçerli kültürü kullanır.

Kültüre özgü bir sonuç dizesiyle ilişkilendirilmiş bir dizeyi çözümlemek için .NET 6 ile başlayan yöntemini kullanın String.Create(IFormatProvider, DefaultInterpolatedStringHandler) . 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, ilişkilendirilmiş bir dizenin örneğe örtük olarak dönüştürülmesi FormattableString kullanılır. 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# etkileşimli öğreticisinde dize ilişkilendirmesi bölümüne bakın. C# öğreticisinde başka bir Dize ilişkilendirmesini de de kontrol edebilirsiniz. Bu öğreticide, biçimlendirilmiş dizeler oluşturmak için ilişkilendirilmiş dizelerin nasıl kullanılacağı gösterilmektedir.

İlişkili dizelerin derlenmesi

C# 10 ve .NET 6'den başlayarak, derleyici ilişkilendirilmiş dizenin ilişkilendirilmiş dize işleyici desenini karşılayan bir türe atanıp atanmadığı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 stringsahip olduğunda, tarafından System.Runtime.CompilerServices.DefaultInterpolatedStringHandlerişlenir. Özel ilişkilendirilmiş dize işleyicisi örneği için Bkz . Özel dize ilişkilendirme işleyicisi yazma öğreticisi . İlişkili dize işleyicisi kullanımı, genellikle performans nedenleriyle gerekli olan gelişmiş bir senaryodur.

Not

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

C# 10'den önce, ilişkilendirilmiş bir dize türüne stringsahipse, genellikle bir String.Format yöntem çağrısına dönüştürülür. Çözümlenen davranışın birleştirmeye eşdeğer olup olmadığını derleyici ile String.Concat değiştirebilirString.Format.

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

C# dili 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:

Ayrıca bkz.