Cadeias de caracteres de formato de data e hora padrão

Uma cadeia de caracteres de formato de data e hora padrão usa um único caractere como o especificador de formato para definir a representação de texto de um DateTime, DateTimeOffsetou DateOnlyTimeOnly valor. Qualquer cadeia de caracteres de formato de data e hora que contenha mais de um caractere, incluindo espaço em branco, é interpretada como uma cadeia de caracteres de formato de data e hora personalizado. Uma cadeia de caracteres de formato padrão ou personalizado pode ser usada de duas maneiras:

• Para definir a cadeia de caracteres resultante de uma operação de formatação.

• Para definir a representação de texto de um valor de data e hora que pode ser convertido em um DateTime, DateTimeOffsetou DateOnlyTimeOnly valor por uma operação de análise.

Tabela de especificadores de formato

A tabela a seguir descreve os especificadores de formato de data e hora padrão. A menos que observado de outra forma, um especificador de formato de data e hora padrão específico produz uma representação de cadeia de caracteres idêntica, independentemente de ser usada com um DateTime ou um valor DateTimeOffset. Nem todos os especificadores de formato podem ser usados com DateOnly e TimeOnly valores; para obter informações adicionais, consulte a formatação DateOnly e TimeOnly. Para obter informações sobre como as configurações regionais no Windows e no objeto atual DateTimeFormatInfo podem afetar a formatação de data e hora, consulte Configurações do Painel de Controle e Propriedades DateTimeFormatInfo.

Como funcionam as cadeias de caracteres de formato padrão

Em uma operação de formatação, uma cadeia de formato padrão é simplesmente um alias para uma cadeia de caracteres de formato personalizado. A vantagem de usar um alias para se referir a uma cadeia de caracteres de formato personalizado é que, embora o alias permaneça invariável, a cadeia de caracteres de formato personalizado em si pode variar. Isso é importante porque as representações de cadeia de caracteres de valores de data e hora normalmente variam de acordo com a cultura. Por exemplo, a cadeia de caracteres de formato padrão "d" indica que um valor de data e hora deve ser exibido usando um formato de data abreviada. Para a cultura invariável, esse padrão é "MM/dd/aaaa". Para a cultura fr-FR, ele é " dd/MM/aaaa ". Para a cultura ja-JP, ele é " aaaa/MM/dd ".

Se uma cadeia de caracteres de formato padrão em uma operação de formatação aponta para uma cadeia de caracteres de formato personalizado de uma cultura, seu aplicativo pode definir a cultura específica cujas cadeias de caracteres de formato personalizado são usadas de uma dessas maneiras:

• Você pode usar a cultura padrão (ou atual). O exemplo a seguir exibe uma data usando o formato de data abreviada da cultura atual. Nesse caso, a cultura atual é en-US.

  // Display using current (en-us) culture's short date format
  DateTime thisDate = new DateTime(2008, 3, 15);
  Console.WriteLine(thisDate.ToString("d"));           // Displays 3/15/2008
  

  ' Display using current (en-us) culture's short date format
  Dim thisDate As Date = #03/15/2008#
  Console.WriteLine(thisDate.ToString("d"))     ' Displays 3/15/2008
  

• Você pode passar um objeto CultureInfo que representa a cultura cuja formatação deve ser usada para um método que tenha um parâmetro IFormatProvider. O exemplo a seguir exibe uma data usando o formato de data abreviada da cultura pt-BR.

  // Display using pt-BR culture's short date format
  DateTime thisDate = new DateTime(2008, 3, 15);
  CultureInfo culture = new CultureInfo("pt-BR");
  Console.WriteLine(thisDate.ToString("d", culture));  // Displays 15/3/2008
  

  ' Display using pt-BR culture's short date format
  Dim thisDate As Date = #03/15/2008#
  Dim culture As New CultureInfo("pt-BR")
  Console.WriteLine(thisDate.ToString("d", culture))   ' Displays 15/3/2008
  

• Você pode passar um objeto DateTimeFormatInfo que fornece informações de formatação para um método que tem um parâmetro IFormatProvider. O exemplo a seguir exibe uma data usando o formato de data curta de um objeto DateTimeFormatInfo para a cultura hr-HR.

  // Display using date format information from hr-HR culture
  DateTime thisDate = new DateTime(2008, 3, 15);
  DateTimeFormatInfo fmt = (new CultureInfo("hr-HR")).DateTimeFormat;
  Console.WriteLine(thisDate.ToString("d", fmt));      // Displays 15.3.2008
  

  ' Display using date format information from hr-HR culture
  Dim thisDate As Date = #03/15/2008#
  Dim fmt As DateTimeFormatInfo = (New CultureInfo("hr-HR")).DateTimeFormat
  Console.WriteLine(thisDate.ToString("d", fmt))   ' Displays 15.3.2008
  

Em alguns casos, a cadeia de caracteres de formato padrão funciona como uma abreviação conveniente de uma cadeia de caracteres de formato personalizado maior que é invariável. Quatro cadeias de caracteres de formato padrão se enquadram nesta categoria: "O" (ou "o"), "R" (ou "r"), "s" e "u". Estas cadeias de caracteres correspondem às cadeias de caracteres de formato personalizado definidas pela cultura invariável. Elas produzem representações de cadeias de caracteres de valores de data e hora que são feitos para ser idênticos entre culturas. A tabela a seguir fornece informações sobre essas quatro cadeias de caracteres de formato de data e hora padrão.

Cadeias de caracteres de formato padrão também podem ser usadas na análise de operações com os DateTime.ParseExactmétodos , DateTimeOffset.ParseExacte DateOnly.ParseExactTimeOnly.ParseExact , que exigem uma cadeia de caracteres de entrada para estar exatamente em conformidade com um padrão específico para que a operação de análise tenha êxito. Muitas cadeias de caracteres de formato padrão são mapeadas para várias cadeias de caracteres de formato personalizado, portanto, um valor de data e hora pode ser representado em uma variedade de formatos e a operação de análise ainda será bem-sucedida. Você pode determinar a cadeia de caracteres de formato personalizado ou cadeias de caracteres que correspondem a uma cadeia de caracteres de formato padrão chamando o método DateTimeFormatInfo.GetAllDateTimePatterns(Char). O exemplo a seguir exibe as cadeias de caracteres de formato personalizado que são mapeadas para a cadeia de caracteres de formato padrão "d" (padrão de data curta).

using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {
      Console.WriteLine("'d' standard format string:");
      foreach (var customString in DateTimeFormatInfo.CurrentInfo.GetAllDateTimePatterns('d'))
          Console.WriteLine($"   {customString}");
   }
}
// The example displays the following output:
//       'd' standard format string:
//          M/d/yyyy
//          M/d/yy
//          MM/dd/yy
//          MM/dd/yyyy
//          yy/MM/dd
//          yyyy-MM-dd
//          dd-MMM-yy

Imports System.Globalization

Module Example
    Public Sub Main()
        Console.WriteLine("'d' standard format string:")
        For Each customString In DateTimeFormatInfo.CurrentInfo.GetAllDateTimePatterns("d"c)
            Console.WriteLine("   {0}", customString)
        Next
    End Sub
End Module
' The example displays the following output:
'    'd' standard format string:
'       M/d/yyyy
'       M/d/yy
'       MM/dd/yy
'       MM/dd/yyyy
'       yy/MM/dd
'       yyyy-MM-dd
'       dd-MMM-yy

As seções a seguir descrevem os especificadores de formato padrão para DateTime, DateTimeOffsete DateOnlyTimeOnly valores.

Formatos de data

Esse grupo inclui os seguintes formatos:

• Especificador de formato de data abreviada ("d")
• Especificador de formato de data completa ("D")

Especificador de formato de data abreviada ("d")

O especificador de formato padrão "d" representa uma cadeia de caracteres de formato de data e hora personalizada definida pela propriedade DateTimeFormatInfo.ShortDatePattern de uma cultura específica. Por exemplo, a cadeia de caracteres de formato personalizado retornada pela propriedade ShortDatePattern da cultura invariável é "MM/dd/yyyyy".

A tabela a seguir lista as propriedades do objeto DateTimeFormatInfo que controlam a formatação da cadeia de caracteres retornada.

O exemplo a seguir usa o especificador de formato "d" para exibir um valor de data e hora.

DateTime date1 = new DateTime(2008,4, 10);
Console.WriteLine(date1.ToString("d", DateTimeFormatInfo.InvariantInfo));
// Displays 04/10/2008
Console.WriteLine(date1.ToString("d",
                  CultureInfo.CreateSpecificCulture("en-US")));
// Displays 4/10/2008
Console.WriteLine(date1.ToString("d",
                  CultureInfo.CreateSpecificCulture("en-NZ")));
// Displays 10/04/2008
Console.WriteLine(date1.ToString("d",
                  CultureInfo.CreateSpecificCulture("de-DE")));
// Displays 10.04.2008

Dim date1 As Date = #4/10/2008#
Console.WriteLine(date1.ToString("d", DateTimeFormatInfo.InvariantInfo))
' Displays 04/10/2008
Console.WriteLine(date1.ToString("d", _
                  CultureInfo.CreateSpecificCulture("en-US")))
' Displays 4/10/2008                       
Console.WriteLine(date1.ToString("d", _
                  CultureInfo.CreateSpecificCulture("en-NZ")))
' Displays 10/04/2008                       
Console.WriteLine(date1.ToString("d", _
                  CultureInfo.CreateSpecificCulture("de-DE")))
' Displays 10.04.2008                       

Voltar à tabela

Especificador de formato de data completa ("D")

O especificador de formato padrão "D" representa uma cadeia de caracteres de formato de data e hora personalizada definida pela propriedade DateTimeFormatInfo.LongDatePattern atual. Por exemplo, a cadeia de caracteres de formato personalizado para a cultura invariável é "dddd, dd MMMM aaaa".

A tabela a seguir lista as propriedades do objeto DateTimeFormatInfo que controlam a formatação da cadeia de caracteres retornada.

O exemplo a seguir utiliza o especificador de formato "D" para exibir um valor de data e hora.

DateTime date1 = new DateTime(2008, 4, 10);
Console.WriteLine(date1.ToString("D",
                  CultureInfo.CreateSpecificCulture("en-US")));
// Displays Thursday, April 10, 2008
Console.WriteLine(date1.ToString("D",
                  CultureInfo.CreateSpecificCulture("pt-BR")));
// Displays quinta-feira, 10 de abril de 2008
Console.WriteLine(date1.ToString("D",
                  CultureInfo.CreateSpecificCulture("es-MX")));
// Displays jueves, 10 de abril de 2008

Dim date1 As Date = #4/10/2008#
Console.WriteLine(date1.ToString("D", _
                  CultureInfo.CreateSpecificCulture("en-US")))
' Displays Thursday, April 10, 2008                        
Console.WriteLine(date1.ToString("D", _
                  CultureInfo.CreateSpecificCulture("pt-BR")))
' Displays quinta-feira, 10 de abril de 2008                        
Console.WriteLine(date1.ToString("D", _
                  CultureInfo.CreateSpecificCulture("es-MX")))
' Displays jueves, 10 de abril de 2008                        

Voltar à tabela

Formatos de data e hora

Esse grupo inclui os seguintes formatos:

• Especificador de formato de data completa e hora abreviada ("f")
• Especificador de formato de data completa e hora completa (“F”)
• Especificador de formato de data geral e hora abreviada (“g”)
• Especificador de formato de data geral e hora completa (“G”)
• Especificador de formato de ida e volta ("O", "o")
• Especificador de formato RFC1123 ("R", "r")
• Especificador de formato classificável ("s")
• Especificador de formato classificável universal ("u")
• O especificador de formato completo universal ("U")

Especificador de formato de data completa e hora abreviada ("f")

O especificador de formato padrão "f" representa uma combinação dos padrões de data completa ("D") e hora abreviada ("t"), separados por um espaço.

A cadeia de caracteres de resultado é afetada pelas informações de formatação de um objeto DateTimeFormatInfo específico. A tabela a seguir lista as propriedades do objeto DateTimeFormatInfo que podem controlar a formatação da cadeia de caracteres retornada. O especificador de formato personalizado retornado pelas propriedades DateTimeFormatInfo.LongDatePattern e DateTimeFormatInfo.ShortTimePattern de algumas culturas pode não usar todas as propriedades.

O exemplo a seguir utiliza o especificador de formato "f" para exibir um valor de data e hora.

DateTime date1 = new DateTime(2008, 4, 10, 6, 30, 0);
Console.WriteLine(date1.ToString("f",
                  CultureInfo.CreateSpecificCulture("en-US")));
// Displays Thursday, April 10, 2008 6:30 AM
Console.WriteLine(date1.ToString("f",
                  CultureInfo.CreateSpecificCulture("fr-FR")));
// Displays jeudi 10 avril 2008 06:30

Dim date1 As Date = #4/10/2008 6:30AM#
Console.WriteLine(date1.ToString("f", _
                  CultureInfo.CreateSpecificCulture("en-US")))
' Displays Thursday, April 10, 2008 6:30 AM                        
Console.WriteLine(date1.ToString("f", _
                  CultureInfo.CreateSpecificCulture("fr-FR")))
' Displays jeudi 10 avril 2008 06:30                       

Voltar à tabela

Especificador de formato de data completa e hora completa (“F”)

O especificador de formato padrão "F" representa uma cadeia de caracteres de formato de data e hora personalizada definida pela propriedade DateTimeFormatInfo.FullDateTimePattern atual. Por exemplo, a cadeia de caracteres de formato personalizado para a cultura invariável é "dddd, dd MMMM aaaa HH:mm:ss".

A tabela a seguir lista as propriedades do objeto DateTimeFormatInfo que podem controlar a formatação da cadeia de caracteres retornada. O especificador de formato personalizado retornado pela propriedade FullDateTimePattern de algumas culturas pode não usar todas as propriedades.

O exemplo a seguir utiliza o especificador de formato "F" para exibir um valor de data e hora.

DateTime date1 = new DateTime(2008, 4, 10, 6, 30, 0);
Console.WriteLine(date1.ToString("F",
                  CultureInfo.CreateSpecificCulture("en-US")));
// Displays Thursday, April 10, 2008 6:30:00 AM
Console.WriteLine(date1.ToString("F",
                  CultureInfo.CreateSpecificCulture("fr-FR")));
// Displays jeudi 10 avril 2008 06:30:00

Dim date1 As Date = #4/10/2008 6:30AM#
Console.WriteLine(date1.ToString("F", _
                  CultureInfo.CreateSpecificCulture("en-US")))
' Displays Thursday, April 10, 2008 6:30:00 AM                        
Console.WriteLine(date1.ToString("F", _
                  CultureInfo.CreateSpecificCulture("fr-FR")))
' Displays jeudi 10 avril 2008 06:30:00                       

Voltar à tabela

Especificador de formato de data geral e hora abreviada (“g”)

O especificador de formato padrão "g" representa uma combinação dos padrões de data abreviada ("d") e hora abreviada ("t"), separados por um espaço.

A cadeia de caracteres de resultado é afetada pelas informações de formatação de um objeto DateTimeFormatInfo específico. A tabela a seguir lista as propriedades do objeto DateTimeFormatInfo que podem controlar a formatação da cadeia de caracteres retornada. O especificador de formato personalizado retornado pelas propriedades DateTimeFormatInfo.ShortDatePattern e DateTimeFormatInfo.ShortTimePattern de algumas culturas pode não usar todas as propriedades.

O exemplo a seguir utiliza o especificador de formato "g" para exibir um valor de data e hora.

DateTime date1 = new DateTime(2008, 4, 10, 6, 30, 0);
Console.WriteLine(date1.ToString("g",
                  DateTimeFormatInfo.InvariantInfo));
// Displays 04/10/2008 06:30
Console.WriteLine(date1.ToString("g",
                  CultureInfo.CreateSpecificCulture("en-us")));
// Displays 4/10/2008 6:30 AM
Console.WriteLine(date1.ToString("g",
                  CultureInfo.CreateSpecificCulture("fr-BE")));
// Displays 10/04/2008 6:30

Dim date1 As Date = #4/10/2008 6:30AM#
Console.WriteLine(date1.ToString("g", _
                  DateTimeFormatInfo.InvariantInfo))
' Displays 04/10/2008 06:30                      
Console.WriteLine(date1.ToString("g", _
                  CultureInfo.CreateSpecificCulture("en-us")))
' Displays 4/10/2008 6:30 AM                       
Console.WriteLine(date1.ToString("g", _
                  CultureInfo.CreateSpecificCulture("fr-BE")))
' Displays 10/04/2008 6:30                        

Voltar à tabela

Especificador de formato de data geral e hora completa (“G”)

O especificador de formato padrão "G" representa uma combinação dos padrões de data abreviada ("d") e hora completa ("T"), separados por um espaço.

A cadeia de caracteres de resultado é afetada pelas informações de formatação de um objeto DateTimeFormatInfo específico. A tabela a seguir lista as propriedades do objeto DateTimeFormatInfo que podem controlar a formatação da cadeia de caracteres retornada. O especificador de formato personalizado retornado pelas propriedades DateTimeFormatInfo.ShortDatePattern e DateTimeFormatInfo.LongTimePattern de algumas culturas pode não usar todas as propriedades.

O exemplo a seguir utiliza o especificador de formato "G" para exibir um valor de data e hora.

DateTime date1 = new DateTime(2008, 4, 10, 6, 30, 0);
Console.WriteLine(date1.ToString("G",
                  DateTimeFormatInfo.InvariantInfo));
// Displays 04/10/2008 06:30:00
Console.WriteLine(date1.ToString("G",
                  CultureInfo.CreateSpecificCulture("en-us")));
// Displays 4/10/2008 6:30:00 AM
Console.WriteLine(date1.ToString("G",
                  CultureInfo.CreateSpecificCulture("nl-BE")));
// Displays 10/04/2008 6:30:00

Dim date1 As Date = #4/10/2008 6:30AM#
Console.WriteLine(date1.ToString("G", _
                  DateTimeFormatInfo.InvariantInfo))
' Displays 04/10/2008 06:30:00
Console.WriteLine(date1.ToString("G", _
                  CultureInfo.CreateSpecificCulture("en-us")))
' Displays 4/10/2008 6:30:00 AM                        
Console.WriteLine(date1.ToString("G", _
                  CultureInfo.CreateSpecificCulture("nl-BE")))
' Displays 10/04/2008 6:30:00                       

Voltar à tabela

Especificador de formato de ida e volta ("O", "o")

O especificador de formato padrão "O" ou "o" representa uma cadeia de caracteres de data e hora personalizada usando um padrão que preserva as informações de fuso horário e emite uma cadeia de caracteres de resultado compilada com ISO 8601. Para valores DateTime, esse especificador de formato foi projetado para preservar valores de data e hora, juntamente com a propriedade DateTime.Kind no texto. A cadeia de caracteres formatada poderá ser analisada novamente usando o método DateTime.Parse(String, IFormatProvider, DateTimeStyles) ou DateTime.ParseExact se o parâmetro styles estiver definido como DateTimeStyles.RoundtripKind.

Para DateOnly valores, esse especificador de formato produz uma cadeia de caracteres ISO 8601 somente data no formato "yyyy-MM-dd". Para TimeOnly valores, ele produz uma cadeia de caracteres ISO 8601 somente tempo no formato "HH:mm:ss.fffffff".

O especificador de formato padrão "O" ou "o" corresponde ao "yyyy'-'MM'-'dd'T'HH':'mm':'ss'.' fffffffK" cadeia de caracteres de formato personalizado para valores DateTime e para o "yyyyy'-'MM'-'dd'T'HH':'mm':'ss'.' cadeia de caracteres de formato personalizado fffffffzzz" para valores DateTimeOffset. Nesta cadeia de caracteres, os pares de aspas simples que delimitam caracteres individuais, como os hífens, os dois-pontos e a letra "T", indicam que o caractere individual é um literal que não pode ser alterado. Os apóstrofos não aparecem na cadeia de caracteres de saída.

O especificador de formato padrão "O" ou "o" (e o "yyy'-'MM'-'dd'T'HH':'mm':'ss'.' A cadeia de caracteres de formato personalizado fffffffK) aproveita as três maneiras pelas quais o ISO 8601 representa informações de fuso horário para preservar a propriedade Kind de valores DateTime:

• O componente de fuso horário de DateTimeKind.Local valores de data e hora é um deslocamento de UTC (por exemplo, +01:00, -07:00). Todos os valores DateTimeOffset também são representados nesse formato.

• O componente de fuso horário de DateTimeKind.Utc valores de data e hora usa "Z" (que significa deslocamento zero) para representar UTC.

• DateTimeKind.Unspecified valores de data e hora não têm informações de fuso horário.

Como o especificador de formato padrão "O" ou "o" está de acordo com um padrão internacional, a operação de formatação ou análise que usa o especificador sempre usa a cultura invariável e o calendário gregoriano.

Cadeias de caracteres que são passadas para o ParseTryParse, , ParseExacte TryParseExact métodos de DateTime, DateTimeOffsetDateOnlye TimeOnly podem ser analisadas usando o especificador de formato "O" ou "o" se estiverem em um desses formatos. No caso de objetos DateTime, a sobrecarga de análise que você chama também deve incluir um parâmetro styles com um valor de DateTimeStyles.RoundtripKind. Observe que se você chamar um método de análise com a cadeia de caracteres de formato personalizado que corresponde ao especificador de formato "O" ou "o", você não obterá os mesmos resultados que "O" ou "o". Isso ocorre porque os métodos de análise que usam uma cadeia de caracteres de formato personalizado não podem analisar a representação de cadeia de caracteres de valores de data e hora que não têm um componente de fuso horário ou usam "Z" para indicar UTC.

O exemplo a seguir usa o especificador de formato "o" para exibir uma série de valores de DateTime e um valor DateTimeOffset em um sistema no fuso horário do Pacífico dos EUA.

using System;

public class Example
{
   public static void Main()
   {
       DateTime dat = new DateTime(2009, 6, 15, 13, 45, 30,
                                   DateTimeKind.Unspecified);
       Console.WriteLine($"{dat} ({dat.Kind}) --> {dat:O}");

       DateTime uDat = new DateTime(2009, 6, 15, 13, 45, 30,
                                    DateTimeKind.Utc);
       Console.WriteLine($"{uDat} ({uDat.Kind}) --> {uDat:O}");

       DateTime lDat = new DateTime(2009, 6, 15, 13, 45, 30,
                                    DateTimeKind.Local);
       Console.WriteLine($"{lDat} ({lDat.Kind}) --> {lDat:O}\n");

       DateTimeOffset dto = new DateTimeOffset(lDat);
       Console.WriteLine($"{dto} --> {dto:O}");
   }
}
// The example displays the following output:
//    6/15/2009 1:45:30 PM (Unspecified) --> 2009-06-15T13:45:30.0000000
//    6/15/2009 1:45:30 PM (Utc) --> 2009-06-15T13:45:30.0000000Z
//    6/15/2009 1:45:30 PM (Local) --> 2009-06-15T13:45:30.0000000-07:00
//
//    6/15/2009 1:45:30 PM -07:00 --> 2009-06-15T13:45:30.0000000-07:00

Module Example
    Public Sub Main()
        Dim dat As New Date(2009, 6, 15, 13, 45, 30,
                            DateTimeKind.Unspecified)
        Console.WriteLine("{0} ({1}) --> {0:O}", dat, dat.Kind)

        Dim uDat As New Date(2009, 6, 15, 13, 45, 30, DateTimeKind.Utc)
        Console.WriteLine("{0} ({1}) --> {0:O}", uDat, uDat.Kind)

        Dim lDat As New Date(2009, 6, 15, 13, 45, 30, DateTimeKind.Local)
        Console.WriteLine("{0} ({1}) --> {0:O}", lDat, lDat.Kind)
        Console.WriteLine()

        Dim dto As New DateTimeOffset(lDat)
        Console.WriteLine("{0} --> {0:O}", dto)
    End Sub
End Module
' The example displays the following output:
'    6/15/2009 1:45:30 PM (Unspecified) --> 2009-06-15T13:45:30.0000000
'    6/15/2009 1:45:30 PM (Utc) --> 2009-06-15T13:45:30.0000000Z
'    6/15/2009 1:45:30 PM (Local) --> 2009-06-15T13:45:30.0000000-07:00
'    
'    6/15/2009 1:45:30 PM -07:00 --> 2009-06-15T13:45:30.0000000-07:00

O exemplo a seguir usa o especificador de formato "o" para criar uma cadeia de caracteres formatada e restaura o valor original de data e hora chamando um método de data e hora Parse.

// Round-trip DateTime values.
DateTime originalDate, newDate;
string dateString;
// Round-trip a local time.
originalDate = DateTime.SpecifyKind(new DateTime(2008, 4, 10, 6, 30, 0), DateTimeKind.Local);
dateString = originalDate.ToString("o");
newDate = DateTime.Parse(dateString, null, DateTimeStyles.RoundtripKind);
Console.WriteLine($"Round-tripped {originalDate} {originalDate.Kind} to {newDate} {newDate.Kind}.");
// Round-trip a UTC time.
originalDate = DateTime.SpecifyKind(new DateTime(2008, 4, 12, 9, 30, 0), DateTimeKind.Utc);
dateString = originalDate.ToString("o");
newDate = DateTime.Parse(dateString, null, DateTimeStyles.RoundtripKind);
Console.WriteLine($"Round-tripped {originalDate} {originalDate.Kind} to {newDate} {newDate.Kind}.");
// Round-trip time in an unspecified time zone.
originalDate = DateTime.SpecifyKind(new DateTime(2008, 4, 13, 12, 30, 0), DateTimeKind.Unspecified);
dateString = originalDate.ToString("o");
newDate = DateTime.Parse(dateString, null, DateTimeStyles.RoundtripKind);
Console.WriteLine($"Round-tripped {originalDate} {originalDate.Kind} to {newDate} {newDate.Kind}.");

// Round-trip a DateTimeOffset value.
DateTimeOffset originalDTO = new DateTimeOffset(2008, 4, 12, 9, 30, 0, new TimeSpan(-8, 0, 0));
dateString = originalDTO.ToString("o");
DateTimeOffset newDTO = DateTimeOffset.Parse(dateString, null, DateTimeStyles.RoundtripKind);
Console.WriteLine($"Round-tripped {originalDTO} to {newDTO}.");
// The example displays the following output:
//    Round-tripped 4/10/2008 6:30:00 AM Local to 4/10/2008 6:30:00 AM Local.
//    Round-tripped 4/12/2008 9:30:00 AM Utc to 4/12/2008 9:30:00 AM Utc.
//    Round-tripped 4/13/2008 12:30:00 PM Unspecified to 4/13/2008 12:30:00 PM Unspecified.
//    Round-tripped 4/12/2008 9:30:00 AM -08:00 to 4/12/2008 9:30:00 AM -08:00.

' Round-trip DateTime values.
Dim originalDate, newDate As Date
Dim dateString As String
' Round-trip a local time.
originalDate = Date.SpecifyKind(#4/10/2008 6:30AM#, DateTimeKind.Local)
dateString = originalDate.ToString("o")
newDate = Date.Parse(dateString, Nothing, DateTimeStyles.RoundtripKind)
Console.WriteLine("Round-tripped {0} {1} to {2} {3}.", originalDate, originalDate.Kind, _
                  newDate, newDate.Kind)
' Round-trip a UTC time.
originalDate = Date.SpecifyKind(#4/12/2008 9:30AM#, DateTimeKind.Utc)
dateString = originalDate.ToString("o")
newDate = Date.Parse(dateString, Nothing, DateTimeStyles.RoundtripKind)
Console.WriteLine("Round-tripped {0} {1} to {2} {3}.", originalDate, originalDate.Kind, _
                  newDate, newDate.Kind)
' Round-trip time in an unspecified time zone.
originalDate = Date.SpecifyKind(#4/13/2008 12:30PM#, DateTimeKind.Unspecified)
dateString = originalDate.ToString("o")
newDate = Date.Parse(dateString, Nothing, DateTimeStyles.RoundtripKind)
Console.WriteLine("Round-tripped {0} {1} to {2} {3}.", originalDate, originalDate.Kind, _
                  newDate, newDate.Kind)

' Round-trip a DateTimeOffset value.
Dim originalDTO As New DateTimeOffset(#4/12/2008 9:30AM#, New TimeSpan(-8, 0, 0))
dateString = originalDTO.ToString("o")
Dim newDTO As DateTimeOffset = DateTimeOffset.Parse(dateString, Nothing, DateTimeStyles.RoundtripKind)
Console.WriteLine("Round-tripped {0} to {1}.", originalDTO, newDTO)
' The example displays the following output:
'    Round-tripped 4/10/2008 6:30:00 AM Local to 4/10/2008 6:30:00 AM Local.
'    Round-tripped 4/12/2008 9:30:00 AM Utc to 4/12/2008 9:30:00 AM Utc.
'    Round-tripped 4/13/2008 12:30:00 PM Unspecified to 4/13/2008 12:30:00 PM Unspecified.
'    Round-tripped 4/12/2008 9:30:00 AM -08:00 to 4/12/2008 9:30:00 AM -08:00.

Voltar à tabela

Especificador de formato RFC1123 ("R", "r")

O especificador de formato padrão "R" ou "r" representa uma cadeia de caracteres de formato de data e hora personalizada definida pela propriedade DateTimeFormatInfo.RFC1123Pattern. O padrão reflete um padrão definido e a propriedade é somente leitura. Portanto, ele é sempre o mesmo, independentemente da cultura usada ou do provedor de formato fornecido. A cadeia de caracteres de formato personalizado é "ddd, dd MMM aaaa HH':'mm':'ss 'GMT' ". Quando esse especificador de formato padrão é usado, a operação de formatação ou análise sempre usa a cultura invariável.

A cadeia de caracteres de resultado é afetada pelas propriedades a seguir do objeto DateTimeFormatInfo retornado pela propriedade DateTimeFormatInfo.InvariantInfo que representa a cultura invariável.

Embora o padrão RFC 1123 expresse um tempo como UTC (Tempo Universal Coordenado), a operação de formatação não modifica o valor do objeto DateTime que está sendo formatado. Portanto, você deve converter o valor DateTime em UTC chamando o método DateTime.ToUniversalTime antes de executar a operação de formatação. Por outro lado, DateTimeOffset valores executam essa conversão automaticamente; não é necessário chamar o método DateTimeOffset.ToUniversalTime antes da operação de formatação.

O exemplo a seguir usa o especificador de formato "r" para exibir um DateTime e um valor DateTimeOffset em um sistema no fuso horário do Pacífico dos EUA.

DateTime date1 = new DateTime(2008, 4, 10, 6, 30, 0);
DateTimeOffset dateOffset = new DateTimeOffset(date1,
                            TimeZoneInfo.Local.GetUtcOffset(date1));
Console.WriteLine(date1.ToUniversalTime().ToString("r"));
// Displays Thu, 10 Apr 2008 13:30:00 GMT
Console.WriteLine(dateOffset.ToUniversalTime().ToString("r"));
// Displays Thu, 10 Apr 2008 13:30:00 GMT

Dim date1 As Date = #4/10/2008 6:30AM#
Dim dateOffset As New DateTimeOffset(date1, TimeZoneInfo.Local.GetUtcOFfset(date1))
Console.WriteLine(date1.ToUniversalTime.ToString("r"))
' Displays Thu, 10 Apr 2008 13:30:00 GMT                       
Console.WriteLine(dateOffset.ToUniversalTime.ToString("r"))
' Displays Thu, 10 Apr 2008 13:30:00 GMT                        

Voltar à tabela

Especificador de formato classificável ("s")

O especificador de formato padrão "s" representa uma cadeia de caracteres de formato de data e hora personalizada definida pela propriedade DateTimeFormatInfo.SortableDateTimePattern. O padrão reflete um padrão definido (ISO 8601) e a propriedade é somente leitura. Portanto, ele é sempre o mesmo, independentemente da cultura usada ou do provedor de formato fornecido. A cadeia de caracteres de formato personalizado é "aaaa'-'MM'-'dd'T'HH':'mm':'ss".

A finalidade do especificador de formato "s" é produzir cadeias de caracteres de resultado que classificam consistentemente em ordem crescente ou decrescente com base nos valores de data e hora. Como resultado, embora o especificador de formato padrão "s" represente um valor de data e hora em um formato consistente, a operação de formatação não modifica o valor do objeto de data e hora que está sendo formatado para refletir sua propriedade DateTime.Kind ou seu valor DateTimeOffset.Offset. Por exemplo, as cadeias de caracteres de resultado produzidas pela formatação dos valores de data e hora 2014-11-15T18:32:17+00:00 e 2014-11-15T18:32:17+08:00 são idênticas.

Quando esse especificador de formato padrão é usado, a operação de formatação ou análise sempre usa a cultura invariável.

O exemplo a seguir usa o especificador de formato "s" para exibir um DateTime e um valor DateTimeOffset em um sistema no fuso horário do Pacífico dos EUA.

DateTime date1 = new DateTime(2008, 4, 10, 6, 30, 0);
Console.WriteLine(date1.ToString("s"));
// Displays 2008-04-10T06:30:00

Dim date1 As Date = #4/10/2008 6:30AM#
Console.WriteLine(date1.ToString("s"))
' Displays 2008-04-10T06:30:00                       

Voltar à tabela

Especificador de formato classificável universal ("u")

O especificador de formato padrão "u" representa uma cadeia de caracteres de formato de data e hora personalizada definida pela propriedade DateTimeFormatInfo.UniversalSortableDateTimePattern. O padrão reflete um padrão definido e a propriedade é somente leitura. Portanto, ele é sempre o mesmo, independentemente da cultura usada ou do provedor de formato fornecido. A cadeia de caracteres de formato personalizado é "aaaa'-'MM'-'dd HH':'mm':'ss'Z'". Quando esse especificador de formato padrão é usado, a operação de formatação ou análise sempre usa a cultura invariável.

Embora a cadeia de caracteres de resultado deva expressar um tempo como UTC (Tempo Universal Coordenado), nenhuma conversão do valor de DateTime original é executada durante a operação de formatação. Portanto, você deve converter um valor de DateTime em UTC chamando o método DateTime.ToUniversalTime antes de formatá-lo. Por outro lado, DateTimeOffset valores executam essa conversão automaticamente; não é necessário chamar o método DateTimeOffset.ToUniversalTime antes da operação de formatação.

O exemplo a seguir utiliza o especificador de formato "u" para exibir um valor de data e hora.

DateTime date1 = new DateTime(2008, 4, 10, 6, 30, 0);
Console.WriteLine(date1.ToUniversalTime().ToString("u"));
// Displays 2008-04-10 13:30:00Z

Dim date1 As Date = #4/10/2008 6:30AM#
Console.WriteLine(date1.ToUniversalTime.ToString("u"))
' Displays 2008-04-10 13:30:00Z                       

Voltar à tabela

O especificador de formato completo universal ("U")

O especificador de formato padrão "U" representa uma cadeia de caracteres de formato de data e hora personalizada definida pela propriedade DateTimeFormatInfo.FullDateTimePattern de uma cultura especificada. O padrão é o mesmo que o padrão "F". No entanto, o valor DateTime é convertido automaticamente em UTC antes de ser formatado.

A tabela a seguir lista as propriedades do objeto DateTimeFormatInfo que podem controlar a formatação da cadeia de caracteres retornada. O especificador de formato personalizado retornado pela propriedade FullDateTimePattern de algumas culturas pode não usar todas as propriedades.

O especificador de formato "U" não tem suporte do tipo DateTimeOffset e lança um FormatException se ele for usado para formatar um valor DateTimeOffset.

O exemplo a seguir usa o especificador de formato "U" para exibir um valor de data e hora.

DateTime date1 = new DateTime(2008, 4, 10, 6, 30, 0);
Console.WriteLine(date1.ToString("U",
                  CultureInfo.CreateSpecificCulture("en-US")));
// Displays Thursday, April 10, 2008 1:30:00 PM
Console.WriteLine(date1.ToString("U",
                  CultureInfo.CreateSpecificCulture("sv-FI")));
// Displays den 10 april 2008 13:30:00

Dim date1 As Date = #4/10/2008 6:30AM#
Console.WriteLine(date1.ToString("U", CultureInfo.CreateSpecificCulture("en-US")))
' Displays Thursday, April 10, 2008 1:30:00 PM                       
Console.WriteLine(date1.ToString("U", CultureInfo.CreateSpecificCulture("sv-FI")))
' Displays den 10 april 2008 13:30:00                       

Voltar à tabela

Formatos de hora

Esse grupo inclui os seguintes formatos:

• Especificador de formato de hora abreviada ("t")
• Especificador de formato de hora completa ("T")

Especificador de formato de hora abreviada ("t")

O especificador de formato padrão "t" representa uma cadeia de caracteres de formato de data e hora personalizada definida pela propriedade DateTimeFormatInfo.ShortTimePattern atual. Por exemplo, a cadeia de caracteres de formato personalizado para a cultura invariável é "HH:mm".

A cadeia de caracteres de resultado é afetada pelas informações de formatação de um objeto DateTimeFormatInfo específico. A tabela a seguir lista as propriedades do objeto DateTimeFormatInfo que podem controlar a formatação da cadeia de caracteres retornada. O especificador de formato personalizado retornado pela propriedade DateTimeFormatInfo.ShortTimePattern de algumas culturas pode não usar todas as propriedades.

O exemplo a seguir utiliza o especificador de formato "t" para exibir um valor de data e hora.

DateTime date1 = new DateTime(2008, 4, 10, 6, 30, 0);
Console.WriteLine(date1.ToString("t",
                  CultureInfo.CreateSpecificCulture("en-us")));
// Displays 6:30 AM
Console.WriteLine(date1.ToString("t",
                  CultureInfo.CreateSpecificCulture("es-ES")));
// Displays 6:30

Dim date1 As Date = #4/10/2008 6:30AM#
Console.WriteLine(date1.ToString("t", _
                  CultureInfo.CreateSpecificCulture("en-us")))
' Displays 6:30 AM                        
Console.WriteLine(date1.ToString("t", _
                  CultureInfo.CreateSpecificCulture("es-ES")))
' Displays 6:30                      

Voltar à tabela

Especificador de formato de hora completa ("T")

O especificador de formato padrão "T" representa uma cadeia de caracteres de formato de data e hora personalizada definida pela propriedade DateTimeFormatInfo.LongTimePattern de uma cultura específica. Por exemplo, a cadeia de caracteres de formato personalizado para a cultura invariável é "HH:mm:ss".

A tabela a seguir lista as propriedades do objeto DateTimeFormatInfo que podem controlar a formatação da cadeia de caracteres retornada. O especificador de formato personalizado retornado pela propriedade DateTimeFormatInfo.LongTimePattern de algumas culturas pode não usar todas as propriedades.

O exemplo a seguir utiliza o especificador de formato "T" para exibir um valor de data e hora.

DateTime date1 = new DateTime(2008, 4, 10, 6, 30, 0);
Console.WriteLine(date1.ToString("T",
                  CultureInfo.CreateSpecificCulture("en-us")));
// Displays 6:30:00 AM
Console.WriteLine(date1.ToString("T",
                  CultureInfo.CreateSpecificCulture("es-ES")));
// Displays 6:30:00

Dim date1 As Date = #4/10/2008 6:30AM#
Console.WriteLine(date1.ToString("T", _
                  CultureInfo.CreateSpecificCulture("en-us")))
' Displays 6:30:00 AM                       
Console.WriteLine(date1.ToString("T", _
                  CultureInfo.CreateSpecificCulture("es-ES")))
' Displays 6:30:00                      

Voltar à tabela

Formatos de data parcial

Esse grupo inclui os seguintes formatos:

• Especificador de formato de mês ("M", "m")
• Especificador de formato de ano mês ("Y", "y")

Especificador de formato de mês ("M", "m")

O especificador de formato padrão "M" ou "m" representa uma cadeia de caracteres de formato de data e hora personalizada definida pela propriedade DateTimeFormatInfo.MonthDayPattern atual. Por exemplo, a cadeia de caracteres de formato personalizado para o cultura invariável é "MMMM dd".

A tabela a seguir lista as propriedades do objeto DateTimeFormatInfo que controlam a formatação da cadeia de caracteres retornada.

O exemplo a seguir utiliza o especificador de formato "m" para exibir um valor de data e hora.

DateTime date1 = new DateTime(2008, 4, 10, 6, 30, 0);
Console.WriteLine(date1.ToString("m",
                  CultureInfo.CreateSpecificCulture("en-us")));
// Displays April 10
Console.WriteLine(date1.ToString("m",
                  CultureInfo.CreateSpecificCulture("ms-MY")));
// Displays 10 April

Dim date1 As Date = #4/10/2008 6:30AM#
Console.WriteLine(date1.ToString("m", _
                  CultureInfo.CreateSpecificCulture("en-us")))
' Displays April 10                        
Console.WriteLine(date1.ToString("m", _
                  CultureInfo.CreateSpecificCulture("ms-MY")))
' Displays 10 April                       

Voltar à tabela

Especificador de formato de ano mês ("Y", "y")

O especificador de formato padrão "Y" ou "y" representa uma cadeia de caracteres de formato de data e hora personalizada definida pela propriedade DateTimeFormatInfo.YearMonthPattern de uma cultura especificada. Por exemplo, a cadeia de caracteres de formato personalizado para o cultura invariável é "aaaa MMMM".

A tabela a seguir lista as propriedades do objeto DateTimeFormatInfo que controlam a formatação da cadeia de caracteres retornada.

O exemplo a seguir utiliza o especificador de formato "y" para exibir um valor de data e hora.

DateTime date1 = new DateTime(2008, 4, 10, 6, 30, 0);
Console.WriteLine(date1.ToString("Y",
                  CultureInfo.CreateSpecificCulture("en-US")));
// Displays April, 2008
Console.WriteLine(date1.ToString("y",
                  CultureInfo.CreateSpecificCulture("af-ZA")));
// Displays April 2008

Dim date1 As Date = #4/10/2008 6:30AM#
Console.WriteLine(date1.ToString("Y", CultureInfo.CreateSpecificCulture("en-US")))
' Displays April, 2008                       
Console.WriteLine(date1.ToString("y", CultureInfo.CreateSpecificCulture("af-ZA")))
' Displays April 2008                       

Voltar à tabela

Formatação DateOnly e TimeOnly

DateOnly e TimeOnly os tipos dão suporte a um subconjunto das cadeias de caracteres de formato de data e hora padrão:

• DateOnly dá suporte a especificadores de formato relacionados à data:

  • "d" (data curta), "D" (data longa)
  • "M" ou "m" (mês/dia)
  • "Y" ou "y" (ano/mês)
  • "O" ou "o" (ida e volta, somente porção de data)
  • "R" ou "r" (RFC1123, somente porção de data)

• TimeOnly dá suporte a especificadores de formato relacionados ao tempo:

  • "t" (pouco tempo), "T" (longo tempo)
  • "O" ou "o" (ida e volta, somente porção de tempo)
  • "R" ou "r" (RFC1123, somente porção de tempo)

Especificadores de formato que combinam informações de data e hora (como "f", "F", "g", "G", "s", "u", "U") lançam um FormatException quando usado com DateOnly ou TimeOnly.

Configurações do Painel de Controle

No Windows, as configurações no item Opções Regionais e de Idioma no Painel de Controle influenciam a cadeia de caracteres de resultado produzida por uma operação de formatação. Essas configurações são usadas para inicializar o objeto DateTimeFormatInfo associado à cultura atual, que fornece valores usados para controlar a formatação. Computadores que usam configurações diferentes geram cadeias de caracteres de resultado diferentes.

Além disso, se você usar o construtor CultureInfo(String) para criar uma instância de um novo objeto CultureInfo que representa a mesma cultura da cultura do sistema atual, todas as personalizações estabelecidas pelo item Opções Regionais e de Idioma no Painel de Controle serão aplicadas ao novo objeto CultureInfo. Você pode usar o construtor CultureInfo(String, Boolean) para criar um objeto CultureInfo que não reflete as personalizações de um sistema.

Propriedades DateTimeFormatInfo

A formatação é influenciada por propriedades do objeto DateTimeFormatInfo atual, que é fornecido implicitamente pela cultura atual ou explicitamente pelo parâmetro IFormatProvider do método que invoca a formatação. Para o parâmetro IFormatProvider, seu aplicativo deve especificar um objeto CultureInfo, que representa uma cultura ou um objeto DateTimeFormatInfo, que representa as convenções de formatação de data e hora de uma determinada cultura. Muitos dos especificadores de formato de data e hora padrão são aliases para padrões de formatação definidos por propriedades do objeto DateTimeFormatInfo atual. Seu aplicativo pode alterar o resultado produzido por alguns especificadores de formato de data e hora padrão alterando os padrões de formato de data e hora correspondentes da propriedade DateTimeFormatInfo correspondente.

Consulte também

• System.DateTime
• System.DateTimeOffset
• Tipos de Formatação
• Personalizar a Cadeia de Caracteres de Formato de Data e Hora
• Exemplo de : Utilitário de Formatação do WinForms do .NET Core (C#)
• Exemplo de : Utilitário de Formatação winforms do .NET Core (Visual Basic)