Interpolazione di stringhe tramite $

Il carattere $ identifica un valore letterale stringa come stringa interpolata. Una stringa interpolata è un letterale di 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.

È 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>[,<width>][:<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",
    }
    }";

Stringhe letterali grezze interpolate

A partire da C# 11, è possibile usare una stringa letterale grezza interpolata, come mostrato 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 una stringa letterale interpolata non elaborata usando 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 per il numero di caratteri rappresentati da $, 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, una stringa letterale interpolata grezza 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 risultante, usare un numero di caratteri $ più elevato per designare un letterale di stringa grezza interpolato. Se la stringa letterale ha più parentesi graffe ripetute rispetto al numero di caratteri $, i caratteri { e } sono raggruppati dall'interno verso l'esterno. Nell'esempio precedente il valore letterale The point {{{X}}, {{Y}}} interpreta {{X}} e {{Y}} come espressioni interpolate. Gli elementi esterni { e } sono inclusi testualmente 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 alla cultura

Per impostazione predefinita, una stringa interpolata usa la cultura corrente definita dalla proprietà CultureInfo.CurrentCulture per tutte le operazioni di formattazione.

Per risolvere una stringa interpolata in una stringa di risultato specifica della cultura locale, 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 nelle versioni precedenti di .NET, si utilizza la conversione implicita di una stringa interpolata in un'istanza di FormattableString. È quindi possibile usare un metodo di istanza FormattableString.ToString(IFormatProvider) o un metodo statico FormattableString.Invariant per produrre una stringa del risultato specifica della 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#. Questa esercitazione illustra come usare stringhe interpolate per produrre stringhe formattate.

Compilazione di stringhe interpolate

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.

Se una stringa interpolata ha il tipo string, viene in genere trasformata in una chiamata al 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:

• Stringhe interpolate migliorate
• C# 11 - Stringhe letterali grezze
• 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)