DateTimeOffset Structure
Updated: January 2010
Represents a point in time, typically expressed as a date and time of day, relative to Coordinated Universal Time (UTC).
Assembly: mscorlib (in mscorlib.dll)
The DateTimeOffset structure includes a DateTime value, together with an Offset property that defines the difference between the current DateTimeOffset instance's date and time and Coordinated Universal Time (UTC). Because it exactly defines a date and time relative to UTC, the DateTimeOffset structure does not include a Kind member, as the DateTime structure does. It represents dates and times with values whose UTC ranges from 12:00:00 midnight, January 1, 0001 C.E., to 11:59:59 P.M., December 31, 9999 C.E.
The time component of a DateTimeOffset value is measured in 100-nanosecond units called ticks, and a particular date is the number of ticks since 12:00 midnight, January 1, 0001 A.D. (C.E.) in the GregorianCalendar calendar. A DateTimeOffset value is always expressed in the context of an explicit or default calendar. Ticks that are attributable to leap seconds are not included in the total number of ticks.
Note: |
|---|
If you are working with a ticks value that you want to convert to TimeSpan or some other time interval, such as minutes or seconds, you should use the TimeSpan.TicksPerDay, TimeSpan.TicksPerHour, TimeSpan.TicksPerMinute, TimeSpan.TicksPerSecond, or TimeSpan.TicksPerMillisecond constant to perform the conversion. For example, to add the number of seconds represented by a specified number of ticks to the Second component of a DateTimeOffset value, you can use the expression dateValue.Second + nTicks/Timespan.TicksPerSecond. |
Although a DateTimeOffset value includes an offset, it is not a fully time zone-aware data structure. While an offset from UTC is one characteristic of a time zone, it does not unambiguously identify a time zone. Not only do multiple time zones share the same offset from UTC, but the offset of a single time zone changes if it observes daylight saving time. This means that, as soon as a DateTimeOffset value is disassociated from its time zone, it can no longer be unambiguously linked back to its original time zone.
Because DateTimeOffset is a structure, a DateTimeOffset object that has been declared but not otherwise initialized contains the default values for each of its member fields. This means that its DateTime property is set to DateTimeOffset.MinValue and its Offset property is set to TimeSpan.Zero.
You can create a new DateTimeOffset value by calling any of the overloads of its constructor, which are similar to the overloaded constructors for the DateTime structure. You can also create a new DateTimeOffset value by assigning it a DateTime value. This is an implicit conversion; it does not require a casting operator (in C#) or call to a conversion method (in Visual Basic). You can also initialize a DateTimeOffset value from the string representation of a date and time by calling a number of static string parsing methods, which include Parse, ParseExact, TryParse, and TryParseExact.
The members of the DateTimeOffset structure provide functionality in the following areas:
Date and time arithmetic.
You can add or subtract either dates or time intervals from a particular DateTimeOffset value. Arithmetic operations with DateTimeOffset values, unlike those with DateTime values, adjust for differences in time offsets when returning a result. For example, the following code uses DateTime variables to subtract the current local time from the current UTC time. The code then uses DateTimeOffset variables to perform the same operation. The subtraction with DateTime values returns the local time zone's difference from UTC, while the subtraction with DateTimeOffset values returns TimeSpan.Zero.
Module DateArithmetic Public Sub Main() Dim date1, date2 As Date Dim dateOffset1, dateOffset2 As DateTimeOffset Dim difference As TimeSpan ' Find difference between Date.Now and Date.UtcNow date1 = Date.Now date2 = Date.UtcNow difference = date1 - date2 Console.WriteLine("{0} - {1} = {2}", date1, date2, difference) ' Find difference between Now and UtcNow using DateTimeOffset dateOffset1 = date.Now dateOffset2 = date.UtcNow difference = dateOffset1 - dateOffset2 Console.WriteLine("{0} - {1} = {2}", _ dateOffset1, dateOffset2, difference) ' If run in the Pacific Standard time zone on 4/2/2007, the example ' displays the following output to the console: ' 4/2/2007 7:23:57 PM - 4/3/2007 2:23:57 AM = -07:00:00 ' 4/2/2007 7:23:57 PM -07:00 - 4/3/2007 2:23:57 AM +00:00 = 00:00:00 End Sub End Module
Type conversion operations.
You can convert DateTimeOffset values to DateTime values and vice versa.
Time manipulation and extraction operations.
You can extract either the date or the time of a DateTimeOffset value. You can also retrieve the value of a particular DateTimeOffset component, such as its year or its month.
Date and time conversion.
You can convert any DateTimeOffset value to another DateTimeOffset value that represents the same point in time in another time zone. However, a time zone's adjustment rules are applied only in the case of the ToLocalTime method, which converts a DateTimeOffset value to the date and time in the local system zone.
Date and time comparison.
You can determine whether any particular DateTimeOffset value is earlier than, the same as, or later than another DateTimeOffset value. Before the comparison is performed, all values are converted to UTC.
Windows 7, Windows Vista, Windows XP SP2, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003
The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.
Date | History | Reason |
|---|---|---|
January 2010 | Added a note about using TimeSpan constants to convert ticks to and from other units of time. | Customer feedback. |
Note: