Kombinierte Formatierung

Das Zusammengesetztformatierungsfeature .NET verwendet eine Liste von Objekten und eine zusammengesetzte Formatzeichenfolge als Eingabe. Eine zusammengesetzte Formatzeichenfolge besteht aus festem Text, der mit indizierten Platzhaltern kombiniert wird, die als Formatelemente bezeichnet werden. die den Objekten in der Liste entsprechen. Der Formatierungsvorgang liefert eine Ergebniszeichenfolge, die sich aus dem ursprünglichen festgelegten Text und der Zeichenfolgendarstellung der Objekte in der Liste zusammensetzt.

Die folgenden Methoden unterstützen die zusammengesetzte Formatierungsfunktion:

• String.Format, der eine formatierte Ergebniszeichenfolge zurückgibt.
• StringBuilder.AppendFormat, das eine formatierte Ergebniszeichenfolge an ein StringBuilder Objekt anfügt.
• Einige Überladungen der Console.WriteLine Methode, die eine formatierte Ergebniszeichenfolge für die Konsole anzeigen.
• Einige Überladungen der TextWriter.WriteLine Methode, die die formatierte Ergebniszeichenfolge in einen Datenstrom oder eine Datei schreiben. Die Klassen, die von TextWriter abgeleitet sind, wie z. B. StreamWriter und HtmlTextWriter, teilen diese Funktionalität ebenfalls.
• Debug.WriteLine(String, Object[]), die eine formatierte Meldung an Ablaufverfolgungslistener ausgibt.
• Die Methoden Trace.TraceError(String, Object[]), Trace.TraceInformation(String, Object[]) und Trace.TraceWarning(String, Object[]), die formatierte Meldungen an Ablaufverfolgungslistener ausgeben.
• Die TraceSource.TraceInformation(String, Object[])-Methode, die eine Informationsmethode in Ablaufverfolgungslistener schreibt.

Kombinierte Formatzeichenfolge

Eine zusammengesetzte Formatzeichenfolge und Objektliste werden als Argumente von Methoden verwendet, die das zusammengesetzte Formatierungsfeature unterstützen. Eine zusammengesetzte Formatzeichenfolge besteht aus null oder mehr Abschnitten aus festem Text, die mit einem oder mehreren Formatelementen vermischt sind. Der feste Text ist eine beliebige Zeichenfolge, und jedes Formatelement entspricht einem Objekt oder einer boxierten Struktur in der Liste. Die Zeichenfolgendarstellung jedes Objekts ersetzt das entsprechende Formatelement.

Betrachten Sie das folgende Format Codefragment:

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

String.Format("Name = {0}, hours = {1:hh}", "Fred", DateTime.Now)

Der feste Text ist Name = und , hours = . Die Formatelemente sind {0}, deren Index 0 dem Objekt nameentspricht und {1:hh}deren Index von 1 dem Objekt DateTime.Nowentspricht.

Formatelementsyntax

Alle Formatelemente weisen die folgende Form auf und bestehen aus folgenden Komponenten:

{index[,width][:formatString]}

Die übereinstimmenden geschweiften Klammern ({ und }) sind erforderlich.

Indexkomponente

Die obligatorische index Komponente, die auch als Parameterbezeichner bezeichnet wird, ist eine Zahl beginnend mit 0, die ein entsprechendes Element in der Liste der Objekte identifiziert. Das bedeutet, dass das Formatelement, dessen Parameterbezeichner 0 ist, das erste Objekt in der Liste formatiert. Das Formatelement, dessen Parameterbezeichner 1 das zweite Objekt in der Liste formatiert, und so weiter. Das folgende Beispiel enthält vier Parameterbezeichner, nummeriert null bis drei, um Primzahlen unter 10 darzustellen:

string primes = string.Format("Four prime numbers: {0}, {1}, {2}, {3}",
                              2, 3, 5, 7);
Console.WriteLine(primes);

// The example displays the following output:
//      Four prime numbers: 2, 3, 5, 7

Dim primes As String = String.Format("Four prime numbers: {0}, {1}, {2}, {3}",
                                      2, 3, 5, 7)
Console.WriteLine(primes)

'The example displays the following output
'     Four prime numbers 2, 3, 5, 7

Mehrere Formatelemente können auf dasselbe Element in der Liste der Objekte verweisen, indem sie denselben Parameterbezeichner angeben. Sie können beispielsweise denselben numerischen Wert im Hexadezimal-, wissenschaftlichen und Zahlenformat formatieren, indem Sie eine zusammengesetzte Formatzeichenfolge wie das "0x{0:X} {0:E} {0:N}"folgende Beispiel angeben:

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

Jedes Formatelement kann auf jedes Objekt in der Liste verweisen. Wenn beispielsweise drei Objekte vorhanden sind, können Sie das zweite, erste und dritte Objekt formatieren, indem Sie eine zusammengesetzte Formatzeichenfolge wie {1} {0} {2} angeben, z. B. . Ein Objekt, auf das nicht von einem Formatelement verwiesen wird, wird ignoriert. Ein FormatException Fehler wird zur Laufzeit ausgelöst, wenn ein Parameterbezeichner ein Element außerhalb der Grenzen der Liste der Objekte angibt.

Breiten-Element

Die optionale width Komponente ist eine signierte ganze Zahl, die die bevorzugte formatierte Feldbreite angibt. Wenn der Wert width kleiner als die Länge der formatierten Zeichenfolge ist, width wird ignoriert, und die Länge der formatierten Zeichenfolge wird als Feldbreite verwendet. Die formatierten Daten im Feld sind rechtsbündig, wenn width positiv ist, und linksbündig, wenn width negativ ist. Wenn Füllzeichen erforderlich sind, werden Leerräume verwendet. Das Komma ist erforderlich, wenn width angegeben wird.

Im folgenden Beispiel werden zwei Arrays definiert, die die Namen der Mitarbeiter und die andere mit den Stunden enthalten, die sie über zwei Wochen gearbeitet haben. Die kombinierte Formatzeichenfolge richtet die Namen in einem Feld mit 20 Zeichen linksbündig aus, und die Stunden werden in einem Feld mit 5 Zeichen rechtsbündig ausgerichtet. Die Standardformatzeichenfolge "N1" formatiert die Stunden mit einer Bruchzahl.

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 counter = 0; counter < names.Length; counter++)
    Console.WriteLine("{0,-20} {1,5:N1}", names[counter], hours[counter]);

// 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

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}\n", "Name", "Hours")

For counter = 0 To names.Length - 1
    Console.WriteLine("{0,-20} {1,5:N1}", names(counter), hours(counter))
Next

'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

Formatzeichenfolgenkomponente

Die optionale formatString Komponente ist eine Formatzeichenfolge, die für den Typ des zu formatierenden Objekts geeignet ist. Sie können Folgendes angeben:

• Eine standard- oder benutzerdefinierte numerische Formatzeichenfolge, wenn das entsprechende Objekt ein numerischer Wert ist.
• Eine standard- oder benutzerdefinierte Datums- und Uhrzeitformatzeichenfolge, wenn das entsprechende Objekt ein DateTime Objekt ist.
• Eine Enumerationsformatzeichenfolge , wenn das entsprechende Objekt ein Enumerationswert ist.

Wenn formatString nicht angegeben, wird der allgemeine Formatbezeichner ("G") für einen numerischen, Datums- und Uhrzeit- oder Enumerationstyp verwendet. Der Doppelpunkt ist erforderlich, wenn formatString angegeben wird.

In der folgenden Tabelle werden Typen oder Kategorien von Typen in der .NET-Klassenbibliothek aufgeführt, die einen vordefinierten Satz von Formatzeichenfolgen unterstützen, und Links zu den Artikeln bereitgestellt, die die unterstützten Formatzeichenfolgen auflisten. Die Zeichenfolgenformatierung ist ein erweiterbarer Mechanismus, der es ermöglicht, neue Formatzeichenfolgen für alle vorhandenen Typen zu definieren und einen Satz von Formatzeichenfolgen zu definieren, die von einem anwendungsdefinierten Typ unterstützt werden.

Weitere Informationen finden Sie in den IFormattable und ICustomFormatter Schnittstellenartikeln.

Versehen von geschweiften Klammern mit Escapezeichen

Öffnende und schließende geschweifte Klammern werden als Beginn und Ende eines Formatelements interpretiert. Um eine literale öffnende bzw. schließende geschweifte Klammer anzuzeigen, müssen Sie eine Escapesequenz verwenden. Geben Sie zwei öffnende geschweifte Klammern ({{) im festen Text an, um eine öffnende Klammer ({) anzuzeigen, oder geben Sie zwei schließende geschweifte Klammern (}}) an, um eine schließende Klammer (}) anzuzeigen.

Escapeklammern mit einem Formatelement werden zwischen .NET und .NET Framework unterschiedlich analysiert.

.NETTO

Geschweifte Klammern können um ein Formatelement herum mit Escapezeichen versehen werden. Betrachten Sie beispielsweise das Formatelement {{{0:D}}}, das eine öffnende geschweifte Klammer anzeigen soll, einen numerischen Wert, der als Dezimalzahl formatiert ist, und eine schließende geschweifte Klammer. Das Formatelement wird wie folgt interpretiert:

1. Die ersten beiden öffnenden geschweiften Klammern ({{) werden mit Escapezeichen versehen und ergeben eine öffnende geschweifte Klammer.
2. Die nächsten drei Zeichen ({0:) werden als Anfang eines Formatelements interpretiert.
3. Das nächste Zeichen (D) wird als numerischer Dezimalformatbezeichner interpretiert.
4. Die nächste geschweifte Klammer (}) wird als Ende des Formatelements interpretiert.
5. Die letzten beiden schließenden geschweiften Klammern werden mit Escapezeichen versehen und ergeben eine schließende geschweifte Klammer.
6. Das endgültige Ergebnis, das angezeigt wird, ist die Literalzeichenfolge. {6324}

int value = 6324;
string output = string.Format("{{{0:D}}}", value);

Console.WriteLine(output);
// The example displays the following output:
//       {6324}

Dim value As Integer = 6324
Dim output As String = String.Format("{{{0:D}}}", value)

Console.WriteLine(output)

'The example displays the following output
'      {6324}

.NET Framework (Englisch)

Geschweifte Klammern in einem Formatelement werden sequenziell in der Reihenfolge interpretiert, in der sie gefunden werden. Die Interpretation geschachtelter geschweifter Klammern wird nicht unterstützt.

Die Art und Weise, wie geschweifte Klammern mit Escapezeichen interpretiert werden, kann zu unerwarteten Ergebnissen führen. Betrachten Sie beispielsweise das Formatelement {{{0:D}}}, das eine öffnende geschweifte Klammer anzeigen soll, einen numerischen Wert, der als Dezimalzahl formatiert ist, und eine schließende geschweifte Klammer. Das Formatelement wird jedoch wie folgt interpretiert:

1. Die ersten beiden öffnenden geschweiften Klammern ({{) werden mit Escapezeichen versehen und ergeben eine öffnende geschweifte Klammer.
2. Die nächsten drei Zeichen ({0:) werden als Anfang eines Formatelements interpretiert.
3. Das nächste Zeichen (D) wird als Formatbezeichner für das numerische Standarddezimalformat interpretiert, und die nächsten beiden geschweiften Klammern mit Escapezeichen (}}) ergeben eine einzelne geschweifte Klammer. Da die resultierende Zeichenfolge (D}) kein standardmäßiger numerischer Formatbezeichner ist, wird die resultierende Zeichenfolge als benutzerdefinierte Formatzeichenfolge interpretiert, die bedeutet, dass die Literalzeichenfolge D}angezeigt wird.
4. Die letzte geschweifte Klammer (}) wird als Ende des Formatelements interpretiert.
5. Das endgültige Ergebnis, das angezeigt wird, ist die Literalzeichenfolge. {D} Der numerische Wert, der formatiert werden soll, wird nicht angezeigt.

int value = 6324;
string output = string.Format("{{{0:D}}}",
                              value);
Console.WriteLine(output);

// The example displays the following output:
//       {D}

Dim value As Integer = 6324
Dim output As String = String.Format("{{{0:D}}}",
                                     value)
Console.WriteLine(output)

'The example displays the following output:
'      {D}

Eine Möglichkeit, Code zu schreiben und dabei Probleme mit falsch interpretierten geschweiften Klammern und Formatelementen zu vermeiden, ist die separate Formatierung der geschweiften Klammern und Formatelemente. Zeigen Sie daher im ersten Formatvorgang eine literale öffnende geschweifte Klammer, im nächsten Formatierungsvorgang das Ergebnis des Formatelements und letzten Formatierungsvorgang eine literale schließende geschweifte Klammer an. Das folgende Beispiel veranschaulicht diesen Ansatz:

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}

Verarbeitungsreihenfolge

Wenn der Aufruf der zusammengesetzten Formatierungsmethode ein IFormatProvider Argument enthält, dessen Wert nicht nullangegeben ist, ruft die Laufzeit die IFormatProvider.GetFormat Methode auf, um eine ICustomFormatter Implementierung anzufordern. Wenn die Methode eine ICustomFormatter Implementierung zurückgeben kann, wird sie während des Aufrufs der zusammengesetzten Formatierungsmethode zwischengespeichert.

Jeder Wert in der Parameterliste, der einem Formatelement entspricht, wird wie folgt in eine Zeichenfolge konvertiert:

1. Wenn der Wert, der formatiert werden soll, null ist, wird eine leere Zeichenfolge String.Empty zurückgegeben.

2. Wenn eine ICustomFormatter Implementierung verfügbar ist, ruft die Laufzeit die Format Methode auf. Die Laufzeit übergibt den Wert des Formatelements formatString (oder null wenn es nicht vorhanden ist) an die Methode. Außerdem übergibt die Runtime die IFormatProvider-Implementierung an die Methode. Wenn der Aufruf der ICustomFormatter.Format-Methode null ergibt, wird die Ausführung im nächsten Schritt weitergeführt. Andernfalls wird das Ergebnis des ICustomFormatter.Format Anrufs zurückgegeben.

3. Wenn der Wert die IFormattable Schnittstelle implementiert, wird die Methode der Schnittstelle ToString(String, IFormatProvider) aufgerufen. Wenn eines im Formatelement vorhanden ist, wird der formatString-Wert an die Methode übergeben. Ist dies nicht der Fall, wird null übergeben. Das IFormatProvider Argument wird wie folgt bestimmt:

   • Wenn für einen numerischen Wert eine zusammengesetzte Formatierungsmethode mit einem Argument ohne Null IFormatProvider aufgerufen wird, fordert die Laufzeit ein NumberFormatInfo Objekt aus seiner IFormatProvider.GetFormat Methode an. Falls dies nicht möglich ist, wenn der Wert des Arguments null ist oder wenn die Verbundformatierungsmethode keinen IFormatProvider Parameter hat, wird das NumberFormatInfo Objekt für die aktuelle Kultur verwendet.

   • Wenn für einen Datums- und Uhrzeitwert eine zusammengesetzte Formatierungsmethode mit einem Argument ohne Null IFormatProvider aufgerufen wird, fordert die Laufzeit ein DateTimeFormatInfo Objekt aus seiner IFormatProvider.GetFormat Methode an. In den folgenden Situationen wird stattdessen das DateTimeFormatInfo Objekt für die aktuelle Kultur verwendet:

     • Die IFormatProvider.GetFormat Methode kann kein DateTimeFormatInfo Objekt bereitstellen.
     • Der Wert des Arguments lautet null.
     • Die zusammengesetzte Formatierungsmethode verfügt nicht über einen IFormatProvider Parameter.

   • Bei Objekten anderer Typen wird der Wert direkt an die IFormatProvider Implementierung übergeben, wenn eine zusammengesetzte Formatierungsmethode mit einem IFormattable.ToString Argument aufgerufen wird. Andernfalls wird null der IFormattable.ToString-Implementierung übergeben.

4. Die parameterlose ToString Methode des Typs, die entweder das Verhalten der Basisklasse überschreibt Object.ToString() oder erbt, wird aufgerufen. In diesem Fall wird die von der formatString Komponente im Formatelement angegebene Formatzeichenfolge ignoriert, falls vorhanden.

Die Ausrichtung wird angewendet, nachdem die vorhergehenden Schritte durchgeführt wurden.

Code-Beispiele

Das folgende Beispiel zeigt eine Zeichenfolge, die mit zusammengesetzter Formatierung und einer anderen Zeichenfolge erstellt wurde, die mit der Methode eines Objekts ToString erstellt wurde. Beide Formatierungstypen erzeugen gleichwertige Ergebnisse.

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")

Wenn das aktuelle Datum ein Donnerstag im Mai ist, lautet der Wert beider Zeichenfolgen im vorherigen Beispiel Thursday May in der Kultur Englisch (USA).

Console.WriteLine bietet die gleiche Funktionalität wie String.Format. Der einzige Unterschied zwischen den beiden Methoden besteht darin, dass String.Format das Ergebnis als Zeichenfolge zurückgegeben wird, während Console.WriteLine das Ergebnis in den Ausgabedatenstrom geschrieben wird, der dem Console Objekt zugeordnet ist. Im folgenden Beispiel wird der Wert von Console.WriteLine mit der myNumber-Methode als Währungswert formatiert:

int myNumber = 100;
Console.WriteLine($"{myNumber:C}");

// The example displays the following output
// if en-US is the current culture:
//        $100.00

Dim myNumber As Integer = 100
Console.WriteLine("{0:C}", myNumber)

'The example displays the following output
'if en-US Is the current culture:
'       $100.00

Das folgende Beispiel veranschaulicht das Formatieren mehrerer Objekte, einschließlich der Formatierung eines Objekts auf zwei verschiedene Arten:

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

Im folgenden Beispiel wird die Verwendung der Breite in der Formatierung veranschaulicht. Die formatierten Argumente werden zwischen vertikalen Balkenzeichen (|) platziert, um die resultierende Ausrichtung hervorzuheben.

string firstName = "Fred";
string lastName = "Opals";
int myNumber = 100;

string formatFirstName = string.Format("First Name = |{0,10}|", firstName);
string formatLastName = string.Format("Last Name =  |{0,10}|", lastName);
string formatPrice = string.Format("Price =      |{0,10:C}|", myNumber);
Console.WriteLine(formatFirstName);
Console.WriteLine(formatLastName);
Console.WriteLine(formatPrice);
Console.WriteLine();

formatFirstName = string.Format("First Name = |{0,-10}|", firstName);
formatLastName = string.Format("Last Name =  |{0,-10}|", lastName);
formatPrice = string.Format("Price =      |{0,-10:C}|", myNumber);
Console.WriteLine(formatFirstName);
Console.WriteLine(formatLastName);
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 firstName As String = "Fred"
Dim lastName As String = "Opals"
Dim myNumber As Integer = 100

Dim formatFirstName As String = String.Format("First Name = |{0,10}|", firstName)
Dim formatLastName As String = String.Format("Last Name =  |{0,10}|", lastName)
Dim formatPrice As String = String.Format("Price =      |{0,10:C}|", myNumber)
Console.WriteLine(formatFirstName)
Console.WriteLine(formatLastName)
Console.WriteLine(formatPrice)
Console.WriteLine()

formatFirstName = String.Format("First Name = |{0,-10}|", firstName)
formatLastName = String.Format("Last Name =  |{0,-10}|", lastName)
formatPrice = String.Format("Price =      |{0,-10:C}|", myNumber)
Console.WriteLine(formatFirstName)
Console.WriteLine(formatLastName)
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   |

Siehe auch

• WriteLine
• String.Format
• Zeichenfolgeninterpolation (C#)
• Zeichenfolgeninterpolation (Visual Basic)
• Formatierung von Typen
• Standardmäßige Zahlenformatzeichenfolgen
• Benutzerdefinierte numerische Formatzeichenfolgen
• Standardmäßige Formatzeichenfolgen für Datums- und Uhrzeitangaben
• Benutzerdefinierte Formatzeichenfolgen für Datum und Uhrzeit
• StandardtimeSpan-Formatzeichenfolgen
• Benutzerdefinierte TimeSpan-Formatzeichenfolgen
• Enumerationsformatzeichenfolgen