Exporter (0) Imprimer
Développer tout
Cet article a fait l'objet d'une traduction automatique. Déplacez votre pointeur sur les phrases de l'article pour voir la version originale de ce texte. Informations supplémentaires.
Traduction
Source

ICustomFormatter, interface

Définit une méthode qui prend en charge la mise en forme personnalisée de la valeur d'un objet.

Espace de noms :  System
Assembly :  mscorlib (dans mscorlib.dll)

[ComVisibleAttribute(true)]
public interface ICustomFormatter

Le type ICustomFormatter expose les membres suivants.

  NomDescription
Méthode publiquePris en charge par XNA FrameworkPris en charge par Bibliothèque de classes portablePris en charge dans .NET pour les applications du Windows StoreFormatConvertit la valeur d'un objet spécifié en une chaîne équivalente à l'aide du format spécifié et des informations de mise en forme propres à la culture.
Début

L'interface ICustomFormatter inclut une méthode unique, ICustomFormatter.Format. Si cette interface est implémentée par un type référence ou valeur, la méthode Format retourne une représentation sous forme de chaîne de mise en forme personnalisée de la valeur d'un objet.

En général, l'interface ICustomFormatter est implémentée avec l'interface IFormatProvider pour personnaliser le comportement de deux méthodes de mise en forme composite de chaînes .NET Framework qui incluent un paramètre IFormatProvider. Plus particulièrement, l'interface ICustomFormatter peut fournir une mise en forme personnalisée de la valeur d'un objet passé à String.Format(IFormatProvider, String, Object[]) et aux méthodes StringBuilder.AppendFormat(IFormatProvider, String, Object[]).

La fourniture d'une représentation personnalisée de la valeur d'un objet requiert que vous effectuiez les opérations suivantes :

  1. Définissez une classe qui implémente l'interface ICustomFormatter et son membre unique, la méthode Format.

  2. Définissez une classe qui implémente l'interface IFormatProvider et son membre unique, la méthode GetFormat. La méthode GetFormat retourne une instance de votre implémentation ICustomFormatter. Souvent, une classe unique implémente ICustomFormatter et IFormatProvider. Dans ce cas, l'implémentation GetFormat de la classe retourne simplement une instance à elle-même.

  3. Passez l'implémentation IFormatProvider comme argument provider de la méthode String.Format(IFormatProvider, String, Object[]) ou d'une méthode comparable.

La méthode .NET Framework utilise ensuite votre mise en forme personnalisée plutôt que la sienne.

Remarques à l'attention des implémenteurs

Le Common Language Runtime essaie d'utiliser votre implémentation ICustomFormatter pour chaque élément de mise en forme dans une chaîne de format composite. Par conséquent, vous devez vous attendre à ce que votre implémentation ICustomFormatter soit appelée pour fournir des services de mise en forme aux objets ou valeurs que sa conception ne permet pas de gérer. Dans ces cas, votre méthode Format doit appeler la méthode de mise en forme appropriée pour cet objet ou pour cette valeur.

Il y a deux types d'implémentations ICustomFormatter: intrinsèques et extensions.

Les implémentations intrinsèques sont des implémentations qui fournissent la mise en forme personnalisée pour un objet défini par l'application. Dans ce cas, votre implémentation devrait inclure les éléments suivants :

  • Définition des chaînes de mise en forme qui définissent la mise en forme de l'objet. Les chaînes de mise en forme sont facultatives. En général, une chaîne de mise en forme « G » ou « g » définit le format général (ou le plus utilisé). Toutefois, vous êtes libre de définir toute chaîne de mise en forme que vous choisissez. Vous êtes également libre à décider s'ils respectent ou non la casse.

  • Un test pour garantir que le type de l'objet passé à votre méthode Format est votre type défini par l'application. Dans le cas contraire, vous devez appeler l'implémentation de l'objet IFormattable, si elle existe, ou sa méthode ToString, si elle n'existe pas. Vous devez être préparé à gérer n'importe quelle exception que ces appels de méthode peuvent lever.

  • Code pour gérer une chaîne de format null, si votre implémentation prend en charge les chaînes de format. L'approche la plus courante consiste à remplacer une chaîne de format null par le spécificateur de format général.

  • Code pour gérer toutes les chaînes de format que votre implémentation prend en charge.

  • Code pour gérer les chaînes de format que vous ne prenez pas en charge. L'approche la plus courante consiste à lever une exception FormatException, bien que vous puissiez spécifier une mise en forme par défaut.

Les implémentations d'extension sont des implémentations qui fournissent la mise en forme personnalisée pour un type qui a déjà la prise en charge de la mise en forme. Par exemple, vous pourriez définir un CustomerNumberFormatter qui met en forme un type intégral avec des traits d'union entre des chiffres spécifiques. Dans ce cas, votre implémentation devrait inclure les éléments suivants :

  • Définition des chaînes de mise en forme qui étendent la mise en forme de l'objet. Ces chaînes de mise en forme sont obligatoires, mais ne doivent pas être en conflit avec les chaînes de mise en forme existantes du type. Par exemple, si vous étendez la mise en forme pour le type Int32, vous ne devez pas implémenter les spécificateurs de format "C", "D", "E", "F" et "G, parmi d'autres.

  • Un test pour garantir que le type de l'objet passé à votre méthode Format est un type dont la mise en forme est prise en charge par votre extension. Dans le cas contraire, appelez l'implémentation de l'objet IFormattable, si elle existe, ou la méthode ToString sans paramètre de l'objet, si elle n'existe pas. Vous devez être préparé à gérer n'importe quelle exception que ces appels de méthode peuvent lever.

  • Code pour gérer toutes les chaînes de format que votre extension prend en charge.

  • Code pour gérer toutes les chaînes de format que votre extension ne prend pas en charge. Celles-ci doivent être transmises à l'implémentation du type IFormattable. Vous devez être préparé à gérer n'importe quelle exception que ces appels de méthode peuvent lever.

L'exemple suivant implémente ICustomFormatter pour autoriser la mise en forme binaire, octale, et hexadécimale de valeurs intégrales. Dans cet exemple, une classe unique, IBinaryFormatter, implémente ICustomFormatter et IFormatProvider. Sa méthode IFormatProvider.GetFormat détermine si le paramètre formatType représente un type ICustomFormatter. S'il le fait, BinaryFormatter retourne une instance d'elle-même; sinon, il retourne null. Son implémentation ICustomFormatter.Format détermine si le paramètre de mise en forme est l'une des trois chaînes de mise en forme prises en charge ("B" pour binaire, "O" pour octal, et "H" pour hexadécimal) et met en forme le paramètre arg de manière adaptée. Dans le cas contraire, si arg n'est pas null, il appelle l'implémentation IFormattable.ToString du paramètre arg, s'il en existe un, ou sa méthode ToString sans paramètre, s'il n'en existe pas. Si arg est null, la méthode retourne String.Empty.


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


Puis BinaryFormatter peut être utilisé pour fournir la mise en forme personnalisée en passant un objet BinaryFormatter comme paramètre provider de la méthode Format, comme l'exemple suivant affiche.


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

Pris en charge dans : 4.5.2, 4.5.1, 4.5, 4, 3.5, 3.0, 2.0, 1.1, 1.0

.NET Framework Client Profile

Pris en charge dans : 4, 3.5 SP1

Bibliothèque de classes portable

Pris en charge dans : Bibliothèque de classes portable

.NET pour les applications du Windows Store

Pris en charge dans : Windows 8

.NET pour les applications Windows Phone

Pris en charge dans : 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 (rôle principal du serveur non pris en charge), Windows Server 2008 R2 (rôle principal du serveur pris en charge avec SP1 ou version ultérieure ; Itanium non pris en charge)

Le .NET Framework ne prend pas en charge toutes les versions de chaque plateforme. Pour obtenir la liste des versions prises en charge, consultez Configuration requise du .NET Framework.

Ajouts de la communauté

AJOUTER
Afficher:
© 2014 Microsoft