Methods

Converts the value of a specified object to an equivalent string representation using specified format and culture-specific formatting information.

Top

Remarks

The ICustomFormatter interface includes a single method, ICustomFormatter.Format. When this interface is implemented by a reference or value type, the Format method returns a custom-formatted string representation of an object's value.

Providing a custom representation of an object's value requires that you do the following:

Define a class that implements the ICustomFormatter interface and its single member, the Format method.

Define a class that implements the IFormatProvider interface and its single member, the GetFormat method. The GetFormat method returns an instance of your ICustomFormatter implementation. Often, a single class implements both ICustomFormatter and IFormatProvider. In that case, the class's GetFormat implementation just returns an instance of itself.

The .NET Framework method will then use your custom formatting instead of its own.

Notes to Implementers

The common language runtime attempts to use your ICustomFormatter implementation for every format item in a composite format string. As a result, you should expect that your ICustomFormatter implementation will be called to provide formatting services to objects or values that it is not designed to handle. In these cases, your Format method must call the appropriate formatting method for that object or value.

There are two kinds of ICustomFormatter implementations: intrinsic and extension.

Intrinsic implementations are implementations that provide custom formatting for an application-defined object. In this case, your implementation should include the following:

A definition of format strings that define the formatting of the object. Format strings are optional. Typically, a "G" or "g" format string defines the general (or most commonly used) format. However, you are free to define any format strings that you choose. You are also free to decide whether they are case-sensitive or case-insensitive.

A test to ensure that the type of the object passed to your Format method is your application-defined type. If it is not, you should call the object's IFormattable implementation, if one exists, or its ToString method, if it does not. You should be prepared to handle any exceptions these method calls might throw.

Code to handle a null format string, if your implementation supports format strings. The most common approach is to replace a null format string with the general format specifier.

Code to handle any format strings that your implementation supports.

Code to handle format strings that you do not support. The most common approach is to throw a FormatException, although you can provide default formatting.

Extension implementations are implementations that provide custom formatting for a type that already has formatting support. For example, you could define a CustomerNumberFormatter that formats an integral type with hyphens between specific digits. In this case, your implementation should include the following:

A definition of format strings that extend the formatting of the object. These format strings are required, but they must not conflict with the type's existing format strings. For example, if you are extending formatting for the Int32 type, you should not implement the "C", "D", "E", "F", and "G" format specifiers, among others.

A test that the type of the object passed to your Format method is a type whose formatting your extension supports. If it is not, call the object's IFormattable implementation, if one exists, or the object's parameterless ToString method, if it does not. You should be prepared to handle any exceptions these method calls might throw.

Code to handle any format strings that your extension supports.

Code to handle any format strings that your extension does not support. These should be passed on to the type's IFormattable implementation. You should be prepared to handle any exceptions these method calls might throw.

Examples

The following example implements ICustomFormatter to allow binary, octal, and hexadecimal formatting of integral values. In this example, a single class, IBinaryFormatter, implements both ICustomFormatter and IFormatProvider. Its IFormatProvider.GetFormat method determines whether the formatType parameter represents an ICustomFormatter type. If it does, BinaryFormatter returns an instance of itself; otherwise, it returns nulla null reference (Nothing in Visual Basic). Its ICustomFormatter.Format implementation determines whether the format parameter is one of the three supported format strings ("B" for binary, "O" for octal, and "H" for hexadecimal) and formats the arg parameter appropriately. Otherwise, if arg is not nulla null reference (Nothing in Visual Basic), it calls the arg parameter's IFormattable.ToString implementation, if one exists, or its parameterless ToString method, if one does not. If arg is nulla null reference (Nothing in Visual Basic), the method returns String.Empty.