Partilhar via

Visão geral: Como formatar números, datas, enums e outros tipos no .NET

A formatação é o processo de conversão de uma instância de uma classe ou estrutura, ou um valor de enumeração, em uma representação de cadeia de caracteres. O objetivo é exibir a cadeia de caracteres resultante para os usuários ou desserializá-la posteriormente para restaurar o tipo de dados original. Este artigo apresenta os mecanismos de formatação que o .NET fornece.

Nota

A análise é o inverso da formatação. Uma operação de análise cria uma instância de um tipo de dados a partir de sua representação de cadeia de caracteres. Para obter mais informações, consulte Analisando cadeias de caracteres. Para obter informações sobre serialização e desserialização, consulte Serialização no .NET.

O mecanismo básico para formatação é a implementação padrão do método, que é discutida Object.ToStringna seção Formatação padrão usando o método ToString mais adiante neste tópico. No entanto, o .NET fornece várias maneiras de modificar e estender seu suporte à formatação padrão. Estas incluem o seguinte:

  • Sobrescrevendo o Object.ToString método para definir uma representação de string personalizada do valor de um objeto. Para obter mais informações, consulte a Substituir o Método ToString mais adiante neste tópico.

  • Definição de especificadores de formato que permitem que a representação de cadeia de caracteres do valor de um objeto assuma várias formas. 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.

    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, consulte a secção Método ToString e Modificar Strings.

  • Usando provedores de formato para implementar as convenções de formatação de uma cultura específica. Por exemplo, a instrução a seguir exibe um valor monetário usando a norma de formatação da cultura dos EUA.

    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 formatação com provedores de formato, consulte a seção Provedores de formato.

  • Implementação da interface para suportar tanto a conversão de cadeia de caracteres com a classe IFormattable quanto a formatação composta. Para obter mais informações, consulte a seção Interface IFormattable .

  • Usando formatação composta para incorporar a representação textual de um valor numa cadeia de caracteres maior. Para obter mais informações, consulte a seção Formatação composta .

  • Usando interpolação de cadeia de caracteres, uma sintaxe mais legível para incorporar a representação de cadeia de caracteres de um valor em uma cadeia de caracteres maior. Para obter mais informações, consulte Interpolação de cadeia de caracteres.

  • Implementar ICustomFormatter e IFormatProvider para fornecer uma solução de formatação completamente personalizada. Para obter mais informações, consulte a seção Formatação personalizada com ICustomFormatter .

As seções a seguir examinam esses métodos para converter um objeto em sua representação de cadeia de caracteres.

Formatação padrão usando o método ToString

Cada tipo derivado de System.Object herda automaticamente um método ToString sem parâmetros, que, por padrão, retorna o nome do tipo. O exemplo a seguir ilustra o método padrão ToString . Ele define uma classe chamada Automobile que não tem implementação. Quando a classe é instanciada e seu ToString método é chamado, ele exibe seu nome de tipo. Observe que o ToString método não é explicitamente chamado no exemplo. O Console.WriteLine(Object) método chama implicitamente o ToString método do objeto passado para ele como um argumento.

using System;

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

public class Example9
{
   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 Example9
    Public Sub Main9()
        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.1, o Windows Runtime inclui uma IStringable interface com um único método, IStringable.ToString, que fornece suporte à formatação padrão. No entanto, recomendamos que os tipos gerenciados não implementem a IStringable interface. Para obter mais informações, consulte O Tempo de Execução do Windows e a Interface IStringable.

Como todos os tipos, exceto as interfaces, são derivadas de Object, esta funcionalidade é automaticamente fornecida às suas classes ou estruturas personalizadas. No entanto, a funcionalidade oferecida pelo método padrão ToString é limitada: embora identifique o tipo, ele não fornece nenhuma informação sobre uma instância do tipo. Para fornecer uma representação de cadeia de caracteres de um objeto que fornece informações sobre esse objeto, você deve substituir o ToString método.

Nota

As estruturas herdam de ValueType, que por sua vez é derivado de Object. Embora ValueType se sobreponha Object.ToString, a sua implementação é idêntica.

Sobrescrever o método ToString

A exibição do nome de um tipo geralmente é de uso limitado e não permite aos consumidores dos seus tipos a diferenciação de uma instância em relação a outra. No entanto, você pode substituir o ToString método para fornecer uma representação mais útil do valor de um objeto. O exemplo a seguir define um Temperature objeto e substitui seu ToString método para exibir a temperatura em graus Celsius.

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 Example12
{
    public static void Main()
    {
        Temperature currentTemperature = new Temperature(23.6m);
        Console.WriteLine($"The current temperature is {currentTemperature}");
    }
}
// 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 Example13
    Public Sub Main13()
        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 ToString método de cada tipo de valor primitivo foi substituído para exibir o valor do objeto em vez de seu nome. A tabela a seguir mostra a substituição para cada tipo primitivo. Observe que a maioria dos métodos sobrepostos chama uma versão alternativa do método ToString e passa-lhe o especificador de formato "G", que define o formato geral para o seu tipo, e um objeto IFormatProvider que representa a cultura atual.

Tipo Substituição de ToString
Boolean Devolve ou Boolean.TrueString ou Boolean.FalseString.
Byte Chama Byte.ToString("G", NumberFormatInfo.CurrentInfo) para formatar o valor Byte para a cultura atual.
Char Retorna o caractere como uma cadeia de caracteres.
DateTime Chama DateTime.ToString("G", DatetimeFormatInfo.CurrentInfo) para que formate o valor de data e hora para a cultura atual.
Decimal Chama Decimal.ToString("G", NumberFormatInfo.CurrentInfo) para formatar o valor Decimal para a cultura atual.
Double Chama Double.ToString("G", NumberFormatInfo.CurrentInfo) para formatar o valor Double para a cultura atual.
Int16 Chama Int16.ToString("G", NumberFormatInfo.CurrentInfo) para formatar o valor Int16 para a cultura atual.
Int32 Chama Int32.ToString("G", NumberFormatInfo.CurrentInfo) para formatar o valor Int32 para a cultura atual.
Int64 Chama Int64.ToString("G", NumberFormatInfo.CurrentInfo) para formatar o valor Int64 para a cultura atual.
SByte Chama SByte.ToString("G", NumberFormatInfo.CurrentInfo) para formatar o valor SByte para a cultura atual.
Single Chama Single.ToString("G", NumberFormatInfo.CurrentInfo) para formatar o valor Single para a cultura atual.
UInt16 Chama UInt16.ToString("G", NumberFormatInfo.CurrentInfo) para formatar o valor UInt16 para a cultura atual.
UInt32 Chama UInt32.ToString("G", NumberFormatInfo.CurrentInfo) para formatar o valor UInt32 para a cultura atual.
UInt64 Chama UInt64.ToString("G", NumberFormatInfo.CurrentInfo) para formatar o valor UInt64 para a cultura atual.

O método ToString e formatar cadeias de caracteres

Confiar no método padrão ToString ou na substituição ToString é apropriado quando um objeto tem uma única representação de cadeia de caracteres. No entanto, o valor de um objeto geralmente tem várias representações. Por exemplo, uma temperatura pode ser expressa em graus Fahrenheit, graus Celsius ou kelvins. Da mesma forma, o valor inteiro 10 pode ser representado de várias maneiras, incluindo 10, 10,0, 1,0e01 ou $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. 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 deve formatar ToString sua saída. A cadeia de caracteres de formato é então passada como um parâmetro para o método do ToString objeto e determina como a representação da cadeia de caracteres do valor desse objeto deve aparecer.

Todos os tipos numéricos, tipos de data e hora e tipos de enumeração no .NET oferecem suporte a um conjunto predefinido de especificadores de formato. 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.

Cadeias de caracteres de formato padrão

Uma cadeia de caracteres de formato padrão contém um especificador de formato único, que é um caractere alfabético que define a representação de cadeia de caracteres do objeto ao qual ela é aplicada, juntamente com um especificador de precisão opcional que afeta quantos dígitos são exibidos na cadeia de caracteres de resultado. Se o especificador de precisão for omitido ou não for suportado, um especificador de formato padrão será equivalente a uma cadeia de caracteres de formato padrão.

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. Por exemplo, cada uma dessas categorias suporta um especificador de formato padrão "G", que define uma representação geral de cadeia de caracteres de um valor desse tipo.

Cadeias de caracteres de formato padrão para tipos de enumeração controlam diretamente a representação de cadeia de caracteres de um valor. As cadeias de caracteres de formato passadas para o método de ToString um valor de enumeração determinam se o valor é exibido usando seu nome de cadeia de caracteres (os especificadores de formato "G" e "F"), seu valor integral subjacente (o especificador de formato "D") ou seu valor hexadecimal (o especificador de formato "X"). O exemplo a seguir ilustra o uso de cadeias de caracteres de formato padrão para formatar um DayOfWeek valor de enumeração.

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, consulte Cadeias de caracteres de formato de enumeração.

Cadeias de caracteres de formato padrão para tipos numéricos geralmente definem uma cadeia de caracteres de resultado cuja aparência precisa é controlada por um ou mais valores de propriedade. Por exemplo, o especificador de formato "C" formata um número como um valor de moeda. Quando você chama o ToString método com o especificador de formato "C" como o único parâmetro, os seguintes valores de propriedade do NumberFormatInfo objeto da cultura atual são usados para definir a representação de cadeia de caracteres do valor numérico:

  • A CurrencySymbol propriedade, que especifica o símbolo de moeda da cultura atual.

  • A propriedade CurrencyNegativePattern ou CurrencyPositivePattern, que retorna um inteiro que determina o seguinte:

    • O posicionamento do símbolo da moeda.

    • Se os valores negativos são indicados por um sinal negativo à esquerda, um sinal negativo à direita ou parênteses.

    • Se aparece um espaço entre o valor numérico e o símbolo da moeda.

  • A propriedade CurrencyDecimalDigits, que define o número de dígitos fracionários na cadeia de resultado.

  • A CurrencyDecimalSeparator propriedade, que define o símbolo do separador decimal na cadeia de caracteres de resultado.

  • A CurrencyGroupSeparator propriedade, que define o símbolo separador de grupo.

  • A propriedade CurrencyGroupSizes, que define o número de dígitos em cada grupo à esquerda do ponto decimal.

  • NegativeSign A propriedade, que determina o sinal negativo usado na sequência de caracteres de resultado caso os parênteses não sejam usados para indicar valores negativos.

Além disso, as cadeias de caracteres de formato numérico podem incluir um especificador de precisão. O significado deste especificador depende da cadeia de caracteres de formato com a qual é usado, mas normalmente indica o número total de dígitos ou o número de dígitos fracionários que devem aparecer na cadeia de resultados. Por exemplo, o exemplo a seguir usa a cadeia numérica padrão "X4" e um especificador de precisão para criar um valor de cadeia de caracteres que tenha quatro dígitos hexadecimais.

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 padrão, consulte Cadeias de caracteres de formato numérico padrão.

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 específica DateTimeFormatInfo . Por exemplo, chamar o método ToString de um valor de data e hora com o especificador de formato "D" exibe a data e a hora usando a cadeia de caracteres de formato personalizada armazenada na propriedade DateTimeFormatInfo.LongDatePattern da cultura atual. (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.

using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {
      DateTime date1 = new DateTime(2009, 6, 30);
      Console.WriteLine($"D Format Specifier:     {date1:D}");
      string longPattern = CultureInfo.CurrentCulture.DateTimeFormat.LongDatePattern;
      Console.WriteLine($"'{longPattern}' custom format string:     {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 Main0()
        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 cadeias de caracteres de formato de data e hora padrão, consulte Cadeias de caracteres de formato de data e hora padrão.

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 do ToString(String) objeto. Você pode definir os especificadores de formato padrão específicos que o seu objeto suporta e determinar se eles diferenciam maiúsculas de minúsculas. Sua implementação do ToString(String) método deve suportar o seguinte:

  • Um especificador de formato "G" que representa um formato habitual ou comum do objeto. A sobrecarga sem parâmetros do método do seu objeto ToString deve chamar a sua sobrecarga ToString(String) e passá-la como a cadeia de caracteres de formato padrão "G".

  • Suporte para um especificador de formato que é igual a uma referência nula (Nothing no Visual Basic). Um especificador de formato que é igual a uma referência nula deve ser considerado equivalente ao especificador de formato "G".

Por exemplo, uma Temperature classe pode armazenar internamente a temperatura em graus Celsius e usar especificadores de formato para representar o Temperature valor do objeto em graus Celsius, graus Fahrenheit e kelvins. O exemplo a seguir fornece uma ilustração.

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 Example1
{
   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 Example1
    Public Sub Main1()
        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 personalizado

Além das 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. 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. 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 para sua representação de cadeia de caracteres na forma "2008/11/15 07:45:00.0000 P -08:00" para a cultura en-US. Da mesma forma, a cadeia de caracteres de formato personalizado "0000" converte o valor inteiro 12 em "0012". Para obter uma lista completa de cadeias de caracteres de formato personalizadas, consulte Cadeias de caracteres de formato de data e hora personalizadas e Cadeias de caracteres de formato numérico personalizadas.

Se uma cadeia de caracteres de formato consistir 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. 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.

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 DateTimeFormatInfo objeto. As cadeias de caracteres de formato personalizado também oferecem flexibilidade considerável no fornecimento de formatação definida pelo aplicativo para valores numéricos ou valores de data e hora. 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 personalizados em uma única cadeia de caracteres de formato personalizado. 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, dia e ano.

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 Int64 valor como um número de telefone padrão de sete dígitos dos EUA junto com seu código de área.

using System;

public class Example17
{
   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 Example18
    Public Sub Main18()
        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 possam lidar com a maioria das necessidades de formatação para os tipos definidos pelo aplicativo, você também pode definir especificadores de formato personalizados para formatar seus tipos.

Formatar cadeias de caracteres e tipos do .NET

Todos os tipos numéricos (ou seja, o Byte, Decimal, Double, Int16, Int32, , Int64SByte, SingleUInt16UInt32UInt64e BigInteger tipos), bem como o DateTime, DateTimeOffset, TimeSpan, Guid, e todos os tipos de enumeração, suportam formatação com cadeias de caracteres de formato. Para obter informações sobre as cadeias de caracteres de formato específicas suportadas por cada tipo, consulte os seguintes tópicos:

Título Definição
Standard Numeric Format Strings (Cadeias de Formato Numérico Padrão) Descreve cadeias de caracteres de formato padrão que criam representações de cadeia de caracteres comumente usadas de valores numéricos.
Cadeias de caracteres de formato numérico personalizado Descreve cadeias de caracteres de formato personalizado que criam formatos específicos do aplicativo para valores numéricos.
Cadeias de Formato de Data e Hora Padrão Descreve cadeias de caracteres de formato padrão que criam representações de cadeia de caracteres comumente usadas de valores DateTime e DateTimeOffset.
Cadeias de Formato de Data e Hora Personalizadas Descreve cadeias de caracteres de formato personalizadas que criam formatos específicos do aplicativo para os valores de DateTime e DateTimeOffset.
Cadeias de caracteres de formato TimeSpan padrão Descreve formatos padrão de cadeia de caracteres que criam representações comuns de intervalos de tempo.
Cadeias de caracteres de formato TimeSpan personalizadas Descreve cadeias de caracteres de formato personalizado que criam formatos específicos do aplicativo para intervalos de tempo.
Cadeias de caracteres de formato de enumeração Descreve cadeias de caracteres de formato padrão que são usadas para criar representações de valores de enumeração.
Guid.ToString(String) Descreve cadeias de caracteres de formato padrão para Guid valores.

Formatação sensível à cultura com fornecedores de formatação

Embora os especificadores de formato permitam personalizar a formatação de objetos, produzir uma representação de cadeia de caracteres significativa de objetos geralmente requer informações adicionais de formatação. Por exemplo, formatar um número como um valor de moeda usando a cadeia de caracteres de formato padrão "C" ou uma cadeia de caracteres de formato personalizado como "$ #,#.00" exige, no mínimo, informações sobre o símbolo de moeda correto, separador de grupo e separador decimal para estar disponível para inclusão na cadeia de caracteres formatada. No .NET, estas informações adicionais de formatação são disponibilizadas através da interface IFormatProvider, fornecida como parâmetro para uma ou mais sobrecargas do método ToString dos tipos numéricos e dos tipos de data e hora. IFormatProvider implementações são usadas no .NET para dar suporte à formatação específica da cultura. O exemplo a seguir ilustra como a representação de cadeia de caracteres de um objeto muda quando ele é formatado com três IFormatProvider objetos que representam culturas diferentes.

using System;
using System.Globalization;

public class Example18
{
   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 Example11
    Public Sub Main11()
        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 IFormatProvider interface 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. Se o método pode fornecer um objeto desse tipo, ele o retorna. Caso contrário, ele retorna uma referência nula (Nothing no Visual Basic).

IFormatProvider.GetFormat é um método de retorno de chamada. Quando chamas uma sobrecarga de método ToString que inclui o parâmetro IFormatProvider, ela chama o método GetFormat desse objeto IFormatProvider. O GetFormat método é responsável por retornar um objeto que fornece as informações de formatação necessárias, conforme especificado por seu formatType parâmetro, para o ToString método.

Vários métodos de formatação ou conversão de cadeia de caracteres incluem um parâmetro do tipo IFormatProvider, mas em muitos casos o valor do parâmetro é ignorado quando o método é chamado. A tabela a seguir lista alguns dos métodos de formatação que usam o parâmetro e o tipo do Type objeto que eles passam para o IFormatProvider.GetFormat método.

Método Tipo de formatType parâmetro
ToString Método dos tipos numéricos System.Globalization.NumberFormatInfo
ToString método para tipos de data e hora System.Globalization.DateTimeFormatInfo
String.Format System.ICustomFormatter
StringBuilder.AppendFormat System.ICustomFormatter

Nota

Os ToString métodos dos tipos numéricos e tipos de data e hora estão sobrecarregados, e apenas algumas das sobrecargas incluem um IFormatProvider parâmetro. Se um método não tiver um parâmetro do tipo IFormatProvider, o objeto retornado pela CultureInfo.CurrentCulture propriedade será passado. Por exemplo, uma chamada para o método padrão Int32.ToString() resulta em uma chamada de método como a seguinte: Int32.ToString("G", System.Globalization.CultureInfo.CurrentCulture).

O .NET fornece três classes que implementam IFormatProvider:

Você também pode implementar seu próprio provedor de formato para substituir qualquer uma dessas classes. No entanto, o método GetFormat da implementação deve retornar um objeto do tipo listado na tabela anterior caso tenha que fornecer informações de formatação ao método ToString.

Formatação de valores numéricos sensível à cultura

Por padrão, a formatação de valores numéricos é sensível à cultura. Se você não especificar uma cultura ao chamar um método de formatação, as convenções de formatação da cultura atual serão usadas. Isso é ilustrado no exemplo a seguir, que altera a cultura atual quatro vezes e, em seguida, chama o método Decimal.ToString(String). Em cada caso, a cadeia de caracteres de resultado reflete as convenções de formatação da cultura atual. Isso ocorre porque os métodos ToString e ToString(String) encapsulam chamadas para o método ToString(String, IFormatProvider) de cada tipo numérico.

using System.Globalization;

public class Example6
{
   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 culture.
         CultureInfo.CurrentCulture = CultureInfo.CreateSpecificCulture(cultureName);
         Console.WriteLine($"The current culture is {CultureInfo.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

Module Example6
    Public Sub Main6()
        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 culture.
            CultureInfo.CurrentCulture = CultureInfo.CreateSpecificCulture(cultureName)
            Console.WriteLine($"The current culture is {CultureInfo.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 ToString sobrecarga que tenha um provider parâmetro e passando-o de uma das seguintes formas:

  • Um CultureInfo objeto que representa a cultura cujas convenções de formatação devem ser usadas. Seu CultureInfo.GetFormat método retorna o valor da propriedade CultureInfo.NumberFormat, que é o objeto NumberFormatInfo que fornece informações de formatação específicas para a cultura em valores numéricos.

  • Um NumberFormatInfo objeto que define as convenções de formatação específicas da cultura a serem usadas. Seu GetFormat método retorna uma instância de si mesmo.

O exemplo a seguir usa NumberFormatInfo objetos que representam as culturas inglesa (Estados Unidos) e inglesa (Reino Unido) e as culturas neutras francesa e russa para formatar um número de vírgula flutuante.

using System.Globalization;

public class Example7
{
    public static void Main()
    {
        double value = 1043.62957;
        string[] cultureNames = { "en-US", "en-GB", "ru", "fr" };

        foreach (string? 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 Example7
    Public Sub Main7()
        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 sensível à cultura

Por padrão, a formatação de valores de data e hora é sensível à cultura. Se você não especificar uma cultura ao chamar um método de formatação, as convenções de formatação da cultura atual serão usadas. Isso é ilustrado no exemplo a seguir, que altera a cultura atual quatro vezes e, em seguida, chama o método DateTime.ToString(String). Em cada caso, a cadeia de caracteres de resultado reflete as convenções de formatação da cultura atual. Isso ocorre porque os DateTime.ToString()métodos , DateTime.ToString(String), DateTimeOffset.ToString(), e DateTimeOffset.ToString(String) encapsulam chamadas para os DateTime.ToString(String, IFormatProvider) métodos e DateTimeOffset.ToString(String, IFormatProvider) .

using System.Globalization;

public class Example4
{
   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 culture.
         CultureInfo.CurrentCulture = CultureInfo.CreateSpecificCulture(cultureName);
         Console.WriteLine($"The current culture is {CultureInfo.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 Example4
    Public Sub Main4()
        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 culture.
            CultureInfo.CurrentCulture = CultureInfo.CreateSpecificCulture(cultureName)
            Console.WriteLine($"The current culture is {CultureInfo.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-lhe uma das seguintes opções:

O exemplo a seguir usa DateTimeFormatInfo objetos que representam as culturas inglesa (Estados Unidos) e inglesa (Reino Unido) e as culturas neutras francesa e russa para formatar uma data.

using System.Globalization;

public class Example5
{
   public static void Main()
   {
      DateTime dat1 = new(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($"{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 Example5
    Public Sub Main5()
        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($"{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

Interface IFormattable

Normalmente, os tipos que sobrecarregam o ToString método com uma cadeia de caracteres de formato e um IFormatProvider parâmetro também implementam a IFormattable interface. Essa interface tem um único membro, IFormattable.ToString(String, IFormatProvider), que inclui uma cadeia de caracteres de formato e um provedor de formato como parâmetros.

A implementação da IFormattable interface para sua classe definida pelo aplicativo oferece duas vantagens:

O exemplo a seguir define uma Temperature classe que implementa a IFormattable interface. Ele suporta os especificadores de formato "C" ou "G" para exibir a temperatura em Celsius, o especificador de formato "F" para exibir a temperatura em Fahrenheit e o especificador de formato "K" para exibir a temperatura em Kelvin.

using System;
using System.Globalization;

namespace HotAndCold
{

    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));
            }
        }
    }

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 '{format}' format string is not supported."))
        End Select
    End Function
End Class

O exemplo a seguir instancia um Temperature objeto. Em seguida, ele chama o ToString método e usa várias cadeias de caracteres de formato composto para obter diferentes representações de cadeia de caracteres de um Temperature objeto. Cada uma dessas chamadas de métodos, por sua vez, chama a implementação IFormattable da classe Temperature.

public class Example11
{
    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: {temp:K}");
        Console.WriteLine($"Temperature: {temp:F}");
        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 Example12
    Public Sub Main12()
        Dim temp As New Temperature(22D)
        CultureInfo.CurrentCulture = CultureInfo.GetCultureInfo("en-US")
        Console.WriteLine(Convert.ToString(temp, New CultureInfo("ja-JP")))
        Console.WriteLine($"Temperature: {temp:K}")
        Console.WriteLine($"Temperature: {temp:F}")
        Console.WriteLine(String.Format(New CultureInfo("fr-FR"), $"Temperature: {temp:F}"))
    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 composta

Alguns métodos, como String.Format e StringBuilder.AppendFormat, suportam formatação composta. Uma cadeia de formato composto é um tipo de modelo que devolve uma única string, incorporando a representação em cadeia de zero, um ou mais objetos. Na cadeia de caracteres de formato composto, cada objeto é representado por um item de formato indexado. O índice do item de formato corresponde à posição do objeto que ele representa na lista de parâmetros do método. Os índices são baseados em zero. Por exemplo, na chamada a seguir para o String.Format método, o primeiro item de formato, {0:D}, é substituído pela representação de cadeia de caracteres de ; o segundo item de thatDateformato, {1}, é substituído pela representação de cadeia de caracteres de ; e o terceiro item de item1formato, {2:C2}, é substituído pela representação de cadeia de caracteres de 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 controlar o seguinte:

  • A maneira específica na qual um objeto é representado como uma cadeia de caracteres, se o objeto implementa a IFormattable interface e suporta cadeias de caracteres de formato. Para fazer isso, siga o índice do item de formato com um : (dois pontos) seguido por uma cadeia de caracteres de formato válida. O exemplo anterior fez isso formatando um valor de data com a cadeia de caracteres de formato "d" (padrão de data curta) (por exemplo, {0:d}) 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.

  • 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. Para fazer isso, siga o índice do elemento de formato com uma , (vírgula) seguida pela largura do campo. A cadeia de caracteres é alinhada à direita no campo se a largura do campo for um valor positivo, e é alinhada à esquerda se a largura do campo for um valor negativo. O exemplo a seguir alinha valores de data à esquerda em um campo de 20 caracteres e alinha à direita valores decimais com um dígito fracionário em um campo de 11 caracteres.

    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

    Se o componente de cadeia de caracteres de alinhamento e o componente de cadeia de caracteres de formato estiverem presentes, o primeiro precederá o segundo (por exemplo, {0,-20:g}).

Para obter mais informações sobre formatação composta, consulte Formatação composta.

Formatação personalizada com ICustomFormatter

Dois métodos String.Format(IFormatProvider, String, Object[]) de formatação composta e StringBuilder.AppendFormat(IFormatProvider, String, Object[]), incluem um parâmetro de provedor de formato que oferece suporte à formatação personalizada. Quando um desses métodos de formatação é chamado, ele passa um Type objeto que representa uma ICustomFormatter interface para o método do GetFormat provedor de formato. O GetFormat método é então responsável por retornar a ICustomFormatter implementação que fornece formatação personalizada.

A ICustomFormatter interface tem um único método, Format(String, Object, IFormatProvider), que é chamado automaticamente por um método de formatação composta, uma vez para cada item de formato em uma cadeia de caracteres de formato composto. O Format(String, Object, IFormatProvider) método tem três parâmetros: uma cadeia de caracteres de formato, que representa o formatString argumento em um item de formato, um objeto para formatar e um IFormatProvider objeto que fornece serviços de formatação. Normalmente, a classe que implementa ICustomFormatter também implementa IFormatProvider, portanto, esse último parâmetro é uma referência à própria classe de formatação personalizada. O método retorna uma representação de cadeia de caracteres formatada personalizada do objeto a ser formatado. Se o método não pode formatar o objeto, ele deve retornar uma referência nula (Nothing no Visual Basic).

O exemplo a seguir fornece uma ICustomFormatter implementação chamada ByteByByteFormatter que exibe valores inteiros como uma sequência de valores hexadecimais de dois dígitos seguida por um espaço.

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 is not null) && !formatProvider.Equals(this)) return "";

        // Handle only hexadecimal format string.
        if ((format is not null) && !format.StartsWith("X")) return "";

        byte[] bytes;

        // Handle only integral types.
        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 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 "";

        string output= "";
        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 ByteByByteFormatter classe para formatar valores inteiros. 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 de método porque . ByteByByteFormatter.Format método não reconhece a cadeia de caracteres de formato "N0" e retorna uma referência nula (Nothing no Visual Basic).

public class Example10
{
    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 Example10
    Public Sub Main10()
        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

Consulte também

Título Definição
Standard Numeric Format Strings (Cadeias de Formato Numérico Padrão) Descreve cadeias de caracteres de formato padrão que criam representações de cadeia de caracteres comumente usadas de valores numéricos.
Cadeias de caracteres de formato numérico personalizado Descreve cadeias de caracteres de formato personalizado que criam formatos específicos do aplicativo para valores numéricos.
Cadeias de Formato de Data e Hora Padrão Descreve formatos de cadeia padrão que criam representações comuns de valores DateTime.
Cadeias de Formato de Data e Hora Personalizadas Descreve cadeias de formato personalizadas que criam formatos específicos da aplicação para valores DateTime.
Cadeias de caracteres de formato TimeSpan padrão Descreve formatos padrão de cadeia de caracteres que criam representações comuns de intervalos de tempo.
Cadeias de caracteres de formato TimeSpan personalizadas Descreve cadeias de caracteres de formato personalizado que criam formatos específicos do aplicativo para intervalos de tempo.
Cadeias de caracteres de formato de enumeração Descreve cadeias de caracteres de formato padrão que são usadas para criar representações de valores de enumeração.
Formatação composta Descreve como incorporar um ou mais valores formatados em uma cadeia de caracteres. A cadeia de caracteres pode ser exibida posteriormente no console ou gravada em um fluxo.
Analisando cadeias de caracteres Descreve como inicializar objetos com os valores descritos por representações em forma de string desses objetos. A análise é a operação inversa da formatação.

Referência