String.Format Method (IFormatProvider, String, Object[])

Replaces the format item in a specified String with the text equivalent of the value of a corresponding Object instance in a specified array. A specified parameter supplies culture-specific formatting information.

Namespace: System
Assembly: mscorlib (in mscorlib.dll)

public static string Format (
	IFormatProvider provider,
	string format,
	params Object[] args
public static String Format (
	IFormatProvider provider, 
	String format, 
	Object[] args
public static function Format (
	provider : IFormatProvider, 
	format : String, 
	... args : Object[]
) : String
Not applicable.



An IFormatProvider that supplies culture-specific formatting information.


A composite format string.


An Object array containing zero or more objects to format.

Return Value

A copy of format in which the format items have been replaced by the String equivalent of the corresponding instances of Object in args.

Exception typeCondition


format or args is a null reference (Nothing in Visual Basic).


format is invalid.


The number indicating an argument to format is less than zero, or greater than or equal to the length of the args array.

This method uses the composite formatting feature of the .NET Framework to convert the value of an object to its text representation and embed that representation in a string. The .NET Framework provides extensive formatting support, which is described in greater detail in the following formatting topics.

The provider parameter supplies custom and culture-specific information used to moderate the formatting process. For more information, see the Format Providers section of the Formatting Overview topic. The Example section provides an example of a custom format provider that outputs numeric values as customer account numbers with embedded hyphens.

The format parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to an object in the parameter list of this method. The formatting process replaces each format item with the text representation of the value of the corresponding object.

The syntax of a format item is {index[,alignment][:formatString]}, which specifies a mandatory index, the optional length and alignment of the formatted text, and an optional string of format specifier characters that govern how the value of the corresponding object is formatted. The components of a format item are:


A zero-based integer that indicates which element in a list of objects to format. If the object specified by index is a null reference (Nothing in Visual Basic), then the format item is replaced by the empty string ("").


An optional integer indicating the minimum width of the region to contain the formatted value. If the length of the formatted value is less than alignment, then the region is padded with spaces. If alignment is negative, the formatted value is left justified in the region; if alignment is positive, the formatted value is right justified. If alignment is not specified, the length of the region is the length of the formatted value. The comma is required if alignment is specified.


An optional string of format specifiers. If formatString is not specified and the corresponding argument implements the IFormattable interface, then a null reference (Nothing in Visual Basic) is used as the IFormattable.ToString format string. Therefore, all implementations of IFormattable.ToString are required to allow a null reference (Nothing in Visual Basic) as a format string, and return default formatting of the object representation as a String object. The colon is required if formatString is specified.

The leading and trailing brace characters, '{' and '}', are required. To specify a single literal brace character in format, specify two leading or trailing brace characters; that is, "{{" or "}}".

If the value of format is, "Thank you for your purchase of {0:####} copies of Microsoft®.NET (Core Reference).", and arg[0] is an Int16 with the value 123, then the return value will be:

"Thank you for your purchase of 123 copies of Microsoft®.NET (Core Reference)."

If the value of format is, "Brad's dog has {0,-8:G} fleas.", arg[0]is an Int16 with the value 42, (and in this example, underscores represent padding spaces) then the return value will be:

"Brad's dog has 42______ fleas."

The following example demonstrates the standard formatting specifiers for numbers, dates, and enumerations. It formats the string representation of these values using the invariant culture.

The following example defines a customer number format provider that formats an integer value as a customer account number in the form x-xxxxx-xx.

Windows 98, Windows Server 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.

.NET Framework

Supported in: 3.0, 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 2.0, 1.0

XNA Framework

Supported in: 1.0

Community Additions