Tipos de formatação no .NETFormatting types in .NET

Formatação é o processo de conversão de uma instância de classe, estrutura ou valor de enumeração em sua representação de cadeia de caracteres, de forma que a cadeia de caracteres resultante possa ser exibida aos usuários ou desserializada para restaurar o tipo de dados original.Formatting is the process of converting an instance of a class, structure, or enumeration value to its string representation, often so that the resulting string can be displayed to users or deserialized to restore the original data type. Essa conversão pode apresentar uma série de desafios:This conversion can pose a number of challenges:

  • A maneira que os valores são armazenados internamente não necessariamente reflete a maneira que os usuários desejam exibi-los.The way that values are stored internally does not necessarily reflect the way that users want to view them. Por exemplo, um número de telefone pode ser armazenado no formato 8009999999, que não é amigável.For example, a telephone number might be stored in the form 8009999999, which is not user-friendly. Em vez disso, ele deve ser exibido como 800-999-9999.It should instead be displayed as 800-999-9999. Veja a seção Cadeias de caracteres de formato personalizado para obter um exemplo que formata um número dessa maneira.See the Custom Format Strings section for an example that formats a number in this way.

  • Às vezes, a conversão de um objeto para sua representação de cadeia de caracteres não é intuitiva.Sometimes the conversion of an object to its string representation is not intuitive. Por exemplo, não é claro o modo como a representação de cadeia de caracteres de um objeto de Temperatura ou um objeto de Pessoa deve aparecer.For example, it is not clear how the string representation of a Temperature object or a Person object should appear. Para obter um exemplo que formata um objeto Temperatura de diversas maneiras, veja a seção Cadeias de caracteres de formato padrão.For an example that formats a Temperature object in a variety of ways, see the Standard Format Strings section.

  • Muitas vezes, os valores exigem formatação que leva em conta a cultura.Values often require culture-sensitive formatting. Por exemplo, em um aplicativo que usa números para refletir os valores monetários, cadeias de caracteres numéricas devem incluir o símbolo da moeda da cultura atual, o separador de grupo (que, na maioria das culturas, é o separador de milhar) e o símbolo decimal.For example, in an application that uses numbers to reflect monetary values, numeric strings should include the current culture’s currency symbol, group separator (which, in most cultures, is the thousands separator), and decimal symbol. Para ver um exemplo, veja a seção Formatação que leva em conta a cultura com provedores de formato e a interface IFormatProvider.For an example, see the Culture-Sensitive Formatting with Format Providers and the IFormatProvider Interface section.

  • Um aplicativo pode ter que exibir o mesmo valor de maneiras diferentes.An application may have to display the same value in different ways. Por exemplo, um aplicativo pode representar um membro de enumeração ao exibindo uma representação de cadeia de caracteres de seu nome ou exibindo seu valor subjacente.For example, an application may represent an enumeration member by displaying a string representation of its name or by displaying its underlying value. Para obter um exemplo que formata um membro da enumeração DayOfWeek de maneiras diferentes, veja a seção Cadeias de caracteres de formato padrão.For an example that formats a member of the DayOfWeek enumeration in different ways, see the Standard Format Strings section.

Observação

A formatação converte o valor de um tipo em uma representação de cadeia de caracteres.Formatting converts the value of a type into a string representation. A análise é o inverso da formatação.Parsing is the inverse of formatting. Uma operação de análise cria uma instância de um tipo de dados com base em na representação de sua cadeia de caracteres.A parsing operation creates an instance of a data type from its string representation. Para obter informações sobre como converter cadeias de caracteres em outros tipos de dados, veja Analisando cadeias de caracteres.For information about converting strings to other data types, see Parsing Strings.

O .NET dá suporte à formatação avançada, que permite aos desenvolvedores atender a esses requisitos..NET provides rich formatting support that enables developers to address these requirements.

Esta visão geral contém as seguintes seções:This overview contains the following sections:

Formatação em .NETFormatting in .NET

O mecanismo básico de formatação é a implementação padrão do método Object.ToString, que é abordado na seção Formatação padrão usando o método ToString, mais adiante neste tópico.The basic mechanism for formatting is the default implementation of the Object.ToString method, which is discussed in the Default Formatting Using the ToString Method section later in this topic. No entanto, o .NET oferece várias maneiras de modificar e estender o suporte à formatação padrão.However, .NET provides several ways to modify and extend its default formatting support. Eles incluem o seguinte:These include the following:

  • A substituição do método Object.ToString para definir uma representação de cadeia de caracteres personalizada do valor de um objeto.Overriding the Object.ToString method to define a custom string representation of an object’s value. Para obter mais informações, veja a seção Substituindo o método ToString mais adiante neste tópico.For more information, see the Overriding the ToString Method section later in this topic.

  • A definição dos especificadores de formato que permitem que a representação de cadeia de caracteres do valor de um objeto assuma várias formas.Defining format specifiers that enable the string representation of an object’s value to take multiple forms. Por exemplo, o especificador de formato "X" na instrução a seguir converte um inteiro na representação de cadeia de caracteres de um valor hexadecimal.For example, the "X" format specifier in the following statement converts an integer to the string representation of a hexadecimal value.

    int integerValue = 60312;
    Console.WriteLine(integerValue.ToString("X"));   // Displays EB98.
    
    Dim integerValue As Integer = 60312
    Console.WriteLine(integerValue.ToString("X"))   ' Displays EB98.
    

    Para obter mais informações sobre especificadores de formato, veja a seção Cadeias de caracteres de formato e método ToString.For more information about format specifiers, see the ToString Method and Format Strings section.

  • O uso de provedores de formato para aproveitar as convenções de formatação de uma cultura específica.Using format providers to take advantage of the formatting conventions of a specific culture. Por exemplo, a instrução a seguir exibe um valor de moeda usando as convenções de formatação da cultura en-US.For example, the following statement displays a currency value by using the formatting conventions of the en-US culture.

    double cost = 1632.54; 
    Console.WriteLine(cost.ToString("C", 
                      new System.Globalization.CultureInfo("en-US")));   
    // The example displays the following output:
    //       $1,632.54
    
    Dim cost As Double = 1632.54
    Console.WriteLine(cost.ToString("C", New System.Globalization.CultureInfo("en-US")))
    ' The example displays the following output:
    '       $1,632.54
    

    Para obter mais informações sobre a formatação com provedores de formato, consulte a seção Provedores de formato e a interface IFormatProvider.For more information about formatting with format providers, see the Format Providers and the IFormatProvider Interface section.

  • A implementação da interface IFormattable para dar suporte tanto à conversão de cadeia de caracteres com a classe Convert quanto à formatação de composição.Implementing the IFormattable interface to support both string conversion with the Convert class and composite formatting. Para obter mais informações, consulte a seção Interface IFormattable.For more information, see the IFormattable Interface section.

  • O uso da formatação de composição para inserir a representação de cadeia de caracteres de um valor em uma cadeia de caracteres maior.Using composite formatting to embed the string representation of a value in a larger string. Para obter mais informações, veja a seção Formatação composição.For more information, see the Composite Formatting section.

  • Implementando ICustomFormatter e IFormatProvider para fornecer uma solução completa de formatação personalizada.Implementing ICustomFormatter and IFormatProvider to provide a complete custom formatting solution. Para obter mais informações, veja a seção Formatação personalizada com ICustomFormatter.For more information, see the Custom Formatting with ICustomFormatter section.

As seções a seguir examinam esses métodos para converter um objeto em sua representação de cadeia de caracteres.The following sections examine these methods for converting an object to its string representation.

Formatação padrão usando o método ToStringDefault Formatting Using the ToString Method

Cada tipo é derivado de System.Object herda automaticamente um método ToString sem parâmetros, que retorna o nome do tipo por padrão.Every type that is derived from System.Object automatically inherits a parameterless ToString method, which returns the name of the type by default. O exemplo a seguir ilustra o método ToString padrão.The following example illustrates the default ToString method. Ele define uma classe chamada Automobile que não tem nenhuma implementação.It defines a class named Automobile that has no implementation. Quando a classe é instanciada e seu método ToString é chamado, ele exibe seu nome de tipo.When the class is instantiated and its ToString method is called, it displays its type name. Observe que o método ToString não é chamado explicitamente no exemplo.Note that the ToString method is not explicitly called in the example. O método Console.WriteLine(Object) chama implicitamente o método ToString do objeto é passado para ele como um argumento.The Console.WriteLine(Object) method implicitly calls the ToString method of the object passed to it as an argument.

using System;

public class Automobile
{
   // No implementation. All members are inherited from Object.
}

public class Example
{
   public static void Main()
   {
      Automobile firstAuto = new Automobile();
      Console.WriteLine(firstAuto);
   }
}
// The example displays the following output:
//       Automobile
Public Class Automobile
   ' No implementation. All members are inherited from Object.
End Class

Module Example
   Public Sub Main()
      Dim firstAuto As New Automobile()
      Console.WriteLine(firstAuto)
   End Sub
End Module
' The example displays the following output:
'       Automobile

Aviso

A partir do Windows 8.1Windows 8.1, o Windows Runtime inclui uma interface IStringable com um único método, IStringable.ToString, que fornece suporte à formatação padrão.Starting with Windows 8.1Windows 8.1, the Windows Runtime includes an IStringable interface with a single method, IStringable.ToString, which provides default formatting support. No entanto, recomendamos que tipos gerenciados não implementem a interface IStringable.However, we recommend that managed types do not implement the IStringable interface. Para obter mais informações, veja a seção "Windows Runtime e a Interface IStringable" na página de referência Object.ToString.For more information, see "The Windows Runtime and the IStringable Interface" section on the Object.ToString reference page.

Já que todos os tipos, com a exceção das interfaces, são derivados de Object, essa funcionalidade é fornecida automaticamente para suas estruturas ou classes personalizadas.Because all types other than interfaces are derived from Object, this functionality is automatically provided to your custom classes or structures. No entanto, a funcionalidade oferecida pelo método ToString padrão é limitada: Embora identifique o tipo, não fornece nenhuma informação sobre uma instância do tipo.However, the functionality offered by the default ToString method, is limited: Although it identifies the type, it fails to provide any information about an instance of the type. Para fornecer uma representação de cadeia de caracteres de um objeto que fornece informações sobre o objeto, você deve substituir o método ToString.To provide a string representation of an object that provides information about that object, you must override the ToString method.

Observação

As estruturas herdam de ValueType, que por sua vez é derivado de Object.Structures inherit from ValueType, which in turn is derived from Object. Embora ValueType substitua Object.ToString, sua implementação é idêntica.Although ValueType overrides Object.ToString, its implementation is identical.

Substituindo o método ToStringOverriding the ToString Method

A exibição do nome de um tipo é geralmente de uso limitado e não permite que os consumidores dos seus tipos diferenciem uma instância da outra.Displaying the name of a type is often of limited use and does not allow consumers of your types to differentiate one instance from another. No entanto, você pode substituir o método ToString para fornecer uma representação mais útil do valor de um objeto.However, you can override the ToString method to provide a more useful representation of an object’s value. O exemplo a seguir define um objeto Temperature e substitui seu método ToString para exibir a temperatura em graus Celsius.The following example defines a Temperature object and overrides its ToString method to display the temperature in degrees Celsius.

using System;

public class Temperature
{
   private decimal temp;
   
   public Temperature(decimal temperature)
   {
      this.temp = temperature;   
   }

   public override string ToString()
   {
      return this.temp.ToString("N1") + "°C";
   }
}

public class Example
{
   public static void Main()
   {
      Temperature currentTemperature = new Temperature(23.6m);
      Console.WriteLine("The current temperature is " +
                        currentTemperature.ToString());
   }
}
// The example displays the following output:
//       The current temperature is 23.6°C.
Public Class Temperature
   Private temp As Decimal
   
   Public Sub New(temperature As Decimal)
      Me.temp = temperature
   End Sub
   
   Public Overrides Function ToString() As String
      Return Me.temp.ToString("N1") + "°C"   
   End Function
End Class

Module Example
   Public Sub Main()
      Dim currentTemperature As New Temperature(23.6d)
      Console.WriteLine("The current temperature is " +
                        currentTemperature.ToString())
   End Sub
End Module
' The example displays the following output:
'       The current temperature is 23.6°C.

No .NET, o método ToString de cada tipo de valor primitivo foi substituído para exibir o valor do objeto, em vez de seu nome.In .NET, the ToString method of each primitive value type has been overridden to display the object’s value instead of its name. A tabela a seguir mostra a substituição de cada tipo primitivo.The following table shows the override for each primitive type. Observe que a maioria dos métodos substituídos chama outra sobrecarga do método ToString e passa-a ao especificador de formato "G", que define o formato geral de seu tipo, além de um objeto IFormatProvider que representa a cultura atual.Note that most of the overridden methods call another overload of the ToString method and pass it the "G" format specifier, which defines the general format for its type, and an IFormatProvider object that represents the current culture.

TipoType Substituição de ToStringToString override
Boolean Retorna Boolean.TrueString ou Boolean.FalseString.Returns either Boolean.TrueString or Boolean.FalseString.
Byte Chama Byte.ToString("G", NumberFormatInfo.CurrentInfo) para formatar o valor Byte para a cultura atual.Calls Byte.ToString("G", NumberFormatInfo.CurrentInfo) to format the Byte value for the current culture.
Char Retorna o caractere como uma cadeia de caracteres.Returns the character as a string.
DateTime Chama DateTime.ToString("G", DatetimeFormatInfo.CurrentInfo) para formatar o valor de data e hora para a cultura atual.Calls DateTime.ToString("G", DatetimeFormatInfo.CurrentInfo) to format the date and time value for the current culture.
Decimal Chama Decimal.ToString("G", NumberFormatInfo.CurrentInfo) para formatar o valor Decimal para a cultura atual.Calls Decimal.ToString("G", NumberFormatInfo.CurrentInfo) to format the Decimal value for the current culture.
Double Chama Double.ToString("G", NumberFormatInfo.CurrentInfo) para formatar o valor Double para a cultura atual.Calls Double.ToString("G", NumberFormatInfo.CurrentInfo) to format the Double value for the current culture.
Int16 Chama Int16.ToString("G", NumberFormatInfo.CurrentInfo) para formatar o valor Int16 para a cultura atual.Calls Int16.ToString("G", NumberFormatInfo.CurrentInfo) to format the Int16 value for the current culture.
Int32 Chama Int32.ToString("G", NumberFormatInfo.CurrentInfo) para formatar o valor Int32 para a cultura atual.Calls Int32.ToString("G", NumberFormatInfo.CurrentInfo) to format the Int32 value for the current culture.
Int64 Chama Int64.ToString("G", NumberFormatInfo.CurrentInfo) para formatar o valor Int64 para a cultura atual.Calls Int64.ToString("G", NumberFormatInfo.CurrentInfo) to format the Int64 value for the current culture.
SByte Chama SByte.ToString("G", NumberFormatInfo.CurrentInfo) para formatar o valor SByte para a cultura atual.Calls SByte.ToString("G", NumberFormatInfo.CurrentInfo) to format the SByte value for the current culture.
Single Chama Single.ToString("G", NumberFormatInfo.CurrentInfo) para formatar o valor Single para a cultura atual.Calls Single.ToString("G", NumberFormatInfo.CurrentInfo) to format the Single value for the current culture.
UInt16 Chama UInt16.ToString("G", NumberFormatInfo.CurrentInfo) para formatar o valor UInt16 para a cultura atual.Calls UInt16.ToString("G", NumberFormatInfo.CurrentInfo) to format the UInt16 value for the current culture.
UInt32 Chama UInt32.ToString("G", NumberFormatInfo.CurrentInfo) para formatar o valor UInt32 para a cultura atual.Calls UInt32.ToString("G", NumberFormatInfo.CurrentInfo) to format the UInt32 value for the current culture.
UInt64 Chama UInt64.ToString("G", NumberFormatInfo.CurrentInfo) para formatar o valor UInt64 para a cultura atual.Calls UInt64.ToString("G", NumberFormatInfo.CurrentInfo) to format the UInt64 value for the current culture.

As cadeias de caractere de formato e do método ToStringThe ToString Method and Format Strings

Contar com o método padrão ToString ou substituir ToString é apropriado quando um objeto tem uma única representação de cadeia de caracteres.Relying on the default ToString method or overriding ToString is appropriate when an object has a single string representation. No entanto, o valor de um objeto normalmente tem várias representações.However, the value of an object often has multiple representations. Por exemplo, uma temperatura pode ser expressa em graus Fahrenheit, graus Celsius ou kelvins.For example, a temperature can be expressed in degrees Fahrenheit, degrees Celsius, or kelvins. De forma similar, o valor de inteiro 10 pode ser representado de várias maneiras, incluindo 10, 10,0, 1.0e01 ou US $10,00.Similarly, the integer value 10 can be represented in numerous ways, including 10, 10.0, 1.0e01, or $10.00.

Para permitir que um único valor tenha várias representações de cadeia de caracteres, o .NET usa cadeias de caracteres de formato.To enable a single value to have multiple string representations, .NET uses format strings. Uma cadeia de caracteres de formato é uma cadeia de caracteres que contém um ou mais especificadores de formato predefinidos, que são caracteres únicos ou grupos de caracteres que definem como o método ToString deve formatar sua saída.A format string is a string that contains one or more predefined format specifiers, which are single characters or groups of characters that define how the ToString method should format its output. A cadeia de caracteres de formato é passada como um parâmetro para o método ToString do objeto e determina como a representação de cadeia de caracteres do valor do objeto deve ser exibida.The format string is then passed as a parameter to the object's ToString method and determines how the string representation of that object's value should appear.

Todos os tipos numéricos, de data e hora e tipos de enumeração no .NET dão suporte a um conjunto predefinido de especificadores de formato.All numeric types, date and time types, and enumeration types in .NET support a predefined set of format specifiers. Você também pode usar cadeias de caracteres de formato para definir várias representações de cadeia de caracteres de seus tipos de dados definidos pelo aplicativo.You can also use format strings to define multiple string representations of your application-defined data types.

Cadeias de caracteres de formato padrãoStandard Format Strings

Uma cadeia de caracteres de formato padrão contém um único especificador de formato, que é um caractere alfabético que define a representação de cadeia de caracteres do objeto ao qual ela é aplicada, junto com um especificador de precisão opcional que afeta a quantos dígitos serão exibidos na cadeia de caracteres de resultado.A standard format string contains a single format specifier, which is an alphabetic character that defines the string representation of the object to which it is applied, along with an optional precision specifier that affects how many digits are displayed in the result string. Se o especificador de precisão for omitido ou não houver suporte a ele, um especificador de formato padrão será equivalente a uma cadeia de caracteres de formato padrão.If the precision specifier is omitted or is not supported, a standard format specifier is equivalent to a standard format string.

O .NET define um conjunto de especificadores de formato padrão para todos os tipos numéricos, todos os tipos de data e hora e todos os tipos de enumeração..NET defines a set of standard format specifiers for all numeric types, all date and time types, and all enumeration types. Por exemplo, cada uma dessas categorias dá suporte a um especificador de formato padrão "G", que define uma representação de cadeia de caracteres geral de um valor desse mesmo tipo.For example, each of these categories supports a "G" standard format specifier, which defines a general string representation of a value of that type.

Cadeias de caracteres de formato padrão para tipos de enumeração controlam diretamente a representação de cadeia de caracteres de um valor.Standard format strings for enumeration types directly control the string representation of a value. As cadeias de caracteres de formato passadas para o método ToString de um valor de enumeração determinam se o valor é exibido usando seu nome de cadeia de caracteres (especificadores de formato "G" e "F"), seu valor integral subjacente (o especificador de formato "D") ou seu valor hexadecimal (o especificador de formato "X").The format strings passed to an enumeration value’s ToString method determine whether the value is displayed using its string name (the "G" and "F" format specifiers), its underlying integral value (the "D" format specifier), or its hexadecimal value (the "X" format specifier). O exemplo a seguir ilustra o uso de cadeias de caracteres de formato padrão para formatar um valor de enumeração DayOfWeek.The following example illustrates the use of standard format strings to format a DayOfWeek enumeration value.

DayOfWeek thisDay = DayOfWeek.Monday;
string[] formatStrings = {"G", "F", "D", "X"};

foreach (string formatString in formatStrings)
   Console.WriteLine(thisDay.ToString(formatString));
// The example displays the following output:
//       Monday
//       Monday
//       1
//       00000001
Dim thisDay As DayOfWeek = DayOfWeek.Monday
Dim formatStrings() As String = {"G", "F", "D", "X"}

For Each formatString As String In formatStrings
   Console.WriteLine(thisDay.ToString(formatString))
Next
' The example displays the following output:
'       Monday
'       Monday
'       1
'       00000001

Para obter informações sobre cadeias de caracteres de formato de enumeração, veja Cadeias de caracteres de formato de enumeração.For information about enumeration format strings, see Enumeration Format Strings.

Cadeias de caracteres de formato padrão para tipos numéricos geralmente definem uma cadeia de caracteres de resultado cuja aparência exata é controlada por um ou mais valores de propriedade.Standard format strings for numeric types usually define a result string whose precise appearance is controlled by one or more property values. Por exemplo, o especificador de formato "C" formata um número como um valor de moeda.For example, the "C" format specifier formats a number as a currency value. Quando você chama o método ToString com o especificador de formato "C" como o único parâmetro, os seguintes valores de propriedade do objeto NumberFormatInfo da cultura atual são usados para definir a representação de cadeia de caracteres do valor numérico:When you call the ToString method with the "C" format specifier as the only parameter, the following property values from the current culture’s NumberFormatInfo object are used to define the string representation of the numeric value:

  • A propriedade CurrencySymbol, que especifica o símbolo da moeda da cultura atual.The CurrencySymbol property, which specifies the current culture’s currency symbol.

  • A propriedade CurrencyNegativePattern ou CurrencyPositivePattern, que retorna um inteiro que determina o seguinte:The CurrencyNegativePattern or CurrencyPositivePattern property, which returns an integer that determines the following:

    • O posicionamento do símbolo da moeda.The placement of the currency symbol.

    • Se valores negativos são indicados por um sinal de negativo à esquerda, um sinal de negativo à direita ou parênteses.Whether negative values are indicated by a leading negative sign, a trailing negative sign, or parentheses.

    • Se um espaço é ou não exibido entre o valor numérico e o símbolo da moeda.Whether a space appears between the numeric value and the currency symbol.

  • A propriedade CurrencyDecimalDigits, que define o número de dígitos fracionários na cadeia de caracteres de resultado.The CurrencyDecimalDigits property, which defines the number of fractional digits in the result string.

  • O propriedade CurrencyDecimalSeparator, que define o símbolo do separador decimal na cadeia de caracteres de resultado.The CurrencyDecimalSeparator property, which defines the decimal separator symbol in the result string.

  • A propriedade CurrencyGroupSeparator, que define o símbolo de separador de grupo.The CurrencyGroupSeparator property, which defines the group separator symbol.

  • A propriedade CurrencyGroupSizes, que define o número de dígitos em cada grupo à esquerda da vírgula decimal.The CurrencyGroupSizes property, which defines the number of digits in each group to the left of the decimal.

  • A propriedade NegativeSign, que determinará o sinal de negativo usado na cadeia de caracteres de resultado se parênteses não forem usados para indicar valores negativos.The NegativeSign property, which determines the negative sign used in the result string if parentheses are not used to indicate negative values.

Além disso, cadeias de caracteres de formato numérico podem incluir um especificador de precisão.In addition, numeric format strings may include a precision specifier. O significado desse especificador depende da cadeia de caracteres de formato com o qual ele é usado, mas ele normalmente indica o número total de dígitos ou o número de dígitos fracionários que devem aparecer na cadeia de caracteres de resultado.The meaning of this specifier depends on the format string with which it is used, but it typically indicates either the total number of digits or the number of fractional digits that should appear in the result string. Por exemplo, o exemplo a seguir usa a cadeia de caracteres numérica padrão "X4" e um especificador de precisão para criar um valor de cadeia de caracteres com quatro dígitos hexadecimais.For example, the following example uses the "X4" standard numeric string and a precision specifier to create a string value that has four hexadecimal digits.

byte[] byteValues = { 12, 163, 255 };
foreach (byte byteValue in byteValues)
   Console.WriteLine(byteValue.ToString("X4"));
// The example displays the following output:
//       000C
//       00A3
//       00FF
Dim byteValues() As Byte = { 12, 163, 255 }
For Each byteValue As Byte In byteValues
   Console.WriteLine(byteValue.ToString("X4"))
Next
' The example displays the following output:
'       000C
'       00A3
'       00FF

Para obter mais informações sobre cadeias de caracteres de formatação numérica de padrão, veja Cadeias de caracteres de formato numérico padrão.For more information about standard numeric formatting strings, see Standard Numeric Format Strings.

Cadeias de caracteres de formato padrão para valores de data e hora são aliases para cadeias de caracteres de formato personalizado armazenadas por uma propriedade DateTimeFormatInfo particular.Standard format strings for date and time values are aliases for custom format strings stored by a particular DateTimeFormatInfo property. Por exemplo, chamar o método ToString de um valor de data e hora com o especificador de formato "D" exibe a data e hora por meio do uso da cadeia de caracteres de formato personalizado armazenada na propriedade DateTimeFormatInfo.LongDatePattern da cultura atual.For example, calling the ToString method of a date and time value with the "D" format specifier displays the date and time by using the custom format string stored in the current culture’s DateTimeFormatInfo.LongDatePattern property. (Para obter mais informações sobre cadeias de caracteres de formato personalizado, consulte a próxima seção.) O exemplo a seguir ilustra essa relação.(For more information about custom format strings, see the next section.) The following example illustrates this relationship.

using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {
      DateTime date1 = new DateTime(2009, 6, 30);
      Console.WriteLine("D Format Specifier:     {0:D}", date1);
      string longPattern = CultureInfo.CurrentCulture.DateTimeFormat.LongDatePattern;
      Console.WriteLine("'{0}' custom format string:     {1}", 
                        longPattern, date1.ToString(longPattern));
   }
}
// The example displays the following output when run on a system whose
// current culture is en-US:
//    D Format Specifier:     Tuesday, June 30, 2009
//    'dddd, MMMM dd, yyyy' custom format string:     Tuesday, June 30, 2009
Imports System.Globalization

Module Example
   Public Sub Main()
      Dim date1 As Date = #6/30/2009#
      Console.WriteLine("D Format Specifier:     {0:D}", date1)
      Dim longPattern As String = CultureInfo.CurrentCulture.DateTimeFormat.LongDatePattern
      Console.WriteLine("'{0}' custom format string:     {1}", _
                        longPattern, date1.ToString(longPattern))
   End Sub
End Module
' The example displays the following output when run on a system whose
' current culture is en-US:
'    D Format Specifier:     Tuesday, June 30, 2009
'    'dddd, MMMM dd, yyyy' custom format string:     Tuesday, June 30, 2009

Para obter mais informações sobre o padrão de data e cadeias de caracteres de formato de hora, veja Cadeias de caracteres de formato de data e hora padrão.For more information about standard date and time format strings, see Standard Date and Time Format Strings.

Você também pode usar cadeias de caracteres de formato padrão para definir a representação de cadeia de caracteres de um objeto definido pelo aplicativo que é produzido pelo método ToString(String) do objeto.You can also use standard format strings to define the string representation of an application-defined object that is produced by the object’s ToString(String) method. Você pode definir os especificadores de formato padrão específicos que dão suporte a seu objeto e você pode determinar se eles diferenciam ou não maiúsculas de minúsculas.You can define the specific standard format specifiers that your object supports, and you can determine whether they are case-sensitive or case-insensitive. A implementação do ToString(String) método deve dar suporte ao seguinte:Your implementation of the ToString(String) method should support the following:

  • Um especificador de formato "G" que representa um formato comum ou habitual do objeto.A "G" format specifier that represents a customary or common format of the object. A sobrecarga sem parâmetros do método ToString de seu objeto deve chamar sua sobrecarga ToString(String) e passar cadeia de caracteres de formato padrão "G".The parameterless overload of your object's ToString method should call its ToString(String) overload and pass it the "G" standard format string.

  • Suporte para um especificador de formato que é igual a uma referência nula (Nothing em Visual Basic).Support for a format specifier that is equal to a null reference (Nothing in Visual Basic). Um especificador de formato igual a uma referência nula deve ser considerado equivalente ao especificador de formato "G".A format specifier that is equal to a null reference should be considered equivalent to the "G" format specifier.

Por exemplo, um Temperature classe interna pode armazenar a temperatura em graus Celsius e usar especificadores de formato para representar o valor do objeto Temperature em graus Fahrenheit, graus Celsius e kelvins.For example, a Temperature class can internally store the temperature in degrees Celsius and use format specifiers to represent the value of the Temperature object in degrees Celsius, degrees Fahrenheit, and kelvins. O exemplo a seguir fornece uma ilustração.The following example provides an illustration.

using System;

public class Temperature
{
   private decimal m_Temp;
   
   public Temperature(decimal temperature)
   {
      this.m_Temp = temperature;
   }
   
   public decimal Celsius
   {
      get { return this.m_Temp; }
   }
   
   public decimal Kelvin
   {
      get { return this.m_Temp + 273.15m; }   
   }
   
   public decimal Fahrenheit
   {
      get { return Math.Round(((decimal) (this.m_Temp * 9 / 5 + 32)), 2); }
   }

   public override string ToString()
   {
      return this.ToString("C");
   }
   
   public string ToString(string format)
   {  
      // Handle null or empty string.
      if (String.IsNullOrEmpty(format)) format = "C";
      // Remove spaces and convert to uppercase.
      format = format.Trim().ToUpperInvariant();      
      
      // Convert temperature to Fahrenheit and return string.
      switch (format)
      {
         // Convert temperature to Fahrenheit and return string.
         case "F":
            return this.Fahrenheit.ToString("N2") + " °F";
         // Convert temperature to Kelvin and return string.
         case "K":
            return this.Kelvin.ToString("N2") + " K";
         // return temperature in Celsius.
         case "G":
         case "C":
            return this.Celsius.ToString("N2") + " °C";
         default:
            throw new FormatException(String.Format("The '{0}' format string is not supported.", format));
      }      
   }
}

public class Example
{
   public static void Main()
   {
      Temperature temp1 = new Temperature(0m);
      Console.WriteLine(temp1.ToString());
      Console.WriteLine(temp1.ToString("G"));
      Console.WriteLine(temp1.ToString("C"));
      Console.WriteLine(temp1.ToString("F"));
      Console.WriteLine(temp1.ToString("K"));

      Temperature temp2 = new Temperature(-40m);
      Console.WriteLine(temp2.ToString());
      Console.WriteLine(temp2.ToString("G"));
      Console.WriteLine(temp2.ToString("C"));
      Console.WriteLine(temp2.ToString("F"));
      Console.WriteLine(temp2.ToString("K"));

      Temperature temp3 = new Temperature(16m);
      Console.WriteLine(temp3.ToString());
      Console.WriteLine(temp3.ToString("G"));
      Console.WriteLine(temp3.ToString("C"));
      Console.WriteLine(temp3.ToString("F"));
      Console.WriteLine(temp3.ToString("K"));
      
      Console.WriteLine(String.Format("The temperature is now {0:F}.", temp3));
   }
}
// The example displays the following output:
//       0.00 °C
//       0.00 °C
//       0.00 °C
//       32.00 °F
//       273.15 K
//       -40.00 °C
//       -40.00 °C
//       -40.00 °C
//       -40.00 °F
//       233.15 K
//       16.00 °C
//       16.00 °C
//       16.00 °C
//       60.80 °F
//       289.15 K
//       The temperature is now 16.00 °C.
Public Class Temperature
   Private m_Temp As Decimal
   
   Public Sub New(temperature As Decimal)
      Me.m_Temp = temperature
   End Sub
   
   Public ReadOnly Property Celsius() As Decimal
      Get
         Return Me.m_Temp
      End Get   
   End Property
   
   Public ReadOnly Property Kelvin() As Decimal
      Get
         Return Me.m_Temp + 273.15d   
      End Get
   End Property
   
   Public ReadOnly Property Fahrenheit() As Decimal
      Get
         Return Math.Round(CDec(Me.m_Temp * 9 / 5 + 32), 2)
      End Get      
   End Property

   Public Overrides Function ToString() As String
      Return Me.ToString("C")
   End Function
   
   Public Overloads Function ToString(format As String) As String  
      ' Handle null or empty string.
      If String.IsNullOrEmpty(format) Then format = "C"
      ' Remove spaces and convert to uppercase.
      format = format.Trim().ToUpperInvariant()      
      
      Select Case format
         Case "F"
           ' Convert temperature to Fahrenheit and return string.
            Return Me.Fahrenheit.ToString("N2") & " °F"
         Case "K"
            ' Convert temperature to Kelvin and return string.
            Return Me.Kelvin.ToString("N2") & " K"
         Case "C", "G"
            ' Return temperature in Celsius.
            Return Me.Celsius.ToString("N2") & " °C"
         Case Else
            Throw New FormatException(String.Format("The '{0}' format string is not supported.", format))
      End Select      
   End Function
End Class

Public Module Example
   Public Sub Main()
      Dim temp1 As New Temperature(0d)
      Console.WriteLine(temp1.ToString())
      Console.WriteLine(temp1.ToString("G"))
      Console.WriteLine(temp1.ToString("C"))
      Console.WriteLine(temp1.ToString("F"))
      Console.WriteLine(temp1.ToString("K"))

      Dim temp2 As New Temperature(-40d)
      Console.WriteLine(temp2.ToString())
      Console.WriteLine(temp2.ToString("G"))
      Console.WriteLine(temp2.ToString("C"))
      Console.WriteLine(temp2.ToString("F"))
      Console.WriteLine(temp2.ToString("K"))

      Dim temp3 As New Temperature(16d)
      Console.WriteLine(temp3.ToString())
      Console.WriteLine(temp3.ToString("G"))
      Console.WriteLine(temp3.ToString("C"))
      Console.WriteLine(temp3.ToString("F"))
      Console.WriteLine(temp3.ToString("K"))
      
      Console.WriteLine(String.Format("The temperature is now {0:F}.", temp3))
   End Sub
End Module
' The example displays the following output:
'       0.00 °C
'       0.00 °C
'       0.00 °C
'       32.00 °F
'       273.15 K
'       -40.00 °C
'       -40.00 °C
'       -40.00 °C
'       -40.00 °F
'       233.15 K
'       16.00 °C
'       16.00 °C
'       16.00 °C
'       60.80 °F
'       289.15 K
'       The temperature is now 16.00 °C.

Cadeias de caracteres de formato personalizadoCustom Format Strings

Além de cadeias de caracteres de formato padrão, o .NET define cadeias de caracteres de formato personalizado para valores numéricos e valores de data e hora.In addition to the standard format strings, .NET defines custom format strings for both numeric values and date and time values. Uma cadeia de caracteres de formato personalizado consiste em um ou mais especificadores de formato personalizado que definem a representação de cadeia de caracteres de um valor.A custom format string consists of one or more custom format specifiers that define the string representation of a value. Por exemplo, a cadeia de caracteres de formato de data e hora personalizada "aaaa/mm/dd hh:mm:ss.ffff t zzz" converte uma data em sua representação de cadeia de caracteres no formato "2008/11/15 07:45:00.0000 P -08:00" para a cultura en-US.For example, the custom date and time format string "yyyy/mm/dd hh:mm:ss.ffff t zzz" converts a date to its string representation in the form "2008/11/15 07:45:00.0000 P -08:00" for the en-US culture. Da mesma forma, a cadeia de caracteres de formato personalizado "0000" converte o valor inteiro 12 em "0012".Similarly, the custom format string "0000" converts the integer value 12 to "0012". Para obter uma lista completa de cadeias de caracteres de formato personalizado, veja Cadeias de caracteres de formato de data e hora personalizado e Cadeias de caracteres de formato numérico personalizado.For a complete list of custom format strings, see Custom Date and Time Format Strings and Custom Numeric Format Strings.

Se uma cadeia de caracteres de formato consiste em um único especificador de formato personalizado, o especificador de formato deve ser precedido pelo símbolo de porcentagem (%) para evitar confusão com um especificador de formato padrão.If a format string consists of a single custom format specifier, the format specifier should be preceded by the percent (%) symbol to avoid confusion with a standard format specifier. O exemplo a seguir usa o especificador de formato personalizado "M" para exibir um número de um ou dois dígitos do mês de uma data específica.The following example uses the "M" custom format specifier to display a one-digit or two-digit number of the month of a particular date.

DateTime date1 = new DateTime(2009, 9, 8);
Console.WriteLine(date1.ToString("%M"));       // Displays 9
Dim date1 As Date = #09/08/2009#
Console.WriteLine(date1.ToString("%M"))      ' Displays 9

Muitas cadeias de caracteres de formato padrão para valores de data e hora são aliases para cadeias de caracteres de formato personalizado que são definidas pelas propriedades do objeto DateTimeFormatInfo.Many standard format strings for date and time values are aliases for custom format strings that are defined by properties of the DateTimeFormatInfo object. Cadeias de caracteres de formato personalizado também oferecem flexibilidade considerável no fornecimento de formação definida pelo aplicativo para valores numéricos ou valores de data e hora.Custom format strings also offer considerable flexibility in providing application-defined formatting for numeric values or date and time values. Você pode definir suas próprias cadeias de caracteres de resultado personalizadas para valores numéricos e valores de data e hora combinando vários especificadores de formato personalizado em uma única cadeia de caracteres de formato personalizado.You can define your own custom result strings for both numeric values and date and time values by combining multiple custom format specifiers into a single custom format string. O exemplo a seguir define uma cadeia de caracteres de formato personalizado que exibe o dia da semana entre parênteses após o nome do mês, o dia e o ano.The following example defines a custom format string that displays the day of the week in parentheses after the month name, day, and year.

string customFormat = "MMMM dd, yyyy (dddd)";
DateTime date1 = new DateTime(2009, 8, 28);
Console.WriteLine(date1.ToString(customFormat));   
// The example displays the following output if run on a system
// whose language is English:
//       August 28, 2009 (Friday)      
Dim customFormat As String = "MMMM dd, yyyy (dddd)"
Dim date1 As Date = #8/28/2009#
Console.WriteLine(date1.ToString(customFormat))   
' The example displays the following output if run on a system
' whose language is English:
'       August 28, 2009 (Friday)      

O exemplo a seguir define uma cadeia de caracteres de formato personalizado que exibe um valor Int64 como um número de telefone de sete dígitos padrão dos EUA, junto com seu código de área.The following example defines a custom format string that displays an Int64 value as a standard, seven-digit U.S. telephone number along with its area code.

using System;

public class Example
{
   public static void Main()
   {
      long number = 8009999999;
      string fmt = "000-000-0000";
      Console.WriteLine(number.ToString(fmt));
   }
}
// The example displays the following output:
//        800-999-9999
Module Example
   Public Sub Main()
      Dim number As Long = 8009999999
      Dim fmt As String = "000-000-0000"
      Console.WriteLine(number.ToString(fmt))
   End Sub
End Module
' The example displays the following output:

' The example displays the following output:
'       800-999-9999

Embora as cadeias de caracteres de formato padrão geralmente tratem da maioria das necessidades de formatação para os tipos definidos pelo aplicativo, você também pode definir especificadores de formato personalizado para formatar seus tipos.Although standard format strings can generally handle most of the formatting needs for your application-defined types, you may also define custom format specifiers to format your types.

Cadeias de caracteres de formato e tipos do .NETFormat Strings and .NET Types

Todos os tipos numéricos (ou seja, os tipos Byte, Decimal, Double, Int16, Int32, Int64, SByte, Single, UInt16, UInt32, UInt64 e BigInteger), bem como o DateTime, DateTimeOffset, TimeSpan, Guid, e todos os tipos de enumeração, suportam a formatação com cadeias de caracteres de formato.All numeric types (that is, the Byte, Decimal, Double, Int16, Int32, Int64, SByte, Single, UInt16, UInt32, UInt64, and BigInteger types), as well as the DateTime, DateTimeOffset, TimeSpan, Guid, and all enumeration types, support formatting with format strings. Para obter informações sobre as cadeias de caracteres de formato específicas às quais cada tipo dá suporte, veja os seguintes tópicos:For information on the specific format strings supported by each type, see the following topics:

TítuloTitle DefiniçãoDefinition
Cadeias de Caracteres de Formato Numérico PadrãoStandard Numeric Format Strings Descreve cadeias de caracteres de formato padrão que criam representações de cadeia de caracteres de valores numéricos frequentemente usadas.Describes standard format strings that create commonly used string representations of numeric values.
Cadeias de caracteres de formato numérico personalizadoCustom Numeric Format Strings Descreve cadeias de caracteres de formato personalizado que criam formatos específicos de aplicativo para valores numéricos.Describes custom format strings that create application-specific formats for numeric values.
Cadeias de caracteres de formato de data e hora padrãoStandard Date and Time Format Strings Descreve cadeias de caracteres de formato padrão que criam representações de cadeia de caracteres de valores DateTime e DateTimeOffset frequentemente usadas.Describes standard format strings that create commonly used string representations of DateTime and DateTimeOffset values.
Cadeias de caracteres de formato de data e hora personalizadoCustom Date and Time Format Strings Descreve cadeias de caracteres de formato personalizado que criam formatos específicos de aplicativo para valores DateTime e DateTimeOffset.Describes custom format strings that create application-specific formats for DateTime and DateTimeOffset values.
Cadeias de caracteres de formato TimeSpan padrãoStandard TimeSpan Format Strings Descreve cadeias de caracteres de formato padrão que criam representações de intervalos de tempo frequentemente usadas.Describes standard format strings that create commonly used string representations of time intervals.
Cadeias de caracteres de formato TimeSpan personalizadoCustom TimeSpan Format Strings Descreve cadeias de caracteres de formato personalizado que criam formatos específicos de aplicativo para intervalos de tempo.Describes custom format strings that create application-specific formats for time intervals.
Cadeias de Caracteres de Formato de EnumeraçãoEnumeration Format Strings Descreve cadeias de caracteres de formato padrão que são usadas para criar representações de cadeia de caracteres de valores de enumeração.Describes standard format strings that are used to create string representations of enumeration values.
Guid.ToString(String) Descreve cadeias de caracteres de formato padrão para valores Guid.Describes standard format strings for Guid values.

Formatação que leva em conta a cultura com provedores de formato e a interface IFormatProviderCulture-Sensitive Formatting with Format Providers and the IFormatProvider Interface

Embora os especificadores de formato permitam personalizar a formatação de objetos, a produção de uma representação de cadeia de caracteres de objetos significativa geralmente requer informações de formatação adicionais.Although format specifiers let you customize the formatting of objects, producing a meaningful string representation of objects often requires additional formatting information. Por exemplo, formatar um número como um valor de moeda usando a cadeia de caracteres de formato padrão "C" ou então uma cadeia de caracteres de formato personalizado como "$ #,#.00" requer que, no mínimo, informações sobre o símbolo correto da moeda, o separador de grupo e o separador decimal estejam disponíveis para inclusão na cadeia de caracteres formatada.For example, formatting a number as a currency value by using either the "C" standard format string or a custom format string such as "$ #,#.00" requires, at a minimum, information about the correct currency symbol, group separator, and decimal separator to be available to include in the formatted string. No .NET, essas informações de formatação adicionais são disponibilizadas por meio da interface IFormatProvider, que é fornecida como um parâmetro para um ou mais sobrecargas do método ToString de tipos numéricos e tipos de data e hora.In .NET, this additional formatting information is made available through the IFormatProvider interface, which is provided as a parameter to one or more overloads of the ToString method of numeric types and date and time types. Implementações IFormatProvider são usadas em .NET para dar suporte à formatação específica à cultura.IFormatProvider implementations are used in .NET to support culture-specific formatting. O exemplo a seguir ilustra como a representação de cadeia de caracteres de um objeto é alterado quando ele é formatado com três objetos IFormatProvider que representam diferentes culturas.The following example illustrates how the string representation of an object changes when it is formatted with three IFormatProvider objects that represent different cultures.

using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {
      decimal value = 1603.42m;
      Console.WriteLine(value.ToString("C3", new CultureInfo("en-US")));
      Console.WriteLine(value.ToString("C3", new CultureInfo("fr-FR")));
      Console.WriteLine(value.ToString("C3", new CultureInfo("de-DE")));
   }
}
// The example displays the following output:
//       $1,603.420
//       1 603,420 €
//       1.603,420 €
Imports System.Globalization

Public Module Example
   Public Sub Main()
      Dim value As Decimal = 1603.42d
      Console.WriteLine(value.ToString("C3", New CultureInfo("en-US")))
      Console.WriteLine(value.ToString("C3", New CultureInfo("fr-FR")))
      Console.WriteLine(value.ToString("C3", New CultureInfo("de-DE")))
   End Sub
End Module
' The example displays the following output:
'       $1,603.420
'       1 603,420 €
'       1.603,420 €

A interface IFormatProvider inclui um método, GetFormat(Type), que tem um único parâmetro que especifica o tipo de objeto que fornece informações de formatação.The IFormatProvider interface includes one method, GetFormat(Type), which has a single parameter that specifies the type of object that provides formatting information. Se o método puder fornecer um objeto desse tipo, ele retornará esse objeto.If the method can provide an object of that type, it returns it. Caso contrário, ele retornará uma referência nula (Nothing em Visual Basic).Otherwise, it returns a null reference (Nothing in Visual Basic).

IFormatProvider.GetFormat é um método de retorno de chamada.IFormatProvider.GetFormat is a callback method. Quando você chama uma sobrecarga do método ToString que inclui um parâmetro IFormatProvider, ela chama o método GetFormat daquele objeto IFormatProvider.When you call a ToString method overload that includes an IFormatProvider parameter, it calls the GetFormat method of that IFormatProvider object. O método GetFormat é responsável por retornar um objeto que fornece as informações de formatação necessárias, conforme especificadas pelo seu parâmetro formatType para o método ToString.The GetFormat method is responsible for returning an object that provides the necessary formatting information, as specified by its formatType parameter, to the ToString method.

Um número de métodos de conversão de cadeia de caracteres ou formatação inclui um parâmetro de tipo IFormatProvider, mas em muitos casos o valor do parâmetro é ignorado quando o método é chamado.A number of formatting or string conversion methods include a parameter of type IFormatProvider, but in many cases the value of the parameter is ignored when the method is called. A tabela a seguir lista alguns dos métodos de formatação que usam o parâmetro e o tipo do objeto Type que passam para o método IFormatProvider.GetFormat.The following table lists some of the formatting methods that use the parameter and the type of the Type object that they pass to the IFormatProvider.GetFormat method.

MétodoMethod Tipo de parâmetro formatTypeType of formatType parameter
ToString método de tipos numéricosToString method of numeric types System.Globalization.NumberFormatInfo
ToString método de tipos de data e horaToString method of date and time types System.Globalization.DateTimeFormatInfo
String.Format System.ICustomFormatter
StringBuilder.AppendFormat System.ICustomFormatter

Observação

Os métodos ToString dos tipos numéricos e dos tipos de data e hora estão sobrecarregados, e somente algumas das sobrecargas incluem um parâmetro IFormatProvider.The ToString methods of the numeric types and date and time types are overloaded, and only some of the overloads include an IFormatProvider parameter. Se um método não tiver um parâmetro do tipo IFormatProvider, o objeto retornado pela propriedade CultureInfo.CurrentCulture será passado.If a method does not have a parameter of type IFormatProvider, the object that is returned by the CultureInfo.CurrentCulture property is passed instead. Por exemplo, uma chamada para o método Int32.ToString() padrão acaba resultando em uma chamada de método como esta: Int32.ToString("G", System.Globalization.CultureInfo.CurrentCulture).For example, a call to the default Int32.ToString() method ultimately results in a method call such as the following: Int32.ToString("G", System.Globalization.CultureInfo.CurrentCulture).

O .NET fornece três classes que implementam IFormatProvider:.NET provides three classes that implement IFormatProvider:

Você também pode implementar seu próprio provedor de formato para substituir qualquer uma dessas classes.You can also implement your own format provider to replace any one of these classes. No entanto, se o seu método GetFormat de sua implementação precisar fornecer informações de formatação ao método ToString, ele deverá retornar um objeto do tipo listado na tabela anterior.However, your implementation’s GetFormat method must return an object of the type listed in the previous table if it has to provide formatting information to the ToString method.

Formatação de valores numéricos que leva em conta a culturaCulture-Sensitive Formatting of Numeric Values

Por padrão, a formatação de valores numéricos leva em conta a cultura.By default, the formatting of numeric values is culture-sensitive. Se você não especificar uma cultura quando chamar um método de formatação, as convenções de formatação da cultura do thread atual serão usadas.If you do not specify a culture when you call a formatting method, the formatting conventions of the current thread culture are used. Isso é ilustrado no exemplo a seguir, que altera a cultura do thread atual quatro vezes e, em seguida, chama o método Decimal.ToString(String).This is illustrated in the following example, which changes the current thread culture four times and then calls the Decimal.ToString(String) method. Em cada caso, a cadeia de caracteres de resultado reflete as convenções de formatação da cultura atual.In each case, the result string reflects the formatting conventions of the current culture. Isso ocorre porque os métodos ToString e ToString(String) encapsulam chamadas para o método ToString(String, IFormatProvider) de cada tipo numérico.This is because the ToString and ToString(String) methods wrap calls to each numeric type's ToString(String, IFormatProvider) method.

using System;
using System.Globalization;
using System.Threading;

public class Example
{
   public static void Main()
   {
      string[] cultureNames = { "en-US", "fr-FR", "es-MX", "de-DE" };
      Decimal value = 1043.17m;
      
      foreach (var cultureName in cultureNames) {
         // Change the current thread culture.
         Thread.CurrentThread.CurrentCulture = CultureInfo.CreateSpecificCulture(cultureName);
         Console.WriteLine("The current culture is {0}", 
                           Thread.CurrentThread.CurrentCulture.Name);
         Console.WriteLine(value.ToString("C2"));
         Console.WriteLine();
      }   
   }
}
// The example displays the following output:
//       The current culture is en-US
//       $1,043.17
//       
//       The current culture is fr-FR
//       1 043,17 €
//       
//       The current culture is es-MX
//       $1,043.17
//       
//       The current culture is de-DE
//       1.043,17 €
Imports System.Globalization
Imports System.Threading 

Module Example
   Public Sub Main()
      Dim cultureNames() As String = { "en-US", "fr-FR", "es-MX", "de-DE" }
      Dim value As Decimal = 1043.17d 
      
      For Each cultureName In cultureNames
         ' Change the current thread culture.
         Thread.CurrentThread.CurrentCulture = CultureInfo.CreateSpecificCulture(cultureName)
         Console.WriteLine("The current culture is {0}", 
                           Thread.CurrentThread.CurrentCulture.Name)
         Console.WriteLine(value.ToString("C2"))
         Console.WriteLine()
      Next                  
   End Sub
End Module
' The example displays the following output:
'       The current culture is en-US
'       $1,043.17
'       
'       The current culture is fr-FR
'       1 043,17 €
'       
'       The current culture is es-MX
'       $1,043.17
'       
'       The current culture is de-DE
'       1.043,17 €

Você também pode formatar um valor numérico para uma cultura específica chamando uma sobrecarga ToString que tenha um parâmetro de provider e passando-o a um dos dois elementos a seguir:You can also format a numeric value for a specific culture by calling a ToString overload that has a provider parameter and passing it either of the following:

O exemplo a seguir usa objetos NumberFormatInfo que representam as culturas inglês (Estados Unidos) e inglês (Grã-Bretanha), além das culturas neutras francês e russo, para formatar um número de ponto flutuante.The following example uses NumberFormatInfo objects that represent the English (United States) and English (Great Britain) cultures and the French and Russian neutral cultures to format a floating-point number.

using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {                                                                                                    
      Double value = 1043.62957;
      string[] cultureNames = { "en-US", "en-GB", "ru", "fr" };
      
      foreach (var name in cultureNames) {
         NumberFormatInfo nfi = CultureInfo.CreateSpecificCulture(name).NumberFormat;
         Console.WriteLine("{0,-6} {1}", name + ":", value.ToString("N3", nfi));
      }   
   }
}
// The example displays the following output:
//       en-US: 1,043.630
//       en-GB: 1,043.630
//       ru:    1 043,630
//       fr:    1 043,630
Imports System.Globalization

Module Example
   Public Sub Main()
      Dim value As Double = 1043.62957
      Dim cultureNames() As String = { "en-US", "en-GB", "ru", "fr" }
      
      For Each name In cultureNames
         Dim nfi As NumberFormatInfo = CultureInfo.CreateSpecificCulture(name).NumberFormat
         Console.WriteLine("{0,-6} {1}", name + ":", value.ToString("N3", nfi))
      Next   
   End Sub
End Module
' The example displays the following output:
'       en-US: 1,043.630
'       en-GB: 1,043.630
'       ru:    1 043,630
'       fr:    1 043,630

Formatação de valores de data e hora que leva em conta a culturaCulture-Sensitive Formatting of Date and Time Values

Por padrão, a formatação de valores de data e hora leva em conta a cultura.By default, the formatting of date and time values is culture-sensitive. Se você não especificar uma cultura quando chamar um método de formatação, as convenções de formatação da cultura do thread atual serão usadas.If you do not specify a culture when you call a formatting method, the formatting conventions of the current thread culture are used. Isso é ilustrado no exemplo a seguir, que altera a cultura do thread atual quatro vezes e, em seguida, chama o método DateTime.ToString(String).This is illustrated in the following example, which changes the current thread culture four times and then calls the DateTime.ToString(String) method. Em cada caso, a cadeia de caracteres de resultado reflete as convenções de formatação da cultura atual.In each case, the result string reflects the formatting conventions of the current culture. Isso ocorre porque os métodos DateTime.ToString(), DateTime.ToString(String), DateTimeOffset.ToString() e DateTimeOffset.ToString(String) encapsulam chamadas para os métodos DateTime.ToString(String, IFormatProvider) e DateTimeOffset.ToString(String, IFormatProvider).This is because the DateTime.ToString(), DateTime.ToString(String), DateTimeOffset.ToString(), and DateTimeOffset.ToString(String) methods wrap calls to the DateTime.ToString(String, IFormatProvider) and DateTimeOffset.ToString(String, IFormatProvider) methods.

using System;
using System.Globalization;
using System.Threading;

public class Example
{
   public static void Main()
   {
      string[] cultureNames = { "en-US", "fr-FR", "es-MX", "de-DE" };
      DateTime dateToFormat = new DateTime(2012, 5, 28, 11, 30, 0);
      
      foreach (var cultureName in cultureNames) {
         // Change the current thread culture.
         Thread.CurrentThread.CurrentCulture = CultureInfo.CreateSpecificCulture(cultureName);
         Console.WriteLine("The current culture is {0}", 
                           Thread.CurrentThread.CurrentCulture.Name);
         Console.WriteLine(dateToFormat.ToString("F"));
         Console.WriteLine();
      }   
   }
}
// The example displays the following output:
//       The current culture is en-US
//       Monday, May 28, 2012 11:30:00 AM
//       
//       The current culture is fr-FR
//       lundi 28 mai 2012 11:30:00
//       
//       The current culture is es-MX
//       lunes, 28 de mayo de 2012 11:30:00 a.m.
//       
//       The current culture is de-DE
//       Montag, 28. Mai 2012 11:30:00
Imports System.Globalization
Imports System.Threading 

Module Example
   Public Sub Main()
      Dim cultureNames() As String = { "en-US", "fr-FR", "es-MX", "de-DE" }
      Dim dateToFormat As Date = #5/28/2012 11:30AM#
      
      For Each cultureName In cultureNames
         ' Change the current thread culture.
         Thread.CurrentThread.CurrentCulture = CultureInfo.CreateSpecificCulture(cultureName)
         Console.WriteLine("The current culture is {0}", 
                           Thread.CurrentThread.CurrentCulture.Name)
         Console.WriteLine(dateToFormat.ToString("F"))
         Console.WriteLine()
      Next                  
   End Sub
End Module
' The example displays the following output:
'       The current culture is en-US
'       Monday, May 28, 2012 11:30:00 AM
'       
'       The current culture is fr-FR
'       lundi 28 mai 2012 11:30:00
'       
'       The current culture is es-MX
'       lunes, 28 de mayo de 2012 11:30:00 a.m.
'       
'       The current culture is de-DE
'       Montag, 28. Mai 2012 11:30:00 

Você também pode formatar um valor de data e hora para uma cultura específica chamando uma sobrecarga DateTime.ToString ou DateTimeOffset.ToString que tenha um parâmetro provider e passando-o a um dos dois elementos a seguir:You can also format a date and time value for a specific culture by calling a DateTime.ToString or DateTimeOffset.ToString overload that has a provider parameter and passing it either of the following:

O exemplo a seguir usa objetos DateTimeFormatInfo que representam as culturas inglês (Estados Unidos) e inglês (Grã-Bretanha), além das culturas neutras francês e russo, para formatar uma data.The following example uses DateTimeFormatInfo objects that represent the English (United States) and English (Great Britain) cultures and the French and Russian neutral cultures to format a date.

using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {                                                                                                    
      DateTime dat1 = new DateTime(2012, 5, 28, 11, 30, 0);
      string[] cultureNames = { "en-US", "en-GB", "ru", "fr" };
      
      foreach (var name in cultureNames) {
         DateTimeFormatInfo dtfi = CultureInfo.CreateSpecificCulture(name).DateTimeFormat;
         Console.WriteLine("{0}: {1}", name, dat1.ToString(dtfi));
      }   
   }
}
// The example displays the following output:
//       en-US: 5/28/2012 11:30:00 AM
//       en-GB: 28/05/2012 11:30:00
//       ru: 28.05.2012 11:30:00
//       fr: 28/05/2012 11:30:00
Imports System.Globalization

Module Example
   Public Sub Main()
      Dim dat1 As Date = #5/28/2012 11:30AM#
      Dim cultureNames() As String = { "en-US", "en-GB", "ru", "fr" }
      
      For Each name In cultureNames
         Dim dtfi As DateTimeFormatInfo = CultureInfo.CreateSpecificCulture(name).DateTimeFormat
         Console.WriteLine("{0}: {1}", name, dat1.ToString(dtfi))
      Next   
   End Sub
End Module
' The example displays the following output:
'       en-US: 5/28/2012 11:30:00 AM
'       en-GB: 28/05/2012 11:30:00
'       ru: 28.05.2012 11:30:00
'       fr: 28/05/2012 11:30:00

A interface IFormattableThe IFormattable Interface

Normalmente, os tipos que sobrecarregam o método ToString com uma cadeia de caracteres de formato e um parâmetro IFormatProvider também implementam a interface IFormattable.Typically, types that overload the ToString method with a format string and an IFormatProvider parameter also implement the IFormattable interface. Essa interface tem um único membro, IFormattable.ToString(String, IFormatProvider), que inclui como parâmetros uma cadeia de caracteres de formato e um provedor de formato.This interface has a single member, IFormattable.ToString(String, IFormatProvider), that includes both a format string and a format provider as parameters.

Implementar a interface IFormattable para a classe definida pelo aplicativo oferece duas vantagens:Implementing the IFormattable interface for your application-defined class offers two advantages:

O exemplo a seguir define uma classe Temperature que implementa a interface IFormattable.The following example defines a Temperature class that implements the IFormattable interface. Ela dá suporte aos especificadores de formato "C" ou "G" para exibir a temperatura em graus Celsius, o especificador de formato "F" para exibir a temperatura em Fahrenheit e o especificador de formato "K" para exibir a temperatura em Kelvin.It supports the "C" or "G" format specifiers to display the temperature in Celsius, the "F" format specifier to display the temperature in Fahrenheit, and the "K" format specifier to display the temperature in Kelvin.

using System;
using System.Globalization;

public class Temperature : IFormattable
{
   private decimal m_Temp;

   public Temperature(decimal temperature)
   {
      this.m_Temp = temperature;
   }
   
   public decimal Celsius
   {
      get { return this.m_Temp; }
   }
   
   public decimal Kelvin
   {
      get { return this.m_Temp + 273.15m; }   
   }
   
   public decimal Fahrenheit
   {
      get { return Math.Round((decimal) this.m_Temp * 9 / 5 + 32, 2); }
   }

   public override string ToString()
   {
      return this.ToString("G", null);
   }
   
   public string ToString(string format)
   {
      return this.ToString(format, null);
   }
   
   public string ToString(string format, IFormatProvider provider)  
   {
      // Handle null or empty arguments.
      if (String.IsNullOrEmpty(format))
         format = "G";
      // Remove any white space and covert to uppercase.
      format = format.Trim().ToUpperInvariant();

      if (provider == null)
         provider = NumberFormatInfo.CurrentInfo;
            
      switch (format)
      {
         // Convert temperature to Fahrenheit and return string.
         case "F":
            return this.Fahrenheit.ToString("N2", provider) + "°F";
         // Convert temperature to Kelvin and return string.
         case "K":
            return this.Kelvin.ToString("N2", provider) + "K";
         // Return temperature in Celsius.
         case "C":
         case "G":
            return this.Celsius.ToString("N2", provider) + "°C";
         default:
            throw new FormatException(String.Format("The '{0}' format string is not supported.", format));
      }      
   }
}
Imports System.Globalization

Public Class Temperature : Implements IFormattable
   Private m_Temp As Decimal

   Public Sub New(temperature As Decimal)
      Me.m_Temp = temperature
   End Sub
   
   Public ReadOnly Property Celsius() As Decimal
      Get
         Return Me.m_Temp
      End Get   
   End Property
   
   Public ReadOnly Property Kelvin() As Decimal
      Get
         Return Me.m_Temp + 273.15d   
      End Get
   End Property
   
   Public ReadOnly Property Fahrenheit() As Decimal
      Get
         Return Math.Round(CDec(Me.m_Temp * 9 / 5 + 32), 2)
      End Get      
   End Property

   Public Overrides Function ToString() As String
      Return Me.ToString("G", Nothing)
   End Function
   
   Public Overloads Function ToString(format As String) As String
      Return Me.ToString(format, Nothing)
   End Function
   
   Public Overloads Function ToString(format As String, provider As IFormatProvider) As String _  
      Implements IFormattable.ToString

      ' Handle null or empty arguments.
      If String.IsNullOrEmpty(format) Then format = "G"
      ' Remove any white space and convert to uppercase.
      format = format.Trim().ToUpperInvariant()

      If provider Is Nothing Then provider = NumberFormatInfo.CurrentInfo
            
      Select Case format
         ' Convert temperature to Fahrenheit and return string.
         Case "F"
            Return Me.Fahrenheit.ToString("N2", provider) & "°F"
         ' Convert temperature to Kelvin and return string.
         Case "K"
            Return Me.Kelvin.ToString("N2", provider) & "K"
         ' Return temperature in Celsius.
         Case "C", "G"
            Return Me.Celsius.ToString("N2", provider) & "°C"
         Case Else
            Throw New FormatException(String.Format("The '{0}' format string is not supported.", format))
      End Select      
   End Function
End Class

O exemplo a seguir instancia um objeto Temperature.The following example instantiates a Temperature object. Depois, ele chama o método ToString e usa várias cadeias de caracteres de formato de composição para obter diferentes representações de cadeia de caracteres de um objeto Temperature.It then calls the ToString method and uses several composite format strings to obtain different string representations of a Temperature object. Cada uma dessas chamadas de método, por sua vez, chama a implementação IFormattable da classe Temperature.Each of these method calls, in turn, calls the IFormattable implementation of the Temperature class.

public class Example
{
   public static void Main()
   {
      CultureInfo.CurrentCulture = CultureInfo.GetCultureInfo("en-US");
      Temperature temp = new Temperature(22m);
      Console.WriteLine(Convert.ToString(temp, new CultureInfo("ja-JP")));
      Console.WriteLine("Temperature: {0:K}", temp);
      Console.WriteLine("Temperature: {0:F}", temp);
      Console.WriteLine(String.Format(new CultureInfo("fr-FR"), "Temperature: {0:F}", temp));
   }
}
// The example displays the following output:
//       22.00°C
//       Temperature: 295.15K
//       Temperature: 71.60°F
//       Temperature: 71,60°F
Public Module Example
   Public Sub Main()
      Dim temp As New Temperature(22d)
      CultureInfo.CurrentCulture = CultureInfo.GetCultureInfo("en-US")
      Console.WriteLine(Convert.ToString(temp1, New CultureInfo("ja-JP")))
      Console.WriteLine("Temperature: {0:K}", temp)
      Console.WriteLine("Temperature: {0:F}", temp)
      Console.WriteLine(String.Format(New CultureInfo("fr-FR"), "Temperature: {0:F}", temp)) 
   End Sub
End Module
' The example displays the following output:
'       22.00°C
'       Temperature: 295.15K
'       Temperature: 71.60°F
'       Temperature: 71,60°F

Formatação compostaComposite Formatting

Alguns métodos, tais como String.Format e StringBuilder.AppendFormat, dão suporte à formatação de composição.Some methods, such as String.Format and StringBuilder.AppendFormat, support composite formatting. Uma cadeia de caracteres de formato de composição é um tipo de modelo que retorna uma única cadeia de caracteres que incorpora a representação de cadeia de caracteres de zero, um ou mais objetos.A composite format string is a kind of template that returns a single string that incorporates the string representation of zero, one, or more objects. Cada objeto é representado na cadeia de caracteres de formato de composição por um item de formato indexado.Each object is represented in the composite format string by an indexed format item. O índice do item de formato corresponde à posição do objeto que ele representa na lista de parâmetros do método.The index of the format item corresponds to the position of the object that it represents in the method's parameter list. Os índices são baseados em zero.Indexes are zero-based. Por exemplo, na seguinte chamada para o método String.Format, o primeiro item de formato, {0:D}, é substituído pela representação de cadeia de caracteres de thatDate; o segundo item de formato, {1}, é substituído pela representação de cadeia de caracteres de item1 e, por fim, o terceiro item de formato, {2:C2}, é substituído pela representação de cadeia de caracteres de item1.Value.For example, in the following call to the String.Format method, the first format item, {0:D}, is replaced by the string representation of thatDate; the second format item, {1}, is replaced by the string representation of item1; and the third format item, {2:C2}, is replaced by the string representation of item1.Value.

result = String.Format("On {0:d}, the inventory of {1} was worth {2:C2}.", 
                       thatDate, item1, item1.Value);
Console.WriteLine(result);                            
// The example displays output like the following if run on a system
// whose current culture is en-US:
//       On 5/1/2009, the inventory of WidgetA was worth $107.44.
result = String.Format("On {0:d}, the inventory of {1} was worth {2:C2}.", _
                       thatDate, item1, item1.Value)
Console.WriteLine(result)                            
' The example displays output like the following if run on a system
' whose current culture is en-US:
'       On 5/1/2009, the inventory of WidgetA was worth $107.44.

Além de substituir um item de formato pela representação de cadeia de caracteres de seu objeto correspondente, os itens de formato também permitem que você controle o seguinte:In addition to replacing a format item with the string representation of its corresponding object, format items also let you control the following:

  • O modo específico em que um objeto é representado como uma cadeia de caracteres, se o objeto implementa a interface IFormattable e se dá suporte a cadeias de caracteres de formato.The specific way in which an object is represented as a string, if the object implements the IFormattable interface and supports format strings. Você pode fazer isso seguindo o índice do item de formato com um : (dois-pontos) seguido por uma cadeia de caracteres de formato válido.You do this by following the format item's index with a : (colon) followed by a valid format string. O exemplo anterior já fez isso ao formatar um valor de data com a cadeia de caracteres de formato (por exemplo, {0:d}) "d" (padrão de data abreviada) e formatando um valor numérico com a cadeia de caracteres de formato "C2" (por exemplo, {2:C2}) para representar o número como um valor de moeda com dois dígitos decimais fracionários.The previous example did this by formatting a date value with the "d" (short date pattern) format string (e.g., {0:d}) and by formatting a numeric value with the "C2" format string (e.g., {2:C2} to represent the number as a currency value with two fractional decimal digits.

  • A largura do campo que contém a representação de cadeia de caracteres do objeto e o alinhamento da representação de cadeia de caracteres nesse campo.The width of the field that contains the object's string representation, and the alignment of the string representation in that field. Você pode fazer isso seguindo o índice do item de formato com uma , (vírgula) seguida da largura do campo.You do this by following the format item's index with a , (comma) followed the field width. A cadeia de caracteres será alinhada à direita no campo se a largura do campo for um valor positivo ou à esquerda se esse valor for negativo.The string is right-aligned in the field if the field width is a positive value, and it is left-aligned if the field width is a negative value. O exemplo a seguir alinha os valores de data à esquerda em um campo de 20 caracteres e alinha valores decimais com um dígito fracionário à direita em um campo de 11 caracteres.The following example left-aligns date values in a 20-character field, and it right-aligns decimal values with one fractional digit in an 11-character field.

    DateTime startDate = new DateTime(2015, 8, 28, 6, 0, 0);
    decimal[] temps = { 73.452m, 68.98m, 72.6m, 69.24563m,
                       74.1m, 72.156m, 72.228m };
    Console.WriteLine("{0,-20} {1,11}\n", "Date", "Temperature");
    for (int ctr = 0; ctr < temps.Length; ctr++)
       Console.WriteLine("{0,-20:g} {1,11:N1}", startDate.AddDays(ctr), temps[ctr]);
    
    // The example displays the following output:
    //       Date                 Temperature
    //
    //       8/28/2015 6:00 AM           73.5
    //       8/29/2015 6:00 AM           69.0
    //       8/30/2015 6:00 AM           72.6
    //       8/31/2015 6:00 AM           69.2
    //       9/1/2015 6:00 AM            74.1
    //       9/2/2015 6:00 AM            72.2
    //       9/3/2015 6:00 AM            72.2
    
    Dim startDate As New Date(2015, 8, 28, 6, 0, 0)
    Dim temps() As Decimal = { 73.452, 68.98, 72.6, 69.24563,
                               74.1, 72.156, 72.228 }
    Console.WriteLine("{0,-20} {1,11}", "Date", "Temperature")
    Console.WriteLine()
    For ctr As Integer = 0 To temps.Length - 1
       Console.WriteLine("{0,-20:g} {1,11:N1}", startDate.AddDays(ctr), temps(ctr))
    Next
    ' The example displays the following output:
    '       Date                 Temperature
    '
    '       8/28/2015 6:00 AM           73.5
    '       8/29/2015 6:00 AM           69.0
    '       8/30/2015 6:00 AM           72.6
    '       8/31/2015 6:00 AM           69.2
    '       9/1/2015 6:00 AM            74.1
    '       9/2/2015 6:00 AM            72.2
    '       9/3/2015 6:00 AM            72.2
    

    Observe que, se o componente de cadeia de caracteres de alinhamento e o componente de cadeia de caracteres de formato estiverem presentes, o primeiro precederá o último (por exemplo, {0,-20:g}.Note that, if both the alignment string component and the format string component are present, the former precedes the latter (for example, {0,-20:g}.

Para obter mais informações sobre formatação de composição, veja Formatação de composição.For more information about composite formatting, see Composite Formatting.

Formatação Personalizada com ICustomFormatterCustom Formatting with ICustomFormatter

Dois métodos de formatação de composição String.Format(IFormatProvider, String, Object[]) e StringBuilder.AppendFormat(IFormatProvider, String, Object[]), incluem um parâmetro de provedor de formato que dá suporte à formatação personalizada.Two composite formatting methods, String.Format(IFormatProvider, String, Object[]) and StringBuilder.AppendFormat(IFormatProvider, String, Object[]), include a format provider parameter that supports custom formatting. Quando um desses métodos de formatação é chamado, ele passa um objeto Type que representa uma interface ICustomFormatter para o método GetFormat do provedor de formato.When either of these formatting methods is called, it passes a Type object that represents an ICustomFormatter interface to the format provider’s GetFormat method. O método GetFormat, em seguida, será responsável por retornar a implementação ICustomFormatter que oferece formatação personalizada.The GetFormat method is then responsible for returning the ICustomFormatter implementation that provides custom formatting.

A interface ICustomFormatter tem um único método, Format(String, Object, IFormatProvider), que é chamado automaticamente por um método de formatação de composição, uma vez para cada item de formato em uma cadeia de caracteres de formato de composição.The ICustomFormatter interface has a single method, Format(String, Object, IFormatProvider), that is called automatically by a composite formatting method, once for each format item in a composite format string. O método Format(String, Object, IFormatProvider) tem três parâmetros: uma cadeia de caracteres de formato, que representa o argumento formatString em um item de formato, um objeto a ser formatado e um objeto IFormatProvider que oferece serviços de formatação.The Format(String, Object, IFormatProvider) method has three parameters: a format string, which represents the formatString argument in a format item, an object to format, and an IFormatProvider object that provides formatting services. Normalmente, a classe que implementa ICustomFormatter também implementa IFormatProvider, portanto este último parâmetro é uma referência para a própria classe de formatação personalizada.Typically, the class that implements ICustomFormatter also implements IFormatProvider, so this last parameter is a reference to the custom formatting class itself. O método retorna uma representação de cadeia de caracteres formatada personalizada do objeto a ser formatado.The method returns a custom formatted string representation of the object to be formatted. Se o método não for capaz de formatar o objeto, ele deverá retornar uma referência nula (Nothing em Visual Basic).If the method cannot format the object, it should return a null reference (Nothing in Visual Basic).

O exemplo a seguir fornece uma implementação ICustomFormatter chamada ByteByByteFormatter que exibe valores inteiros como uma sequência de valores hexadecimais de dois dígitos seguidos por um espaço.The following example provides an ICustomFormatter implementation named ByteByByteFormatter that displays integer values as a sequence of two-digit hexadecimal values followed by a space.

public class ByteByByteFormatter : IFormatProvider, ICustomFormatter
{
   public object GetFormat(Type formatType)
   { 
      if (formatType == typeof(ICustomFormatter))
         return this;
      else
         return null;
   }
   
   public string Format(string format, object arg, 
                          IFormatProvider formatProvider)
   {   
      if (! formatProvider.Equals(this)) return null;
      
      // Handle only hexadecimal format string.
      if (! format.StartsWith("X")) return null;
      
      byte[] bytes;
      string output = null;
      
      // Handle only integral types.
      if (arg is Byte) 
         bytes = BitConverter.GetBytes((Byte) arg);
      else if (arg is Int16)
         bytes = BitConverter.GetBytes((Int16) arg);
      else if (arg is Int32)
         bytes = BitConverter.GetBytes((Int32) arg);
      else if (arg is Int64)   
         bytes = BitConverter.GetBytes((Int64) arg);
      else if (arg is SByte)
         bytes = BitConverter.GetBytes((SByte) arg);
      else if (arg is UInt16)
         bytes = BitConverter.GetBytes((UInt16) arg);
      else if (arg is UInt32)
         bytes = BitConverter.GetBytes((UInt32) arg);
      else if (arg is UInt64)
         bytes = BitConverter.GetBytes((UInt64) arg);
      else
         return null;

      for (int ctr = bytes.Length - 1; ctr >= 0; ctr--)
         output += String.Format("{0:X2} ", bytes[ctr]);   
      
      return output.Trim();
   }
}
Public Class ByteByByteFormatter : Implements IFormatProvider, ICustomFormatter
   Public Function GetFormat(formatType As Type) As Object _
                   Implements IFormatProvider.GetFormat
      If formatType Is GetType(ICustomFormatter) Then
         Return Me
      Else
         Return Nothing
      End If
   End Function
   
   Public Function Format(fmt As String, arg As Object, 
                          formatProvider As IFormatProvider) As String _
                          Implements ICustomFormatter.Format

      If Not formatProvider.Equals(Me) Then Return Nothing

      ' Handle only hexadecimal format string.
      If Not fmt.StartsWith("X") Then 
            Return Nothing
      End If

      ' Handle only integral types.
      If Not typeof arg Is Byte AndAlso
         Not typeof arg Is Int16 AndAlso
         Not typeof arg Is Int32 AndAlso
         Not typeof arg Is Int64 AndAlso
         Not typeof arg Is SByte AndAlso
         Not typeof arg Is UInt16 AndAlso
         Not typeof arg Is UInt32 AndAlso
         Not typeof arg Is UInt64 Then _
            Return Nothing

      Dim bytes() As Byte = BitConverter.GetBytes(arg)
      Dim output As String = Nothing
         
      For ctr As Integer = bytes.Length - 1 To 0 Step -1
         output += String.Format("{0:X2} ", bytes(ctr))   
      Next
      
      Return output.Trim()
   End Function
End Class

O exemplo a seguir usa a classe ByteByByteFormatter para formatar valores inteiros.The following example uses the ByteByByteFormatter class to format integer values. Observe que o método ICustomFormatter.Format é chamado mais de uma vez na segunda chamada de método String.Format(IFormatProvider, String, Object[]) e que o provedor padrão NumberFormatInfo é usado na terceira chamada do método porque o método .ByteByByteFormatter.FormatNote that the ICustomFormatter.Format method is called more than once in the second String.Format(IFormatProvider, String, Object[]) method call, and that the default NumberFormatInfo provider is used in the third method call because the .ByteByByteFormatter.Format não reconhece a cadeia de caracteres de formato "N0" e retorna uma referência nula (Nothing no Visual Basic).method does not recognize the "N0" format string and returns a null reference (Nothing in Visual Basic).

public class Example
{
   public static void Main()
   {
      long value = 3210662321; 
      byte value1 = 214;
      byte value2 = 19;
      
      Console.WriteLine(String.Format(new ByteByByteFormatter(), "{0:X}", value));
      Console.WriteLine(String.Format(new ByteByByteFormatter(), "{0:X} And {1:X} = {2:X} ({2:000})", 
                                      value1, value2, value1 & value2));                                
      Console.WriteLine(String.Format(new ByteByByteFormatter(), "{0,10:N0}", value));
   }
}
// The example displays the following output:
//       00 00 00 00 BF 5E D1 B1
//       00 D6 And 00 13 = 00 12 (018)
//       3,210,662,321
Public Module Example
   Public Sub Main()
      Dim value As Long = 3210662321 
      Dim value1 As Byte = 214
      Dim value2 As Byte = 19
      
      Console.WriteLine((String.Format(New ByteByByteFormatter(), "{0:X}", value)))
      Console.WriteLine((String.Format(New ByteByByteFormatter(), "{0:X} And {1:X} = {2:X} ({2:000})", 
                                      value1, value2, value1 And value2)))                                
      Console.WriteLine(String.Format(New ByteByByteFormatter(), "{0,10:N0}", value))
   End Sub
End Module
' The example displays the following output:
'       00 00 00 00 BF 5E D1 B1
'       00 D6 And 00 13 = 00 12 (018)
'       3,210,662,321

TítuloTitle DefiniçãoDefinition
Cadeias de Caracteres de Formato Numérico PadrãoStandard Numeric Format Strings Descreve cadeias de caracteres de formato padrão que criam representações de cadeia de caracteres de valores numéricos frequentemente usadas.Describes standard format strings that create commonly used string representations of numeric values.
Cadeias de caracteres de formato numérico personalizadoCustom Numeric Format Strings Descreve cadeias de caracteres de formato personalizado que criam formatos específicos de aplicativo para valores numéricos.Describes custom format strings that create application-specific formats for numeric values.
Cadeias de caracteres de formato de data e hora padrãoStandard Date and Time Format Strings Descreve cadeias de caracteres de formato padrão que criam representações de cadeia de caracteres de valores DateTime frequentemente usadas.Describes standard format strings that create commonly used string representations of DateTime values.
Cadeias de caracteres de formato de data e hora personalizadoCustom Date and Time Format Strings Descreve cadeias de caracteres de formato personalizado que criam formatos específicos de aplicativo para valores DateTime.Describes custom format strings that create application-specific formats for DateTime values.
Cadeias de caracteres de formato TimeSpan padrãoStandard TimeSpan Format Strings Descreve cadeias de caracteres de formato padrão que criam representações de intervalos de tempo frequentemente usadas.Describes standard format strings that create commonly used string representations of time intervals.
Cadeias de caracteres de formato TimeSpan personalizadoCustom TimeSpan Format Strings Descreve cadeias de caracteres de formato personalizado que criam formatos específicos de aplicativo para intervalos de tempo.Describes custom format strings that create application-specific formats for time intervals.
Cadeias de Caracteres de Formato de EnumeraçãoEnumeration Format Strings Descreve cadeias de caracteres de formato padrão que são usadas para criar representações de cadeia de caracteres de valores de enumeração.Describes standard format strings that are used to create string representations of enumeration values.
Formatação de composiçãoComposite Formatting Descreve como inserir um ou mais valores formatados em uma cadeia de caracteres.Describes how to embed one or more formatted values in a string. A cadeia de caracteres pode posteriormente ser exibida no console ou gravada em um fluxo.The string can subsequently be displayed on the console or written to a stream.
Executando operações de formataçãoPerforming Formatting Operations Lista os tópicos que fornecem instruções passo a passo para executar operações de formatação específicas.Lists topics that provide step-by-step instructions for performing specific formatting operations.
Análise de cadeias de caracteresParsing Strings Descreve como inicializar objetos para os valores descritos pelas representações de cadeia de caracteres desses objetos.Describes how to initialize objects to the values described by string representations of those objects. A análise é a operação inversa da formatação.Parsing is the inverse operation of formatting.

ReferênciaReference