Interpolazione di stringhe tramite $

Il carattere $ identifica un valore letterale stringa come stringa interpolata. Una stringa interpolata è un valore letterale stringa che può contenere espressioni di interpolazione. Quando una stringa interpolata viene risolta in una stringa di risultato, il compilatore sostituisce gli elementi con espressioni di interpolazione con le rappresentazioni stringa dei risultati dell'espressione.

L'interpolazione di stringhe offre una sintassi più leggibile e pratica per formattare le stringhe. È più facile da leggere rispetto alla formattazione composita di stringhe. L'esempio seguente usa entrambe le funzionalità per produrre lo stesso output:

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.

A partire da C# 10, è possibile usare una stringa interpolata per inizializzare una stringa costante. È possibile farlo solo se tutte le espressioni di interpolazione all'interno della stringa interpolata sono anche stringhe costanti.

Struttura di una stringa interpolata

Per identificare un valore letterale stringa come stringa interpolata, anteporre a questa il simbolo $. Non è possibile avere spazi vuoti tra $ e " che avvia un valore letterale stringa.

La struttura di un elemento con un'espressione di interpolazione è la seguente:

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

Gli elementi tra parentesi quadre sono facoltativi. La tabella seguente descrive i singoli elementi:

L'esempio seguente usa i componenti di formattazione facoltativi descritti nella tabella precedente:

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

A partire da C# 11, è possibile usare nuove righe all'interno di un'espressione di interpolazione per rendere il codice dell'espressione più leggibile. Nell'esempio seguente viene illustrato come le nuove righe possano migliorare la leggibilità di un'espressione che include criteri di ricerca:

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",
    }
    }";

Valori letterali stringa non elaborati interpolati

A partire da C# 11, è possibile usare un valore letterale stringa non elaborata interpolata, come illustrato nell'esempio seguente:

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

Per incorporare i caratteri{ e } nella stringa di risultato, avviare un valore letterale stringa non elaborato interpolato con più caratteri $. Quando si esegue questa operazione, qualsiasi sequenza di caratteri { o } inferiore al numero di caratteri $ viene incorporata nella stringa di risultato. Per racchiudere qualsiasi espressione di interpolazione all'interno di tale stringa, è necessario usare lo stesso numero di parentesi graffe del numero di caratteri $, come illustrato nell'esempio seguente:

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}

Nell'esempio precedente un valore letterale stringa non elaborato interpolato inizia con due caratteri $. È necessario racchiudere ogni espressione di interpolazione tra parentesi graffe doppie, {{ e }}. Una singola parentesi graffa è incorporata in una stringa di risultato. Se è necessario incorporare caratteri { o } ripetuti in una stringa di risultato, usare un numero di caratteri $ più elevato per designare un valore letterale stringa non elaborato interpolato. Se il valore letterale stringa ha più parentesi graffe ripetute rispetto al numero di caratteri $, i caratteri { e } vengono raggruppati dall'interno all'esterno. Nell'esempio precedente il valore letterale The point {{{X}}, {{Y}}} interpreta {{X}} e {{Y}} come espressioni interpolate. Le parentesi { e } esterne sono incluse verbatim nella stringa di output.

Caratteri speciali

Per includere una parentesi graffa, "{" o "}", nel testo prodotto da una stringa interpolata, digitare due parentesi graffe, ovvero "{{" o "}}". Per altre informazioni, vedere la sezione Parentesi graffe di escape dell'articolo Formattazione composita.

Poiché i due punti (":") hanno un significato speciale in un elemento dell'espressione di interpolazione, per usare un operatore condizionale in un'espressione di interpolazione racchiudere l'espressione tra parentesi.

Nell'esempio seguente viene illustrato come includere una parentesi graffa in una stringa di risultato. Illustra anche come usare un operatore condizionale:

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.

Una stringa verbatim interpolata inizia con i caratteri $ e @. È possibile usare $ e @ in qualsiasi ordine: sia $@"..." che @$"..." sono stringhe verbatim interpolate valide. Per altre informazioni sulle stringhe verbatim, vedere gli articoli stringa e identificatore verbatim.

Formattazione specifica delle impostazioni cultura

Per impostazione predefinita, una stringa interpolata usa le impostazioni cultura correnti definite dalla proprietà CultureInfo.CurrentCulture per tutte le operazioni di formattazione.

Per risolvere una stringa interpolata in una stringa di risultato specifica delle impostazioni cultura, usare il metodo String.Create(IFormatProvider, DefaultInterpolatedStringHandler), disponibile a partire da .NET 6. L'esempio seguente illustra come eseguire questa operazione:

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.

In .NET 5 e versioni precedenti di .NET usare la conversione implicita di una stringa interpolata in un'istanza di FormattableString. È quindi possibile usare un metodo di FormattableString.ToString(IFormatProvider) istanza o un metodo FormattableString.Invariant statico per produrre una stringa di risultato specifica delle impostazioni cultura. L'esempio seguente illustra come eseguire questa operazione:

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.

Per altre informazioni sulla formattazione personalizzata, vedere la sezione Formattazione personalizzata con ICustomFormatter dell'articolo Tipi di formattazione in .NET.

Altre risorse

Se non si ha familiarità con l'interpolazione di stringhe, vedere l'esercitazione interattiva Interpolazione di stringhe in C#. È anche possibile controllare un'altra esercitazione sull’interpolazione di stringhe in C#. Questa esercitazione illustra come usare stringhe interpolate per produrre stringhe formattate.

Compilazione di stringhe interpolate

A partire da C# 10 e .NET 6, il compilatore controlla se una stringa interpolata viene assegnata a un tipo che soddisfa il modello del gestore di stringhe interpolato. Un gestore di stringhe interpolato è un tipo che converte la stringa interpolata in una stringa di risultato. Quando una stringa interpolata ha il tipo string, viene elaborata da System.Runtime.CompilerServices.DefaultInterpolatedStringHandler. Per l'esempio di un gestore di stringhe interpolato personalizzato, vedere l'esercitazione Scrivere un gestore di interpolazione di stringhe personalizzato. L'uso di un gestore di stringhe interpolato è uno scenario avanzato, in genere necessario per motivi di prestazioni.

Prima di C# 10, se una stringa interpolata ha il tipo string, in genere viene trasformata in una chiamata a un metodo String.Format. Il compilatore può sostituire String.Format con String.Concat se il comportamento analizzato è equivalente alla concatenazione.

Se una stringa interpolata dispone del tipo IFormattable o FormattableString, il compilatore genera una chiamata al metodo FormattableStringFactory.Create.

Specifiche del linguaggio C#

Per altre informazioni, vedere la sezione Espressioni di stringa interpolata della specifica del linguaggio C# e le nuove specifiche di funzionalità seguenti:

• C# 10 - Stringhe interpolate migliorate
• C# 11 - Valori letterali stringa non elaborati
• C# 11 - Nuove righe nelle interpolazioni di stringhe

Vedi anche

• Caratteri speciali di C#
• Stringhe
• Stringhe di formato numerico standard
• Formattazione composita
• String.Format
• Semplificare l'interpolazione (regola di stile IDE0071)
• Interpolazione di stringhe in C# 10 e .NET 6 (blog .NET)