System.ICustomFormatter Interface

Summary

Defines a method that supports custom, user-defined formatting of the value of an object.

C# Syntax:

public interface ICustomFormatter

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

Use this interface, and the IFormatProvider interface, to supersede the support supplied in .NET Framework formatting methods that honor an IFormatProvider parameter. For example, use this interface to provide custom formatting of the value of an object by the String.Format or Int32.ToString methods.

Derive a class that implements the IFormatProvider interface and its IFormatProvider.GetFormat method. Specify that derived class for the IFormatProvider parameter of the method you want to supersede. Your implementation of the IFormatProvider.GetFormat method should return a format object that implements the ICustomFormatter interface. The .NET Framework method will then use your custom formatting instead of its own.

System Namespace | IFormatProvider

System.ICustomFormatter Member List:

Public Methods

Format

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

System.ICustomFormatter Member Details

Summary

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

C# Syntax:

string Format(string format, object arg, I Format(    string format,    object arg,    IFormatProvider formatProvider );

format

A format string containing formatting specifications.

arg

An object to format.

formatProvider

An IFormatProvider object that supplies format information about the current instance.

Return Value:

The string representation of the value of arg, formatted as specified by format and formatProvider.

Exceptions

Exception Type	Condition
ArgumentNullException	arg is null.

The format parameter contains a user-defined formatting specification. For more information about standard .NET Framework formatting specifications, see the conceptual topic at MSDN: formattingoverview.

Throw an exception only if arg is null. If format is null, use the default format specification of your choice. If formatProvider is null, ignore that parameter.

Your implementation of the ICustomFormatter.Format method must include the following functionality so the .NET Framework can provide formatting you do not support. If your format method does not support a format, determine whether the object being formatted implements the IFormattable interface. If it does, invoke the IFormattable.ToString method of that interface. Otherwise, invoke the default Object.ToString method of the underlying object.

Here is a fragment of C# code that demonstrates this pattern for object arg, format format, format provider formatProvider, and return value, s.

if (arg is IFormattable) s = ((IFormattable)arg).ToString(format, formatProvider);

else if (arg != null) s = arg.ToString();

Return to top

Top of page