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.

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;
   }
}

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

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: