Métodos System.DateTime.ToBinary e FromBinary

Este artigo fornece observações complementares à documentação de referência para essa 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 método para recriar o FromBinary 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 DateTime estrutura consiste em um campo privado, que indica se o valor de hora especificado é baseado na hora local, Tempo Universal Coordenado (UTC) ou nenhum dos dois, concatenado a um campo privado KindTicks , que contém o número de ticks de 100 nanossegundos que especificam uma data e hora.

Ajuste de hora local

Uma hora local, que é uma Hora Universal Coordenada ajustada ao 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 que é produzida pelo ToBinary método, o método pode ajustar o FromBinary valor recriado para que ele não seja igual ao valor original. Isso pode ocorrer nas seguintes condições:

• Se um objeto local for serializado em um fuso horário pelo método e, em seguida, desserializado FromBinary em um fuso horário diferente pelo método, a hora local DateTime representada pelo objeto resultante DateTime será ajustada automaticamente para o segundo fuso ToBinary 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 leste dos EUA usa o método para converter o FromBinary valor binário em um novo DateTime objeto. O valor do novo DateTime objeto é 6 P.M., que representa o mesmo ponto no tempo que o valor original 3 P.M., mas é ajustado para a hora local no fuso horário 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, a hora será ajustada para que seja válida.

  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 tempo 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 método e, em seguida, é restaurado pelo ToBinaryFromBinary método, o valor original é ajustado para se tornar um tempo válido. É possível determinar se um valor de data e hora específico podem estar sujeito à modificação passando-o para o método TimeZoneInfo.IsInvalidTime, como o exemplo ilustra.

  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("{0} is an invalid time in the {1} zone.",
                             localDate,
                             TimeZoneInfo.Local.StandardName);
  
        DateTime localDate2 = DateTime.FromBinary(binLocal);
        Console.WriteLine("{0} = {1}: {2}",
                          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