Métodos System.DateTime.ToBinary e FromBinary

Este artigo fornece comentários complementares à documentação de referência para esta API.

Use o ToBinary método para converter o valor do objeto atual DateTime em um valor binário. Posteriormente, use o valor binário e o FromBinary método para recriar o objeto original DateTime .

Importante

Em alguns casos, o DateTime valor retornado pelo FromBinary método não é idêntico ao valor original DateTime fornecido ao ToBinary método. Para obter mais informações, consulte a próxima seção, "Ajuste de hora local".

Uma estrutura de DateTime consiste em um campo de Kind privado, que indica se o valor de hora especificado é baseado em hora local, UTC (Tempo Universal Coordenado) ou nenhum deles, concatenado a um campo de Ticks privado, que contém o número de tiques de 100 nanossegundos que especificam uma data e hora.

Ajuste de hora local

Uma hora local, que é um Tempo Universal Coordenado ajustado para o fuso horário local, é representada por uma DateTime estrutura cuja Kind propriedade tem o valor Local. Ao restaurar um valor local DateTime da representação binária produzida pelo ToBinary método, o FromBinary método pode ajustar o valor recriado para que ele não seja igual ao valor original. Isso pode ocorrer nas seguintes condições:

• Se um objeto local DateTime for serializado em um fuso horário pelo ToBinary método e desserializado em um fuso horário diferente pelo FromBinary método, a hora local representada pelo objeto resultante DateTime será ajustada automaticamente para o segundo fuso horário.

  Por exemplo, considere um DateTime objeto que representa uma hora local de 15h. Um aplicativo que está sendo executado no fuso horário do Pacífico dos EUA usa o ToBinary método para converter esse DateTime objeto em um valor binário. Outro aplicativo que está sendo executado no fuso horário do Leste dos EUA usa o FromBinary método para converter o valor binário em um novo DateTime objeto. O valor do novo objeto DateTime é 18:00, que representa o mesmo ponto no tempo que o valor original das 15:00, mas é ajustado para a hora local no Fuso Horário do Leste.

• Se a representação binária de um valor local DateTime representar uma hora inválida no fuso horário local do sistema no qual FromBinary é chamado, o horário será ajustado para que ele seja válido.

  Por exemplo, a transição do horário padrão para o horário de verão ocorre no fuso horário do Pacífico dos Estados Unidos em 14 de março de 2010, às 2:00 da manhã, quando o horário avança em uma hora, para 3:00 da manhã. Esse intervalo de hora é um tempo inválido, ou seja, um intervalo de tempo que não existe nesse fuso horário. O exemplo a seguir mostra que quando um tempo que se enquadra nesse intervalo é convertido em um valor binário pelo ToBinary método e, em seguida, é restaurado pelo FromBinary método, o valor original é ajustado para se tornar um horário válido. Você pode determinar se um determinado valor de data e hora pode estar sujeito à modificação passando-o para o TimeZoneInfo.IsInvalidTime método, como ilustra o exemplo.

  using System;
  
  public class Example
  {
     public static void Main()
     {
        DateTime localDate = new DateTime(2010, 3, 14, 2, 30, 0, DateTimeKind.Local);
        long binLocal = localDate.ToBinary();
        if (TimeZoneInfo.Local.IsInvalidTime(localDate))
           Console.WriteLine($"{localDate} is an invalid time in the {TimeZoneInfo.Local.StandardName} zone.");
  
        DateTime localDate2 = DateTime.FromBinary(binLocal);
        Console.WriteLine($"{localDate} = {localDate2}: {localDate.Equals(localDate2)}");
     }
  }
  // The example displays the following output:
  //    3/14/2010 2:30:00 AM is an invalid time in the Pacific Standard Time zone.
  //    3/14/2010 2:30:00 AM = 3/14/2010 3:30:00 AM: False
  

  open System
  
  let localDate = DateTime(2010, 3, 14, 2, 30, 0, DateTimeKind.Local)
  let binLocal = localDate.ToBinary()
  if TimeZoneInfo.Local.IsInvalidTime localDate then
      printfn $"{localDate} is an invalid time in the {TimeZoneInfo.Local.StandardName} zone."
  
  let localDate2 = DateTime.FromBinary binLocal
  printfn $"{localDate} = {localDate2}: {localDate.Equals localDate2}"
  
  // The example displays the following output:
  //    3/14/2010 2:30:00 AM is an invalid time in the Pacific Standard Time zone.
  //    3/14/2010 2:30:00 AM = 3/14/2010 3:30:00 AM: False
  

  Module Example
     Public Sub Main()
        Dim localDate As Date = DateTime.SpecifyKind(#03/14/2010 2:30AM#, DateTimeKind.Local)
        Dim binLocal As Long = localDate.ToBinary()
        If TimeZoneInfo.Local.IsInvalidTime(localDate) Then
           Console.WriteLine("{0} is an invalid time in the {1} zone.", _
                             localDate, _
                             TimeZoneInfo.Local.StandardName)
        End If
        Dim localDate2 As Date = DateTime.FromBinary(binLocal)
        Console.WriteLine("{0} = {1}: {2}", _
                          localDate, localDate2, localDate.Equals(localDate2))
     End Sub
  End Module
  ' The example displays the following output:
  '    3/14/2010 2:30:00 AM is an invalid time in the Pacific Standard Time zone.
  '    3/14/2010 2:30:00 AM = 3/14/2010 3:30:00 AM: False