Permalink
Fetching contributors…
Cannot retrieve contributors at this time
105 lines (68 sloc) 8.25 KB
title ms.custom ms.date ms.prod ms.reviewer ms.suite ms.technology ms.tgt_pltfrm ms.topic helpviewer_keywords ms.assetid caps.latest.revision author ms.author manager
How to: Round-trip Date and Time Values
03/30/2017
.net
dotnet-standard
article
round-trip date and time values
dates [.NET Framework], round-trip values
time zones [.NET Framework], round-trip date and time values
time [.NET Framework], round-trip values
formatting strings [.NET Framework], round-trip values
b609b277-edc6-4c74-b03e-ea73324ecbdb
12
rpetrusha
ronpet
wpickett

How to: Round-trip Date and Time Values

In many applications, a date and time value is intended to unambiguously identify a single point in time. This topic shows how to save and restore a xref:System.DateTime value, a xref:System.DateTimeOffset value, and a date and time value with time zone information so that the restored value identifies the same time as the saved value.

To round-trip a DateTime value

  1. Convert the xref:System.DateTime value to its string representation by calling the xref:System.DateTime.ToString%28System.String%29?displayProperty=nameWithType method with the "o" format specifier.

  2. Save the string representation of the xref:System.DateTime value to a file, or pass it across a process, application domain, or machine boundary.

  3. Retrieve the string that represents the xref:System.DateTime value.

  4. Call the xref:System.DateTime.Parse%28System.String%2CSystem.IFormatProvider%2CSystem.Globalization.DateTimeStyles%29?displayProperty=nameWithType method, and pass xref:System.Globalization.DateTimeStyles.RoundtripKind?displayProperty=nameWithType as the value of the styles parameter.

The following example illustrates how to round-trip a xref:System.DateTime value.

[!code-csharpFormatting.HowTo.RoundTrip#1] [!code-vbFormatting.HowTo.RoundTrip#1]

When round-tripping a xref:System.DateTime value, this technique successfully preserves the time for all local and universal times. For example, if a local xref:System.DateTime value is saved on a system in the U.S. Pacific Standard Time zone and is restored on a system in the U.S. Central Standard Time zone, the restored date and time will be two hours later than the original time, which reflects the time difference between the two time zones. However, this technique is not necessarily accurate for unspecified times. All xref:System.DateTime values whose xref:System.DateTime.Kind%2A property is xref:System.DateTimeKind.Unspecified are treated as if they are local times. If this is not the case, the xref:System.DateTime will not successfully identify the correct point in time. The workaround for this limitation is to tightly couple a date and time value with its time zone for the save and restore operation.

To round-trip a DateTimeOffset value

  1. Convert the xref:System.DateTimeOffset value to its string representation by calling the xref:System.DateTimeOffset.ToString%28System.String%29?displayProperty=nameWithType method with the "o" format specifier.

  2. Save the string representation of the xref:System.DateTimeOffset value to a file, or pass it across a process, application domain, or machine boundary.

  3. Retrieve the string that represents the xref:System.DateTimeOffset value.

  4. Call the xref:System.DateTimeOffset.Parse%28System.String%2CSystem.IFormatProvider%2CSystem.Globalization.DateTimeStyles%29?displayProperty=nameWithType method, and pass xref:System.Globalization.DateTimeStyles.RoundtripKind?displayProperty=nameWithType as the value of the styles parameter.

The following example illustrates how to round-trip a xref:System.DateTimeOffset value.

[!code-csharpFormatting.HowTo.RoundTrip#2] [!code-vbFormatting.HowTo.RoundTrip#2]

This technique always unambiguously identifies a xref:System.DateTimeOffset value as a single point in time. The value can then be converted to Coordinated Universal Time (UTC) by calling the xref:System.DateTimeOffset.ToUniversalTime%2A?displayProperty=nameWithType method, or it can be converted to the time in a particular time zone by calling the xref:System.DateTimeOffset.ToOffset%2A?displayProperty=nameWithType or xref:System.TimeZoneInfo.ConvertTime%28System.DateTimeOffset%2CSystem.TimeZoneInfo%29?displayProperty=nameWithType method. The major limitation of this technique is that date and time arithmetic, when performed on a xref:System.DateTimeOffset value that represents the time in a particular time zone, may not produce accurate results for that time zone. This is because when a xref:System.DateTimeOffset value is instantiated, it is disassociated from its time zone. Therefore, that time zone's adjustment rules can no longer be applied when you perform date and time calculations. You can work around this problem by defining a custom type that includes both a date and time value and its accompanying time zone.

To round-trip a date and time value with its time zone

  1. Define a class or a structure with two fields. The first field is either a xref:System.DateTime or a xref:System.DateTimeOffset object, and the second is a xref:System.TimeZoneInfo object. The following example is a simple version of such a type.

    [!code-csharpFormatting.HowTo.RoundTrip#3] [!code-vbFormatting.HowTo.RoundTrip#3]

  2. Mark the class with the xref:System.SerializableAttribute attribute.

  3. Serialize the object using the xref:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter.Serialize%2A?displayProperty=nameWithType method.

  4. Restore the object using the xref:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter.Deserialize%2A method.

  5. Cast (in C#) or convert (in Visual Basic) the deserialized object to an object of the appropriate type.

The following example illustrates how to round-trip an object that stores both date and time and time zone information.

[!code-csharpFormatting.HowTo.RoundTrip#4] [!code-vbFormatting.HowTo.RoundTrip#4]

This technique should always unambiguously reflect the correct point of time both before and after it is saved and restored, provided that the implementation of the combined date and time and time zone object does not allow the date value to become out of sync with the time zone value.

Compiling the Code

These examples require:

  • That the following namespaces be imported with C# using statements or [!INCLUDEvbprvb] Imports statements:

    • xref:System (C# only).

    • xref:System.Globalization?displayProperty=nameWithType.

    • xref:System.IO?displayProperty=nameWithType.

    • xref:System.Runtime.Serialization?displayProperty=nameWithType.

    • xref:System.Runtime.Serialization.Formatters.Binary?displayProperty=nameWithType.

  • A reference to System.Core.dll.

  • Each code example, other than the DateInTimeZone class, should be included in a class or Visual Basic module, wrapped in methods, and called from the Main method.

See Also

Performing Formatting Operations
Choosing Between DateTime, DateTimeOffset, TimeSpan, and TimeZoneInfo
Standard Date and Time Format Strings