Dieser Artikel wurde maschinell übersetzt. Wenn Sie die englische Version des Artikels anzeigen möchten, aktivieren Sie das Kontrollkästchen Englisch. Sie können den englischen Text auch in einem Popupfenster anzeigen, indem Sie den Mauszeiger über den Text bewegen.
Übersetzung
Englisch

ICustomFormatter-Schnittstelle

 

Veröffentlicht: Oktober 2016

Definiert eine Methode, die die benutzerdefinierte Formatierung des Werts eines Objekts unterstützt.

Namespace:   System
Assembly:  mscorlib (in mscorlib.dll)

<ComVisibleAttribute(True)>
Public Interface ICustomFormatter

NameBeschreibung
System_CAPS_pubmethodFormat(String, Object, IFormatProvider)

Konvertiert den Wert eines angegebenen Objekts unter Verwendung des angegebenen Formats sowie der kulturspezifischen Formatierungsinformationen in die entsprechende Zeichenfolgendarstellung.

Die ICustomFormatter Schnittstelle enthält eine einzelne Methode ICustomFormatter.Format. Wenn diese Schnittstelle, von einem Typ Verweis- oder Werttyp implementiert wird, der Format Methode gibt eine benutzerdefinierte formatierte Zeichenfolgendarstellung eines Objektwerts zurück.

In der Regel die ICustomFormatter Schnittstelle wird implementiert, mit der IFormatProvider Schnittstelle zum Anpassen des Verhaltens von zwei Methoden für die Formatierung von .NET Framework zusammengesetzte Zeichenfolge, die implizit enthalten eine IFormatProvider Parameter. Insbesondere die ICustomFormatter -Schnittstelle bereitstellen kann, benutzerdefinierte Formatierung des Werts eines Objekts, das an die String.Format(IFormatProvider, String, Object()) und StringBuilder.AppendFormat(IFormatProvider, String, Object()) Methoden.

Bereitstellen einer benutzerdefinierten Darstellung der Wert eines Objekts erfordert, dass Sie die folgenden Schritte aus:

  1. Definieren Sie eine Klasse, die implementiert die ICustomFormatter Schnittstelle und die einzelnen Member, die Format Methode.

  2. Definieren Sie eine Klasse, die implementiert die IFormatProvider Schnittstelle und die einzelnen Member, die GetFormat Methode. Die GetFormat Methode gibt eine Instanz Ihrer ICustomFormatter Implementierung. Häufig eine einzelne Klasse implementiert beide ICustomFormatter und IFormatProvider. In diesem Fall wird die Klasse des GetFormat Implementierung gibt nur eine Instanz von sich selbst zurück.

  3. Übergeben der IFormatProvider Implementierung als die provider Argument der String.Format(IFormatProvider, String, Object()) Methode oder eine vergleichbare Methode.

.NET Framework-Methode verwendet dann die benutzerdefinierte Formatierung anstatt einen eigenen.

Hinweise für Implementierer:

Die common Language Runtime versucht, mithilfe der ICustomFormatter Implementierung für jedes Formatelement in einer kombinierten Formatzeichenfolge. Daher sollten Sie erwarten, dass Ihre ICustomFormatter Implementierung wird aufgerufen, um die Formatierung Dienstleistungen auf Objekte oder Werte, die es ist nicht für ausgelegt. In diesen Fällen die Format Methode muss die entsprechende Formatierungsmethode für das Objekt oder den Wert aufgerufen werden.

Es gibt zwei Arten von ICustomFormatter Implementierungen: systeminterne und Erweiterung.

Systeminterne Implementierungen sind Implementierungen, die eine benutzerdefinierte Formatierung für eine Anwendung definiertes Objekt bereitstellen. In diesem Fall sollte die Implementierung der folgenden enthalten:

  • Eine Definition von Formatzeichenfolgen, die die Formatierung des Objekts zu definieren. Formatzeichenfolgen sind optional. Eine Formatzeichenfolge "G" oder "g" wird in der Regel das Format allgemeine ("oder" am häufigsten verwendete) definiert. Allerdings können Sie von Formatzeichenfolgen zu definieren, die Sie auswählen. Sie können auch entscheiden, ob die Groß- und Kleinschreibung beachtet werden.

  • Einen Test, um sicherzustellen, dass der Typ des Objekts an übergeben Ihr Format Methode wird von der Anwendung definierte Typ. Wenn es nicht der Fall ist, sollten Sie des Objekts aufrufen IFormattable Implementierung, sofern vorhanden, oder seine ToString -Methode, wenn dies nicht der Fall. Sie sollten darauf vorbereitet sein, keine Ausnahmen behandeln diese Methodenaufrufe auslösen können.

  • Code zum Behandeln von einer null-Zeichenfolge, wenn die Implementierung Formatzeichenfolgen unterstützt. Die am häufigsten verwendete Ansatz ist eine null-Zeichenfolge mit dem allgemeinen Formatbezeichner zu ersetzen.

  • Code zum Behandeln von Formatzeichenfolgen, die Ihre Implementierung unterstützt.

  • Code zum Behandeln von Formatzeichenfolgen, die Sie nicht unterstützen. Die am häufigsten verwendete Ansatz ist das Auslösen einer FormatException, obwohl Sie die standardformatierung bereitstellen können.

Extension-Implementierungen sind Implementierungen, die benutzerdefinierte Formatierung zum Bereitstellen eines Typs, die bereits formatierungsunterstützung. Beispielsweise können Sie definieren eine CustomerNumberFormatter , die einen ganzzahligen Typ mit Bindestrichen zwischen bestimmten Ziffern formatiert. In diesem Fall sollte die Implementierung der folgenden enthalten:

  • Eine Definition von Formatzeichenfolgen, die die Formatierung des Objekts erweitern. Diese Formatzeichenfolgen sind erforderlich, aber sie müssen nicht in Konflikt mit vorhandenen Formatzeichenfolgen des Typs. Angenommen, Sie erweitern Formatierung für die Int32 geben, sollten Sie u. a. die Formatbezeichner "C", "D", "E", "F" und "G" nicht implementiert.

  • Einen Test, der der Typ des Objekts an Ihre Format Methode ist ein Typ, dessen Formatierung der Erweiterungs unterstützt. Wenn sie nicht der Fall ist, rufen Sie des Objekts IFormattable Implementierung wird, falls vorhanden, oder das Objekt des parameterlosen ToString -Methode, wenn dies nicht der Fall. Sie sollten darauf vorbereitet sein, keine Ausnahmen behandeln diese Methodenaufrufe auslösen können.

  • Code zum Behandeln von Formatzeichenfolgen, die Ihre Erweiterung unterstützt.

  • Code zum Behandeln von Formatzeichenfolgen, die die Erweiterung nicht unterstützt. Diese sollte auf dem Typ übergeben werden IFormattable Implementierung. Sie sollten darauf vorbereitet sein, keine Ausnahmen behandeln diese Methodenaufrufe auslösen können.

Das folgende Beispiel implementiert ICustomFormatter um binäre, oktale und hexadezimale Formatierung von ganzzahligen Werten zu ermöglichen. In diesem Beispiel wird eine einzelne Klasse IBinaryFormatter, implementiert beide ICustomFormatter und IFormatProvider. Seine IFormatProvider.GetFormat Methode bestimmt, ob die formatType -Parameter stellt eine ICustomFormatter Typ. Wenn dies der Fall, BinaryFormatter gibt eine Instanz von sich selbst; andernfalls wird zurückgegeben null. Die ICustomFormatter.Format Implementierung bestimmt, ob der Formatparameter eine der drei unterstützten Formatzeichenfolgen ist ("B" für Binärdatei, "O" für oktale, und "H" für hexadezimal) und formatiert die arg Parameter entsprechend. Andernfalls gilt: Wenn arg ist nicht null, ruft er die arg des Parameters IFormattable.ToString -Implementierung, sofern vorhanden, oder die parameterlose ToString -Methode, wenn eine nicht der Fall ist. Wenn arg gleich null ist, gibt die Methode String.Empty zurück.

Imports System.Globalization
Imports System.Numerics

Public Class BinaryFormatter : Implements IFormatProvider, ICustomFormatter
   ' IFormatProvider.GetFormat implementation.
   Public Function GetFormat(formatType As Type) As Object _
                   Implements IFormatProvider.GetFormat
      ' Determine whether custom formatting object is requested.
      If formatType Is GetType(ICustomFormatter) Then
         Return Me
      Else
         Return Nothing
      End If
   End Function   

   ' Format number in binary (B), octal (O), or hexadecimal (H).
   Public Function Format(fmt As String, arg As Object, _
                          formatProvider As IFormatProvider) As String _
                   Implements ICustomFormatter.Format

     ' Handle format string.
      Dim base As Integer
      ' Handle null or empty format string, string with precision specifier.
      Dim thisFmt As String = String.Empty
      ' Extract first character of format string (precision specifiers
      ' are not supported by BinaryFormatter).
      If Not String.IsNullOrEmpty(fmt) Then
         thisFmt = CStr(IIf(fmt.Length > 1, fmt.Substring(0, 1), fmt))
      End If



      ' Get a byte array representing the numeric value.
      Dim bytes() As Byte
      If TypeOf(arg) Is SByte Then
         Dim byteString As String = CType(arg, SByte).ToString("X2")
         bytes = New Byte(0) { Byte.Parse(byteString, System.Globalization.NumberStyles.HexNumber ) }
      ElseIf TypeOf(arg) Is Byte Then
         bytes = New Byte(0) { CType(arg, Byte) }
      ElseIf TypeOf(arg) Is Int16 Then
         bytes = BitConverter.GetBytes(CType(arg, Int16))
      ElseIf TypeOf(arg) Is Int32 Then
         bytes = BitConverter.GetBytes(CType(arg, Int32))
      ElseIf TypeOf(arg) Is Int64 Then
         bytes = BitConverter.GetBytes(CType(arg, Int64))
      ElseIf TypeOf(arg) Is UInt16 Then
         bytes = BitConverter.GetBytes(CType(arg, UInt16))
      ElseIf TypeOf(arg) Is UInt32 Then
         bytes = BitConverter.GetBytes(CType(arg, UInt64))
      ElseIf TypeOf(arg) Is UInt64 Then
         bytes = BitConverter.GetBytes(CType(arg, UInt64))                  
      ElseIf TypeOf(arg) Is BigInteger Then
         bytes = CType(arg, BigInteger).ToByteArray()
      Else
         Try 
            Return HandleOtherFormats(fmt, arg) 
         Catch e As FormatException 
            Throw New FormatException(String.Format("The format of '{0}' is invalid.", fmt), e)
         End Try
      End If

      Select Case thisFmt.ToUpper()
         ' Binary formatting.
         Case "B"
            base = 2        
         Case "O"
            base = 8
         Case "H"
            base = 16
         ' Handle unsupported format strings.
         Case Else
            Try 
               Return HandleOtherFormats(fmt, arg) 
            Catch e As FormatException 
               Throw New FormatException(String.Format("The format of '{0}' is invalid.", fmt), e)
            End Try
      End Select

      ' Return a formatted string.
      Dim numericString As String = String.Empty
      For ctr As Integer = bytes.GetUpperBound(0) To bytes.GetLowerBound(0) Step -1
         Dim byteString As String = Convert.ToString(bytes(ctr), base)
         If base = 2 Then
            byteString = New String("0"c, 8 - byteString.Length) + byteString
         ElseIf base = 8 Then
            byteString = New String("0"c, 4 - byteString.Length) + byteString
         ' Base is 16.
         Else     
            byteString = New String("0"c, 2 - byteString.Length) + byteString
         End If
         numericString +=  byteString + " "
      Next
      Return numericString.Trim()
   End Function

   Private Function HandleOtherFormats(fmt As String, arg As Object) As String
      If TypeOf arg Is IFormattable Then
         Return DirectCast(arg, IFormattable).ToString(fmt, CultureInfo.CurrentCulture)
      ElseIf arg IsNot Nothing Then
         Return arg.ToString()
      Else
         Return String.Empty
      End If
   End Function
End Class

BinaryFormatterkann dann verwendet werden, geben Sie die benutzerdefinierte Formatierung durch Übergeben einer BinaryFormatter -Objekts entsprechend der der provider Parameter von der Format Methode, wie im folgenden Beispiel gezeigt.

Public Module Example
   Public Sub Main
      Console.WindowWidth = 100

      Dim byteValue As Byte = 124
      Console.WriteLine(String.Format(New BinaryFormatter(), _
                                      "{0} (binary: {0:B}) (hex: {0:H})", byteValue))

      Dim intValue As Integer = 23045
      Console.WriteLine(String.Format(New BinaryFormatter(), _
                                      "{0} (binary: {0:B}) (hex: {0:H})", intValue))

      Dim ulngValue As ULong = 31906574882
      Console.WriteLine(String.Format(New BinaryFormatter(), _
                                      "{0} {1}   (binary: {0:B}) {1}   (hex: {0:H})", _
                                      ulngValue, vbCrLf))

      Dim bigIntValue As BigInteger = BigInteger.Multiply(Int64.MaxValue, 2)
      Console.WriteLine(String.Format(New BinaryFormatter(), _
                                      "{0} {1}   (binary: {0:B}) {1}   (hex: {0:H})", _
                                      bigIntValue, vbCrLf))
   End Sub
End Module
' The example displays the following output:
'    124 (binary: 01111100) (hex: 7c)
'    23045 (binary: 00000000 00000000 01011010 00000101) (hex: 00 00 5a 05)
'    31906574882
'       (binary: 00000000 00000000 00000000 00000111 01101101 11000111 10110010 00100010)
'       (hex: 00 00 00 07 6d c7 b2 22)
'    18446744073709551614
'       (binary: 00000000 11111111 11111111 11111111 11111111 11111111 11111111 11111111 11111110)
'       (hex: 00 ff ff ff ff ff ff ff fe)

Universelle Windows-Plattform
Verfügbar seit 8
.NET Framework
Verfügbar seit 1.1
Portierbare Klassenbibliothek
Unterstützt in: portierbare .NET-Plattformen
Silverlight
Verfügbar seit 2.0
Windows Phone Silverlight
Verfügbar seit 7.0
Windows Phone
Verfügbar seit 8.1
Zurück zum Anfang
Anzeigen: