Formattazione compositaComposite Formatting

La funzionalità di formattazione composta di .NET consente di usare come input un elenco di oggetti e una stringa di formato composto.The .NET composite formatting feature takes a list of objects and a composite format string as input. Una stringa di formato composto è costituita da testo fisso alternato a segnaposto indicizzati, denominati elementi di formato, che corrispondono agli oggetti dell'elenco.A composite format string consists of fixed text intermixed with indexed placeholders, called format items, that correspond to the objects in the list. L'operazione di formattazione produce una stringa risultato costituita dal testo fisso originale alternato alla rappresentazione di stringa degli oggetti dell'elenco.The formatting operation yields a result string that consists of the original fixed text intermixed with the string representation of the objects in the list.

Importante

Invece di usare le stringhe di formato composito, è possibile usare stringhe interpolate se il linguaggio e la versione del linguaggio in uso le supportano.Instead of using composite format strings, you can use interpolated strings if the language and language version that you're using support them. Una stringa interpolata è una stringa che contiene espressioni interpolate.An interpolated string is a string that contains interpolated expressions. Ogni espressione interpolata viene risolta con il valore dell'espressione e inclusa nella stringa di risultato al momento dell'assegnazione della stringa.Each interpolated expression is resolved with the expression's value and included in the result string when the string is assigned. Per altre informazioni, vedere Interpolazione di stringhe (Riferimenti per C#) e Stringhe interpolate (Riferimenti per Visual Basic).For more information, see String interpolation (C# Reference) and Interpolated strings (Visual Basic Reference).

La funzionalità di formattazione composita è supportata da metodi quali i seguenti:The composite formatting feature is supported by methods such as the following:

Stringa di formato compostoComposite Format String

Una stringa di formato composto e un elenco di oggetti vengono usati come argomenti di metodi che supportano la funzionalità di formattazione composta.A composite format string and object list are used as arguments of methods that support the composite formatting feature. Una stringa di formato composto è costituita da zero o più esecuzioni di testo fisso alternate a uno o più elementi di formato.A composite format string consists of zero or more runs of fixed text intermixed with one or more format items. Il testo fisso corrisponde a una stringa di propria scelta e ogni elemento di formato corrisponde a un oggetto o una struttura boxed dell'elenco.The fixed text is any string that you choose, and each format item corresponds to an object or boxed structure in the list. La funzionalità di formattazione composta restituisce una nuova stringa risultato in cui ciascun elemento di formato viene sostituito dalla rappresentazione di stringa di origine dell'oggetto corrispondente dell'elenco.The composite formatting feature returns a new result string where each format item is replaced by the string representation of the corresponding object in the list.

Si consideri il frammento di codice Format riportato di seguito.Consider the following Format code fragment.

string name = "Fred";
String.Format("Name = {0}, hours = {1:hh}", name, DateTime.Now);
Dim name As String = "Fred"
String.Format("Name = {0}, hours = {1:hh}", name, DateTime.Now)

Il testo corretto è "Name =" e ", hours =".The fixed text is "Name = " and ", hours = ". Gli elementi di formato sono "{0}", il cui indice è 0, che corrisponde all'elemento name dell'oggetto, e "{1:hh}", il cui indice è 1, che corrisponde all'elemento DateTime.Now dell'oggetto.The format items are "{0}", whose index is 0, which corresponds to the object name, and "{1:hh}", whose index is 1, which corresponds to the object DateTime.Now.

Sintassi degli elementi di formatoFormat Item Syntax

Ogni elemento di formato usa il formato seguente ed è costituito dai componenti riportati di seguito:Each format item takes the following form and consists of the following components:

{ index[,alignment][:formatString]}{ index[,alignment][:formatString]}

Le parentesi graffe corrispondenti "{" e "}" sono obbligatorie.The matching braces ("{" and "}") are required.

Componente di indiceIndex Component

Il componente obbligatorio index, denominato anche identificatore di parametro, corrisponde a un numero a partire da 0 che identifica un elemento corrispondente nell'elenco di oggetti.The mandatory index component, also called a parameter specifier, is a number starting from 0 that identifies a corresponding item in the list of objects. Con l'elemento di formato con identificatore di parametro 0 viene formattato il primo oggetto dell'elenco, con l'elemento di formato con identificatore di parametro 1 viene formattato il secondo oggetto dell'elenco e così via.That is, the format item whose parameter specifier is 0 formats the first object in the list, the format item whose parameter specifier is 1 formats the second object in the list, and so on. L'esempio seguente include quattro identificatori di parametro, numerati da zero a tre, per rappresentare i numeri primi inferiori a dieci:The following example includes four parameter specifiers, numbered zero through three, to represent prime numbers less than ten:

string primes;
primes = String.Format("Prime numbers less than 10: {0}, {1}, {2}, {3}",
                       2, 3, 5, 7 );
Console.WriteLine(primes);
// The example displays the following output:
//      Prime numbers less than 10: 2, 3, 5, 7
Dim primes As String
primes = String.Format("Prime numbers less than 10: {0}, {1}, {2}, {3}",
                       2, 3, 5, 7 )
Console.WriteLine(primes)
' The example displays the following output:
'      Prime numbers less than 10: 2, 3, 5, 7

Più elementi di formato possono fare riferimento allo stesso elemento dell'elenco di oggetti specificando lo stesso identificatore di parametro.Multiple format items can refer to the same element in the list of objects by specifying the same parameter specifier. È ad esempio possibile formattare lo stesso valore numerico in formato esadecimale, scientifico e numerico specificando una stringa di formato composto quale: "0x{0:X} {0:E} {0:N}", come nell'esempio riportato di seguito.For example, you can format the same numeric value in hexadecimal, scientific, and number format by specifying a composite format string such as : "0x{0:X} {0:E} {0:N}", as the following example shows.

string multiple = String.Format("0x{0:X} {0:E} {0:N}",
                                Int64.MaxValue);
Console.WriteLine(multiple);
// The example displays the following output:
//      0x7FFFFFFFFFFFFFFF 9.223372E+018 9,223,372,036,854,775,807.00
Dim multiple As String = String.Format("0x{0:X} {0:E} {0:N}",
                                       Int64.MaxValue)
Console.WriteLine(multiple)
' The example displays the following output:
'      0x7FFFFFFFFFFFFFFF 9.223372E+018 9,223,372,036,854,775,807.00

Ogni elemento di formato può fare riferimento a un oggetto dell'elenco.Each format item can refer to any object in the list. Se ad esempio sono presenti tre oggetti, è possibile formattare il secondo, il primo e il terzo oggetto specificando una stringa di formato composito come questa: "{1} {0} {2}".For example, if there are three objects, you can format the second, first, and third object by specifying a composite format string like this: "{1} {0} {2}". Gli oggetti a cui non fa riferimento un elemento di formato vengono ignorati.An object that is not referenced by a format item is ignored. Se un identificatore di parametro corrisponde a un elemento non incluso nei limiti dell'elenco di oggetti, verrà generata un'eccezione FormatException in fase di esecuzione.A FormatException is thrown at runtime if a parameter specifier designates an item outside the bounds of the list of objects.

Componente di allineamentoAlignment Component

Il componente facoltativo alignment corrisponde a un intero con segno che indica la larghezza preferita del campo formattato.The optional alignment component is a signed integer indicating the preferred formatted field width. Se il valore di alignment è inferiore alla lunghezza della stringa formattata, il componente alignment verrà ignorato e come larghezza del campo verrà usata la lunghezza della stringa.If the value of alignment is less than the length of the formatted string, alignment is ignored and the length of the formatted string is used as the field width. I dati formattati verranno allineati a destra se il valore di alignment è positivo e a sinistra se il valore di alignment è negativo.The formatted data in the field is right-aligned if alignment is positive and left-aligned if alignment is negative. Per la spaziatura eventualmente necessaria verranno usati spazi vuoti.If padding is necessary, white space is used. Se viene specificato il componente alignment, la virgola è obbligatoria.The comma is required if alignment is specified.

L'esempio seguente definisce due matrici, una contenente i nomi dei dipendenti e l'altra contenente il numero di ore in cui hanno lavorato per un periodo di due settimane.The following example defines two arrays, one containing the names of employees and the other containing the hours they worked over a two-week period. La stringa di formato composto allinea a sinistra i nomi in un campo di 20 caratteri e allinea a destra le ore in un campo di 5 caratteri.The composite format string left-aligns the names in a 20-character field, and right-aligns their hours in a 5-character field. Si noti che la stringa di formato standard "N1" viene usata anche per formattare le ore con una cifra frazionaria.Note that the "N1" standard format string is also used to format the hours with one fractional digit.

using System;

public class Example
{
   public static void Main()
   {
      string[] names = { "Adam", "Bridgette", "Carla", "Daniel",
                         "Ebenezer", "Francine", "George" };
      decimal[] hours = { 40, 6.667m, 40.39m, 82, 40.333m, 80,
                                 16.75m };

      Console.WriteLine("{0,-20} {1,5}\n", "Name", "Hours");
      for (int ctr = 0; ctr < names.Length; ctr++)
         Console.WriteLine("{0,-20} {1,5:N1}", names[ctr], hours[ctr]);

   }
}
// The example displays the following output:
//       Name                 Hours
//
//       Adam                  40.0
//       Bridgette              6.7
//       Carla                 40.4
//       Daniel                82.0
//       Ebenezer              40.3
//       Francine              80.0
//       George                16.8
Module Example
   Public Sub Main()
      Dim names() As String = { "Adam", "Bridgette", "Carla", "Daniel",
                                "Ebenezer", "Francine", "George" }
      Dim hours() As Decimal = { 40, 6.667d, 40.39d, 82, 40.333d, 80,
                                 16.75d }

      Console.WriteLine("{0,-20} {1,5}", "Name", "Hours")
      Console.WriteLine()
      For ctr As Integer = 0 To names.Length - 1
         Console.WriteLine("{0,-20} {1,5:N1}", names(ctr), hours(ctr))
      Next
   End Sub
End Module
' The example displays the following output:
'       Name                 Hours
'
'       Adam                  40.0
'       Bridgette              6.7
'       Carla                 40.4
'       Daniel                82.0
'       Ebenezer              40.3
'       Francine              80.0
'       George                16.8

Componente della stringa di formatoFormat String Component

Il componente formatString facoltativo è una stringa di formato appropriata per il tipo di oggetto formattato.The optional formatString component is a format string that is appropriate for the type of object being formatted. Specificare una stringa di formato numerico standard o personalizzata se l'oggetto corrispondente è un valore numerico, una stringa di formato di data e ora standard o personalizzata se l'oggetto corrispondente è un oggetto DateTime o una stringa di formato di enumerazione se l'oggetto corrispondente è un valore di enumerazione.Specify a standard or custom numeric format string if the corresponding object is a numeric value, a standard or custom date and time format string if the corresponding object is a DateTime object, or an enumeration format string if the corresponding object is an enumeration value. Se il componente formatString viene omesso, verrà usato l'identificatore di formato generale "G" per un tipo numerico, di data e ora o di enumerazione.If formatString is not specified, the general ("G") format specifier for a numeric, date and time, or enumeration type is used. Se viene specificato il componente formatString, i due punti sono obbligatori.The colon is required if formatString is specified.

Nella tabella seguente sono elencati i tipi o le categorie di tipi della libreria di classi .NET Framework che supportano un set predefinito di stringhe di formato e vengono forniti collegamenti ad argomenti in cui vengono elencate le stringhe di formato supportate.The following table lists types or categories of types in the .NET Framework class library that support a predefined set of format strings, and provides links to the topics that list the supported format strings. Si noti che la formattazione delle stringhe è un meccanismo estendibile che consente di definire nuove stringhe di formato per tutti i tipi esistenti nonché definire un set di stringhe di formato supportate da un tipo definito dall'applicazione.Note that string formatting is an extensible mechanism that makes it possible to define new format strings for all existing types as well as to define a set of format strings supported by an application-defined type. Per altre informazioni, vedere gli argomenti delle interfacce IFormattable e ICustomFormatter.For more information, see the IFormattable and ICustomFormatter interface topics.

Tipo o categoria di tipoType or type category VedereSee
Tipi di data e ora (DateTime, DateTimeOffset)Date and time types (DateTime, DateTimeOffset) Stringhe di formato di data e ora standardStandard Date and Time Format Strings

Custom Date and Time Format StringsCustom Date and Time Format Strings
Tipi di enumerazione (tutti derivati da System.Enum)Enumeration types (all types derived from System.Enum) Enumeration Format StringsEnumeration Format Strings
Tipi numerici (BigInteger, Byte, Decimal, Double, Int16, Int32, Int64, SByte, Single, UInt16, UInt32, UInt64)Numeric types (BigInteger, Byte, Decimal, Double, Int16, Int32, Int64, SByte, Single, UInt16, UInt32, UInt64) Standard Numeric Format StringsStandard Numeric Format Strings

Custom Numeric Format StringsCustom Numeric Format Strings
Guid Guid.ToString(String)
TimeSpan Stringhe di formato TimeSpan standardStandard TimeSpan Format Strings

Stringhe di formato TimeSpan personalizzateCustom TimeSpan Format Strings

Sequenze di escape delle parentesi graffeEscaping Braces

Le parentesi graffe di apertura e di chiusura sono interpretate come l'inizio e la fine di un elemento di formato.Opening and closing braces are interpreted as starting and ending a format item. Di conseguenza, è necessario usare una sequenza di escape per visualizzare una parentesi graffa di apertura o di chiusura letterale.Consequently, you must use an escape sequence to display a literal opening brace or closing brace. Specificare due parentesi graffe di apertura ("{{") nel testo fisso per visualizzare una parentesi di apertura ("{") oppure due parentesi graffe di chiusura ("}}") per visualizzare una parentesi graffa di chiusura ("}").Specify two opening braces ("{{") in the fixed text to display one opening brace ("{"), or two closing braces ("}}") to display one closing brace ("}"). Le parentesi graffe in un elemento di formato vengono interpretate sequenzialmente nell'ordine in cui sono rilevate.Braces in a format item are interpreted sequentially in the order they are encountered. L'interpretazione delle parentesi graffe annidate non è supportata.Interpreting nested braces is not supported.

Il tipo di interpretazione delle parentesi graffe in sequenza di escape può produrre risultati imprevisti.The way escaped braces are interpreted can lead to unexpected results. Si consideri, ad esempio, l'elemento di formato "{{{0:D}}}", destinato alla visualizzazione di una parentesi graffa di apertura, un valore numerico formattato come numero decimale e una parentesi graffa di chiusura.For example, consider the format item "{{{0:D}}}", which is intended to display an opening brace, a numeric value formatted as a decimal number, and a closing brace. L'elemento di formato viene tuttavia interpretato nel modo seguente:However, the format item is actually interpreted in the following manner:

  1. Le prime due parentesi apertura ("{{") presentano una sequenza di escape e producono una parentesi graffa di apertura.The first two opening braces ("{{") are escaped and yield one opening brace.

  2. I tre caratteri successivi ("{0:") sono interpretati come l'inizio di un elemento di formato.The next three characters ("{0:") are interpreted as the start of a format item.

  3. Il carattere successivo ("D") verrebbe interpretato come identificatore del formato numerico standard Decimal, ma le due parentesi graffe successive con sequenza di escape ("}}") producono una parentesi graffa singola.The next character ("D") would be interpreted as the Decimal standard numeric format specifier, but the next two escaped braces ("}}") yield a single brace. Poiché la stringa risultante ("D}") non è un identificatore di un formato numerico standard, viene interpretata come una stringa di formato personalizzata che indica la visualizzazione della stringa letterale "D}".Because the resulting string ("D}") is not a standard numeric format specifier, the resulting string is interpreted as a custom format string that means display the literal string "D}".

  4. L'ultima parentesi graffa ("}") viene interpretata come la fine dell'elemento di formato.The last brace ("}") is interpreted as the end of the format item.

  5. Il risultato finale visualizzato è la stringa letterale "{D}".The final result that is displayed is the literal string, "{D}". Il valore numerico da formattare non viene visualizzato.The numeric value that was to be formatted is not displayed.

Per evitare di interpretare in modo errato gli elementi di formato e le parentesi graffe con sequenza di escape, è preferibile formattarli separatamente, ovveroOne way to write your code to avoid misinterpreting escaped braces and format items is to format the braces and format item separately. nella prima operazione di formattazione visualizzare una parentesi graffa di apertura letterale, nella successiva operazione visualizzare il risultato dell'elemento di formato, quindi nell'ultima operazione visualizzare una parentesi graffa di chiusura letterale.That is, in the first format operation display a literal opening brace, in the next operation display the result of the format item, then in the final operation display a literal closing brace. Questo approccio viene illustrato nell'esempio seguente:The following example illustrates this approach.

int value = 6324;
string output = string.Format("{0}{1:D}{2}", 
                             "{", value, "}");
Console.WriteLine(output);
// The example displays the following output:
//       {6324}                            
Dim value As Integer = 6324
Dim output As String = String.Format("{0}{1:D}{2}", _
                                     "{", value, "}")
Console.WriteLine(output)   
' The example displays the following output:
'       {6324}

Ordine di elaborazioneProcessing Order

Se la chiamata al metodo di formattazione composita include un argomento IFormatProvider il cui valore non è null, il runtime chiama il metodo IFormatProvider.GetFormat per richiedere un'implementazione di ICustomFormatter.If the call to the composite formatting method includes an IFormatProvider argument whose value is not null, the runtime calls its IFormatProvider.GetFormat method to request an ICustomFormatter implementation. Se il metodo è in grado di restituire un'implementazione ICustomFormatter, viene memorizzata nella cache per la durata della chiamata del metodo di formattazione composita.If the method is able to return an ICustomFormatter implementation, it's cached for the duration of the call of the composite formatting method.

Ogni valore nell'elenco di parametri che corrisponde a un elemento di formato viene convertito in una stringa, nel modo seguente:Each value in the parameter list that corresponds to a format item is converted to a string as follows:

  1. Se il valore da formattare è null, viene restituita una stringa vuota String.Empty.If the value to be formatted is null, an empty string String.Empty is returned.

  2. Se l'implementazione di ICustomFormatter è disponibile, il runtime chiama il metodo Format.If an ICustomFormatter implementation is available, the runtime calls its Format method. Passa al metodo il valore formatString dell'elemento di formato, se disponibile, o null in caso contrario, con l'implementazione di IFormatProvider.It passes the method the format item's formatString value, if one is present, or null if it's not, along with the IFormatProvider implementation. Se la chiamata al metodo ICustomFormatter.Format restituisce null, l'esecuzione procede al passaggio successivo; in caso contrario, viene restituito il risultato della chiamata ICustomFormatter.Format.If the call to the ICustomFormatter.Format method returns null, execution proceeds to the next step; otherwise, the result of the ICustomFormatter.Format call is returned.

  3. Se il valore implementa l'interfaccia IFormattable, verrà chiamato il relativo metodo ToString(String, IFormatProvider).If the value implements the IFormattable interface, the interface's ToString(String, IFormatProvider) method is called. Al metodo viene passato il valore formatString, se disponibile nell'elemento di formato, o null in caso contrario.The method is passed the formatString value, if one is present in the format item, or null if it's not. L'argomento IFormatProvider è determinato come segue:The IFormatProvider argument is determined as follows:

  4. Viene chiamato il metodo senza parametri ToString del tipo, che esegue l'override di Object.ToString() o eredita il comportamento della relativa classe di base.The type's parameterless ToString method, which either overrides Object.ToString() or inherits the behavior of its base class, is called. In questo caso la stringa di formato specificata dal componente formatString nell'elemento di formato, se presente, viene ignorata.In this case, the format string specified by the formatString component in the format item, if it's present, is ignored.

L'allineamento viene applicato al termine dei precedenti passaggi.Alignment is applied after the preceding steps have been performed.

Esempi di codiceCode Examples

Nell'esempio seguente vengono illustrate una stringa creata con la formattazione composita e un'altra creata mediante il metodo ToString di un oggetto.The following example shows one string created using composite formatting and another created using an object's ToString method. Entrambi i tipi di formattazione producono risultati equivalenti.Both types of formatting produce equivalent results.

string FormatString1 = String.Format("{0:dddd MMMM}", DateTime.Now);
string FormatString2 = DateTime.Now.ToString("dddd MMMM");
Dim FormatString1 As String = String.Format("{0:dddd MMMM}", DateTime.Now)
Dim FormatString2 As String = DateTime.Now.ToString("dddd MMMM") 

Presupponendo che il giorno corrente sia un giovedì di maggio, il valore di entrambe le stringhe dell'esempio precedente sarà Thursday May se sono specificate le impostazioni cultura inglesi.Assuming that the current day is a Thursday in May, the value of both strings in the preceding example is Thursday May in the U.S. English culture.

Console.WriteLine espone la stessa funzionalità di String.Format.Console.WriteLine exposes the same functionality as String.Format. L'unica differenza tra i due metodi è che String.Format restituisce il risultato come stringa, mentre Console.WriteLine scrive il risultato nel flusso di output associato all'oggetto Console.The only difference between the two methods is that String.Format returns its result as a string, while Console.WriteLine writes the result to the output stream associated with the Console object. Nell'esempio seguente viene usato il metodo Console.WriteLine per formattare il valore di MyInt come valore di valuta.The following example uses the Console.WriteLine method to format the value of MyInt to a currency value.

int MyInt = 100;
Console.WriteLine("{0:C}", MyInt);
// The example displays the following output 
// if en-US is the current culture:
//        $100.00
Dim MyInt As Integer = 100
Console.WriteLine("{0:C}", MyInt)
' The example displays the following output
' if en-US is the current culture:
'        $100.00

Nell'esempio riportato di seguito vengono illustrate la formattazione di più oggetti e la formattazione di un oggetto in due diversi modi.The following example demonstrates formatting multiple objects, including formatting one object two different ways.

string myName = "Fred";
Console.WriteLine(String.Format("Name = {0}, hours = {1:hh}, minutes = {1:mm}",
      myName, DateTime.Now));
// Depending on the current time, the example displays output like the following:
//    Name = Fred, hours = 11, minutes = 30                 
Dim myName As String = "Fred"
Console.WriteLine(String.Format("Name = {0}, hours = {1:hh}, minutes = {1:mm}", _
                  myName, DateTime.Now))
' Depending on the current time, the example displays output like the following:
'    Name = Fred, hours = 11, minutes = 30                 

Nell'esempio seguente viene illustrato l'utilizzo dell'allineamento nella formattazione.The following example demonstrates the use of alignment in formatting. Gli argomenti formattati sono inseriti tra barre verticali (|) per evidenziare l'allineamento ottenuto.The arguments that are formatted are placed between vertical bar characters (|) to highlight the resulting alignment.

string myFName = "Fred";
string myLName = "Opals";
int myInt = 100;
string FormatFName = String.Format("First Name = |{0,10}|", myFName);
string FormatLName = String.Format("Last Name = |{0,10}|", myLName);
string FormatPrice = String.Format("Price = |{0,10:C}|", myInt); 
Console.WriteLine(FormatFName);
Console.WriteLine(FormatLName);
Console.WriteLine(FormatPrice);
Console.WriteLine();

FormatFName = String.Format("First Name = |{0,-10}|", myFName);
FormatLName = String.Format("Last Name = |{0,-10}|", myLName);
FormatPrice = String.Format("Price = |{0,-10:C}|", myInt);
Console.WriteLine(FormatFName);
Console.WriteLine(FormatLName);
Console.WriteLine(FormatPrice);
// The example displays the following output on a system whose current
// culture is en-US:
//          First Name = |      Fred|
//          Last Name = |     Opals|
//          Price = |   $100.00|
//
//          First Name = |Fred      |
//          Last Name = |Opals     |
//          Price = |$100.00   |
   Dim myFName As String = "Fred"
   Dim myLName As String = "Opals"

   Dim myInt As Integer = 100
   Dim FormatFName As String = String.Format("First Name = |{0,10}|", myFName)
   Dim FormatLName As String = String.Format("Last Name = |{0,10}|", myLName)
   Dim FormatPrice As String = String.Format("Price = |{0,10:C}|", myInt)
   Console.WriteLine(FormatFName)
   Console.WriteLine(FormatLName)
   Console.WriteLine(FormatPrice)
   Console.WriteLine()
   
   FormatFName = String.Format("First Name = |{0,-10}|", myFName)
   FormatLName = String.Format("Last Name = |{0,-10}|", myLName)
   FormatPrice = String.Format("Price = |{0,-10:C}|", myInt)
   Console.WriteLine(FormatFName)
   Console.WriteLine(FormatLName)
   Console.WriteLine(FormatPrice)
   ' The example displays the following output on a system whose current
   ' culture is en-US:
   '          First Name = |      Fred|
   '          Last Name = |     Opals|
   '          Price = |   $100.00|
   '
   '          First Name = |Fred      |
   '          Last Name = |Opals     |
   '          Price = |$100.00   |

Vedere ancheSee also