Little Wonders C # /. NET - Structure DateTimeOffset

Consider some parts of the .Net Framework that look trivial, but are capable of making your code easier to write and maintain.


Writing on .NET (and if you do not do it, then you should not read this post) for certain, from time to time they use the DateTime structure for their needs. This structure is convenient for storing dates, times, or dates / times related to the local time zone (or to UTC).


However, there are times when you need to save time as an offset, rather than convert it to local time. And here comes a structure that first appeared in .NET 3.5 - DateTimeOffset.
')
Problem: DateTime parsing may lead to local time conversion

Imagine that you are using a file, a web service, etc. Some third-party company whose servers are in a different time zone. Moreover, they have several fields in the returned data, which should contain dates, but actually contain serialized instances of the DateTime structure, the time in which is set at midnight. For example, they give the patient's date of birth in this form:

2012-03-01 00: 00: 00-05: 00

Such a record suggests that the person was born on March 1, 2012 at an unspecified time (after all, most forms do not require you to fill in the time of your birth). But since the instance of the DateTime structure was serialized head-on, it contains the time set at midnight, according to its time zone.


So, knowing that this date is compatible with the Eastern Time Zone, and we are in the Central Time Zone, we parse it like this:

// // ..
var dateString = "2012-03-01 00:00:00-05:00";
// DateTime
var birthDay = DateTime.Parse(dateString);

Looks perfect, right? But here lies the problem. If we check the contents of the DateTime object on our local machine, where the Central time zone is set, we will see this:

2012-02-29 11:00:00 PM

What happened? (Or as one character said - Who did it?) Yes, the DateTime.Parse () method converted the date to a local time zone since the original date of birth was stored with the specified offset. You just had a service - converted the specified date and time to your local date and time. This is not so bad if it was not about the birthday, which since March 1 has moved to February 29.


Of course, we can call the third party and ask to stop including time on the date line or stop sending the offset along with time (in this case, it will no longer be converted to local time, but will be marked as DateTimeKind.Unspecified).


However, it happens that we are not able to change the situation in this way.


There are cases when you want to read the date and time with an offset, but not convert it to a local time zone. And this is where the DateTimeOffset comes in handy.

DateTimeOffset - stores DateTime and Offset

So what about DateTimeOffset? The structure is as simple as its name, DateTimeOffset is date + time + offset. That is why it represents a much more accurate point in time, because it includes information about the offset, which was set by the current date and time.


In truth, the functionality of DateTime and DateTimeOffset largely overlaps, and since Microsoft has a guide on choosing one or the other, I recommend that you familiarize yourself with it in MSDN. The article is called "Choosing Between DateTime, DateTimeOffset, and TimeZoneInfo."


In general, you can use DateTime if you are “attached” to one time zone or use only universal time in UTC format. But if you want to use dates and time from different time zones, and also want to save information about the offset without conversion to local time, then it is better to use DateTimeOffset.


There are many of the same properties in the DateTimeOffset structure as in the DateTime structure (Day, Month, Year, Hour, Minute, Second, etc.), therefore here I will not describe them. The main difference is in several new properties:

Datetime

Returns the DateTime without offset.

Localdatetime

Returns the converted DateTime, given the offset (i.e. in the local time zone).

Offset

Returns the offset from UTC.

Utcdatetime

Returns the DateTime as UTC time.


The DateTime property gives you a DateTime (not cast to the local time zone), and the Offset property has a TimeSpan format representing the offset from UTC time. There are also LocalDateTime and UtcDateTime properties that convert a given DateTimeOffset to a DateTime for a local time zone or UTC.


Also note that the Now and UtcNow properties of the DateTimeOffset structure do not return a DateTime type, but a DateTimeOffsets with a corresponding offset from UTC. Of course, like DateTime, DateTimeOffset has methods that operate on a date / time, returning a DateTimeOffset type instead of a DateTime.


So how can all this help us in the above example? Now we know that the third party sends us the date and time of its time zone, which does not need to be converted to local date / time. Therefore, you can use DateTimeOffset.Parse () (or TryParse ()) and select only the date:

// // ..
var dateString = "2012-03-01 00:00:00-05:00";
// / ( /)
var dtOffset = DateTimeOffset.Parse(dateString);
// DateTime
// Date
//
var theDay = dtOffset.Date;

Thus, you can easily parse dates without having to track the “midnight shift” or use it where you need to have date, time and offset without converting to local time.

Results

Although the DateTime structure is quite powerful in terms of parsing, manipulating and comparing dates / times, it can deliver quite a few unpleasant minutes in working with dates in the format of different time zones. In this case, DateTimeOffset behaves much more flexible because it uses the offset from UTC.


Free translation (c) VF Chuzha aka hDrummer, the original is here .