System.ICustomFormatter 接口

方法描述

定义一种方法,它支持自定义设置对象的值的格式。

语法定义(C# System.ICustomFormatter 接口 的用法)

[ComVisibleAttribute(true)]
public interface ICustomFormatter

构造函数

构造函数名称 构造函数描述

成员/方法

方法名称 方法描述
Format 使用指定的格式和区域性特定格式设置信息将指定对象的值转换为等效的字符串表示形式。

提示和注释

ICustomFormatter 接口包含单个方法:ICustomFormatter.Format。 当此接口由引用或值类型实现时,Format 方法会返回对象值的自定义格式字符串表示形式。

通常,ICustomFormatter 接口与 IFormatProvider 接口一起实现,用于自定义包含 IFormatProvider 参数的 .NET Framework 字符串格式设置方法的行为。 例如,ICustomFormatter 接口可提供传递到 String.Format(IFormatProvider, String, Object[]) 方法的对象值自定义格式设置。

提供对象值的自定义的表示形式时,需要下列操作:

定义一个类,它实现 ICustomFormatter 接口及其单个成员(Format 方法)。

定义一个类,它实现 IFormatProvider 接口及其单个成员(GetFormat 方法)。 GetFormat 方法返回一个 ICustomFormatter 实现的实例。 通常,单个类同时实现 ICustomFormatter 和 IFormatProvider。 在这种情况下,类的 GetFormat 实现仅返回其自身的实例。

传递 IFormatProvider 实现作为 String.Format(IFormatProvider, String, Object[]) 方法或可比较方法的 provider 参数。

然后,.NET Framework 方法将使用您的自定义格式设置来替代它自己的格式设置。

对实现者的说明

公共语言运行库将尝试为复合格式字符串中每个格式项使用 ICustomFormatter 实现。 因此,可以预期将调用 ICustomFormatter 实现以提供未设计为处理对象或值的格式化服务。 在这些情况下,Format 方法必须为该对象或值调用适当的格式设置方法。

有两种 ICustomFormatter 实现:内部和扩展。

固有的实现都是为应用程序定义的对象提供自定义格式设置的实现。 在这种情况下,您的实现应包括以下内容:

定义对象的格式设置的格式字符串的定义。 格式化字符串是可选的。 通常,“G”或“g”格式字符串定义了常规(或最常用的)格式。 但是,您可以随意定义您选择的任何格式字符串。 您还可以随意决定它们是否区分大小写。

用于确保对象类型传递至 Format 方法的测试是应用程序定义的类型。 如果不是,则在存在时,应调用对象的 IFormattable 实现,在不存在时,调用其 ToString 方法。 应准备好处理这些方法调用可能会引发的任何异常。

如果您的实现支持格式字符串,则为处理空格式字符串的代码。 最常见的方法是将空格式字符串替换为常规格式说明符。

处理实现支持的任何格式字符串的代码。

处理您不支持的格式字符串的代码。 最常见的方法是引发 FormatException,尽管您也可以提供默认格式设置。

扩展实现是为有格式设置支持的类型提供自定义格式设置的实现。 例如,您可以定义 CustomerNumberFormatter,将整型的格式设置为在特定的数字间具有连字符 。 在这种情况下,您的实现应包括以下内容:

扩展对象的格式设置的格式字符串的定义。 这些格式字符串是必需的,但是它们不能与类型的现有格式字符串冲突。 例如,如果您正在扩展 Int32 类型的格式设置,则不应在其他格式说明符中实现“C”、“D”、“E”、“F”和“G”格式说明符。

对象类型传递至 Format 方法的测试是设置扩展名支持的类型。 如果不是,则在存在时,调用对象的 IFormattable 实现,在不存在时,调用对象的无参数 ToString 方法。 应准备好处理这些方法调用可能会引发的任何异常。

处理扩展支持的任何格式字符串的代码。

处理扩展不支持的任何格式字符串的代码。 这些应传递到该类型的 IFormattable 实现。 应准备好处理这些方法调用可能会引发的任何异常。

System.ICustomFormatter 接口例子

然后,通过将 BinaryFormatter 对象作为 Format 方法的 provider 参数传递,BinaryFormatter 可用于提供自定义格式设置,如下例所示。

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)

继承层次结构

命名空间

namespace: System

程序集: mscorlib(在 mscorlib.dll 中)

线程安全

版本信息

.NET Framework 受以下版本支持:4、3.5、3.0、2.0、1.1、1.0 .NET Framework Client Profile 受以下版本支持:4、3.5 SP1 受以下版本支持:

适用平台

Windows 7, Windows Vista SP1 或更高版本, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008(不支持服务器核心), Windows Server 2008 R2(支持 SP1 或更高版本的服务器核心), Windows Server 2003 SP2 .NET Framework 并不是对每个平台的所有版本都提供支持。有关支持的版本的列表,请参见.NET Framework 系统要求。