Metody „System.DateTime.ToBinary” i „FromBinary”

Ten artykuł zawiera dodatkowe uwagi dotyczące dokumentacji referencyjnej dla tego interfejsu API.

ToBinary Użyj metody , aby przekonwertować wartość bieżącego DateTime obiektu na wartość binarną. Następnie użyj wartości binarnej i FromBinary metody , aby ponownie utworzyć oryginalny DateTime obiekt.

Ważne

W niektórych przypadkach zwrócona przez metodę FromBinary wartość nie jest identyczna z oryginalną wartością DateTime przekazaną do metody ToBinary. Aby uzyskać więcej informacji, zobacz następną sekcję "Dostosowanie czasu lokalnego".

Struktura DateTime składa się z pola prywatnego Kind, które wskazuje, czy określona wartość godziny jest oparta na czasie lokalnym, uniwersalnym czasie koordynowanym (UTC) czy ani jeden z nich, połączonego z polem prywatnym Ticks, które zawiera liczbę 100-nanosekundowych znaczników określających datę i godzinę.

Dostosowanie czasu lokalnego

Czas lokalny, który jest uniwersalnym czasem koordynowanym dostosowanym do lokalnej strefy czasowej, jest reprezentowany przez DateTime strukturę, której Kind właściwość ma wartość Local. Podczas przywracania wartości lokalnej DateTime z reprezentacji binarnej, która jest generowana przez ToBinary metodę, metoda może dostosować ponownie utworzoną wartość, FromBinary aby nie była równa oryginalnej wartości. Może to wystąpić w następujących warunkach:

• Jeśli obiekt lokalny DateTime jest serializowany w jednej strefie czasowej przez ToBinary metodę, a następnie deserializowany w innej strefie czasowej przez FromBinary metodę, czas lokalny reprezentowany przez wynikowy DateTime obiekt jest automatycznie dostosowywany do drugiej strefy czasowej.

  Rozważmy na przykład DateTime obiekt reprezentujący lokalny czas 15:00. Aplikacja działająca w strefie czasowej Pacyfiku w USA używa metody ToBinary, aby przekonwertować ten DateTime obiekt na wartość binarną. Inna aplikacja, która jest uruchamiana w strefie czasowej USA Wschodniej, następnie używa metody FromBinary, aby przekonwertować wartość binarną na nowy obiekt DateTime. Wartość nowego DateTime obiektu to 18:00, który reprezentuje ten sam punkt w czasie co oryginalna wartość 15:00, ale jest dostosowywana do czasu lokalnego w strefie czasowej wschodniej.

• Jeśli binarna reprezentacja wartości lokalnej DateTime reprezentuje nieprawidłowy czas w lokalnej strefie czasowej systemu, na którym FromBinary jest wywoływany, czas jest dostosowywany tak, aby był prawidłowy.

  Na przykład przejście z czasu standardowego na czas letni występuje w strefie czasowej Pacyfik Stanów Zjednoczonych 14 marca 2010 r., o godzinie 2:00, kiedy czas upływa o jedną godzinę, do godziny 3:00. Ten interwał godziny jest nieprawidłowym czasem, czyli interwałem czasu, który nie istnieje w tej strefie czasowej. W poniższym przykładzie pokazano, że gdy czas, który mieści się w tym zakresie, jest konwertowany na wartość binarną przez ToBinary metodę, a następnie jest przywracany przez FromBinary metodę, oryginalna wartość jest dostosowywana, aby stała się prawidłową godziną. Można określić, czy określona wartość daty i godziny może podlegać modyfikacji, przekazując ją do TimeZoneInfo.IsInvalidTime metody, jak pokazano w przykładzie.

  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