(0) exportieren Drucken
Alle erweitern
Dieser Artikel wurde maschinell übersetzt. Bewegen Sie den Mauszeiger über die Sätze im Artikel, um den Originaltext anzuzeigen. Weitere Informationen
Übersetzung
Original

ICustomFormatter-Schnittstelle

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

Der ICustomFormatter-Typ macht die folgenden Member verfügbar.

  NameBeschreibung
Öffentliche MethodeUnterstützt von XNA FrameworkUnterstützt von Portable KlassenbibliothekUnterstützt in .NET für Windows Store-AppsFormatKonvertiert den Wert eines angegebenen Objekts unter Verwendung des angegebenen Formats und der kulturabhängigen Formatierungsinformationen in eine entsprechende Zeichenfolgenentsprechung.
Zum Seitenanfang

Die ICustomFormatter-Schnittstelle verfügt über eine einzige Methode, ICustomFormatter.Format. Wenn diese Schnittstelle durch einen Verweis- oder Werttyp implementiert wird, gibt die Format-Methode eine Zeichenfolgenentsprechung des Werts eines Objekts in einem benutzerdefinierten Format zurück.

In der Regel wird die ICustomFormatter-Schnittstelle mit der IFormatProvider-Schnittstelle implementiert, um das Verhalten von .NET Framework zwei Zeichenfolgen-Formatierungsmethoden anzupassen zusammengesetzten, die einen IFormatProvider-Parameter enthalten. Insbesondere kann die ICustomFormatter-Schnittstelle benutzerdefinierte Formatierung des Werts eines Objekts bereitstellen, das den String.Format(IFormatProvider, String, Object[]) und StringBuilder.AppendFormat(IFormatProvider, String, Object[])-Methoden übergeben wird.

Eine benutzerdefinierte Darstellung eines Objektwerts bereitzustellen, erfordert folgende Schritte:

  1. Definieren Sie eine Klasse, die die ICustomFormatter-Schnittstelle und deren einzigen Member (die Format-Methode) implementiert.

  2. Definieren Sie eine Klasse, die die IFormatProvider-Schnittstelle und deren einzigen Member (die GetFormat-Methode) implementiert. Die GetFormat-Methode gibt eine Instanz der ICustomFormatter-Implementierung zurück. Häufig implementiert eine einzelne Klasse sowohl ICustomFormatter als auch IFormatProvider. In diesem Fall gibt die GetFormat-Implementierung der Klasse nur eine Instanz von sich zurück.

  3. Übergeben Sie die IFormatProvider-Implementierung als provider-Argument der String.Format(IFormatProvider, String, Object[])-Methode oder einer vergleichbaren Methode.

Die .NET Framework-Methode verwendet dann die benutzerdefinierte Formatierung anstelle ihrer eigenen.

Hinweise zur Implementierung

Die Common Language Runtime versucht, die ICustomFormatter-Implementierung in einer zusammengesetzten Formatzeichenfolge für jedes Formatelement zu verwenden. Als Ergebnis sollten Sie erwarten, dass die ICustomFormatter-Implementierung aufgerufen wird, um Formatierungsdienste für Objekte oder Werte bereitzustellen, für deren Behandlung sie nicht entworfen wurde. In diesen Fällen muss die Format-Methode die entsprechende Formatierungsmethode für das Objekt oder den Wert aufrufen.

Es gibt zwei Arten von ICustomFormatter-Implementierungen: systemintern und Erweiterung.

Systeminterne Implementierungen sind Implementierungen, die eine benutzerdefinierte Formatierung für ein anwendungsdefiniertes Objekt bereitstellen. In diesem Fall sollte die Implementierung Folgendes einschließen:

  • Eine Definition von Formatierungszeichenfolgen, die die Formatierung des Objekts definieren. Formatzeichenfolgen sind optional. In der Regel definiert die Formatzeichenfolge "G" oder "g" das allgemeine (oder am häufigsten verwendete) Format. Sie können Formatzeichenfolgen jedoch ganz nach Belieben definieren. Sie können auch frei festlegen, ob die Groß-/Kleinschreibung beachtet wird.

  • Ein Test, um sicherzustellen, dass der Typ des Objekts, das an die Format-Methode übergeben wurde, der von der Anwendung definierte Typ ist. Wenn nicht, rufen Sie die IFormattable-Implementierung des Objekts auf, falls vorhanden, oder die ToString-Methode, wenn nicht vorhanden. Sie sollten Vorkehrungen treffen, alle Ausnahmen zu behandeln, die diese Methodenaufrufe auslösen könnten.

  • Code zum Behandeln einer NULL Formatzeichenfolge, wenn die Implementierung Formatzeichenfolgen unterstützt. Der gängigste Ansatz besteht darin, eine NULL Formatzeichenfolge durch den allgemeinen Formatbezeichner zu ersetzen.

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

  • Code zum Behandeln von Formatzeichenfolgen, die nicht unterstützt werden. Der gängigste Ansatz besteht darin, einen FormatException auszulösen, obwohl Sie auch die Standardformatierung bereitstellen können.

Erweiterungsimplementierungen sind Implementierungen, die benutzerdefinierte Formatierung für einen Typ bereitstellen, der bereits über Formatierungsunterstützung verfügt. Sie können z. B. einen CustomerNumberFormatter definieren, der einen ganzzahligen Typ mit Bindestrichen zwischen bestimmten Ziffern formatiert. In diesem Fall sollte die Implementierung Folgendes einschließen:

  • Eine Definition von Formatierungszeichenfolgen, die die Formatierung des Objekts erweitern. Diese Formatzeichenfolgen sind erforderlich, aber sie dürfen keinen Konflikt mit den vorhandenen Formatzeichenfolgen des Typs verursachen. Wenn Sie z. B. die Formatierung für den Int32-Typ verlängern, sollten Sie Formatbezeichner "C","D", "E", "F", und "G", u. a. nicht implementieren.

  • Ein Test, dass der Typ des Objekts, das an die Format-Methode übergeben wurde, ein Typ ist, dessen Formatierung die Erweiterung unterstützt. Wenn nicht, rufen Sie die IFormattable-Implementierung des Objekts auf, falls vorhanden, oder die parameterlose ToString-Methode des Objekts, wenn nicht vorhanden. Sie sollten Vorkehrungen treffen, alle Ausnahmen zu behandeln, die diese Methodenaufrufe auslösen könnten.

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

  • Code zum Behandeln von Formatzeichenfolgen, die von der Erweiterung nicht unterstützt werden. Diese sollten an die IFormattable-Implementierung des Typs übergeben werden. Sie sollten Vorkehrungen treffen, alle Ausnahmen zu behandeln, die diese Methodenaufrufe auslösen könnten.

Im folgenden Beispiel wird ICustomFormatter implementiert, um binäre, oktale, und hexadezimale Formatierung von ganzzahligen Werten zu ermöglichen. In diesem Beispiel implementiert die einzelne Klasse IBinaryFormatter sowohl ICustomFormatter als auch IFormatProvider. Die zugehörige IFormatProvider.GetFormat-Methode bestimmt, ob der formatType-Parameter einen ICustomFormatter-Typ darstellt. Wenn ja, gibt BinaryFormatter eine Instanz von sich selbst zurück. Andernfalls wird null zurückgegeben. Seine ICustomFormatter.Format-Implementierung bestimmt, ob der Formatparameter eine der drei unterstützten Formatzeichenfolgen ("B" für Binärdatei, "O" für Oktal und "STD" für Hexadezimal) ist und den arg-Parameter ordnungsgemäß formatiert. Wenn arg jedoch nicht null ist, wird die IFormattable.ToString-Implementierung des arg-Parameters, sofern vorhanden, oder die parameterlose ToString-Methode aufgerufen. Wenn arg gleich null ist, gibt die Methode String.Empty zurück.


using System;
using System.Globalization;
using System.Numerics;

public class BinaryFormatter : IFormatProvider, ICustomFormatter
{
   // IFormatProvider.GetFormat implementation.
   public object GetFormat(Type formatType)
   {
      // Determine whether custom formatting object is requested.
      if (formatType == typeof(ICustomFormatter))
         return this;
      else
         return null;
   }   

   // Format number in binary (B), octal (O), or hexadecimal (H).
   public string Format(string format, object arg, IFormatProvider formatProvider)
   {
      // Handle format string.
      int baseNumber;
      // Handle null or empty format string, string with precision specifier.
      string thisFmt = String.Empty;
      // Extract first character of format string (precision specifiers
      // are not supported).
      if (! String.IsNullOrEmpty(format))
         thisFmt = format.Length > 1 ? format.Substring(0, 1) : format;


      // Get a byte array representing the numeric value.
      byte[] bytes;
      if (arg is sbyte)
      {
         string byteString = ((sbyte) arg).ToString("X2");
         bytes = new byte[1] { Byte.Parse(byteString, System.Globalization.NumberStyles.HexNumber ) };
      }
      else if (arg is byte) {
         bytes = new byte[1] { (byte) arg };
      }   
      else if (arg is short) {
         bytes = BitConverter.GetBytes((short) arg);
      }   
      else if (arg is int) {
         bytes = BitConverter.GetBytes((int) arg);
      }   
      else if (arg is long) {
         bytes = BitConverter.GetBytes((long) arg);
      }
      else if (arg is ushort) {
         bytes = BitConverter.GetBytes((ushort) arg);
      }
      else if (arg is uint) {
         bytes = BitConverter.GetBytes((uint) arg);
      }
      else if (arg is ulong) {
         bytes = BitConverter.GetBytes((ulong) arg);                  
      }
      else if (arg is BigInteger) {
         bytes = ((BigInteger) arg).ToByteArray();
      }
      else {
         try {
            return HandleOtherFormats(format, arg); 
         }
         catch (FormatException e) {
            throw new FormatException(String.Format("The format of '{0}' is invalid.", format), e);
         }
      }

      switch (thisFmt.ToUpper())
      {
         // Binary formatting.
         case "B":
            baseNumber = 2;
            break;        
         case "O":
            baseNumber = 8;
            break;
         case "H":
            baseNumber = 16;
            break;
         // Handle unsupported format strings.
         default:
         try {
            return HandleOtherFormats(format, arg); 
         }
         catch (FormatException e) {
            throw new FormatException(String.Format("The format of '{0}' is invalid.", format), e);
         }
      }

      // Return a formatted string.
      string numericString = String.Empty;
      for (int ctr = bytes.GetUpperBound(0); ctr >= bytes.GetLowerBound(0); ctr--)
      {
         string byteString = Convert.ToString(bytes[ctr], baseNumber);
         if (baseNumber == 2)
            byteString = new String('0', 8 - byteString.Length) + byteString;
         else if (baseNumber == 8)
            byteString = new String('0', 4 - byteString.Length) + byteString;
         // Base is 16.
         else     
            byteString = new String('0', 2 - byteString.Length) + byteString;

         numericString +=  byteString + " ";
      }
      return numericString.Trim();
   }

   private string HandleOtherFormats(string format, object arg)
   {
      if (arg is IFormattable) 
         return ((IFormattable)arg).ToString(format, CultureInfo.CurrentCulture);
      else if (arg != null)
         return arg.ToString();
      else
         return String.Empty;
   }
}


BinaryFormatter kann dann verwendet werden, um benutzerdefinierte Formatierung durch das Übergeben eines BinaryFormatter-Objekts als provider-Parameter der Format-Methode bereitzustellen, wie das folgende Beispiel zeigt.


public class Example
{
   public static void Main()
   {
      Console.WindowWidth = 100;

      byte byteValue = 124;
      Console.WriteLine(String.Format(new BinaryFormatter(), 
                                      "{0} (binary: {0:B}) (hex: {0:H})", byteValue));

      int intValue = 23045;
      Console.WriteLine(String.Format(new BinaryFormatter(), 
                                      "{0} (binary: {0:B}) (hex: {0:H})", intValue));

      ulong ulngValue = 31906574882;
      Console.WriteLine(String.Format(new BinaryFormatter(), 
                                      "{0}\n   (binary: {0:B})\n   (hex: {0:H})", 
                                      ulngValue));

      BigInteger bigIntValue = BigInteger.Multiply(Int64.MaxValue, 2);
      Console.WriteLine(String.Format(new BinaryFormatter(), 
                                      "{0}\n   (binary: {0:B})\n   (hex: {0:H})", 
                                      bigIntValue));
   }
}
// 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)


.NET Framework

Unterstützt in: 4.5.2, 4.5.1, 4.5, 4, 3.5, 3.0, 2.0, 1.1, 1.0

.NET Framework Client Profile

Unterstützt in: 4, 3.5 SP1

Portable Klassenbibliothek

Unterstützt in: Portable Klassenbibliothek

.NET für Windows Store-Apps

Unterstützt in: Windows 8

.NET für Windows Phone-Apps

Unterstützt in: Windows Phone 8, Silverlight 8.1

Windows Phone 8.1, Windows Phone 8, Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core-Rolle wird nicht unterstützt), Windows Server 2008 R2 (Server Core-Rolle wird mit SP1 oder höher unterstützt; Itanium wird nicht unterstützt)

.NET Framework unterstützt nicht alle Versionen sämtlicher Plattformen. Eine Liste der unterstützten Versionen finden Sie unter Systemanforderungen für .NET Framework.

Community-Beiträge

HINZUFÜGEN
Anzeigen:
© 2014 Microsoft