{"id":25,"date":"2012-04-06T17:37:00","date_gmt":"2012-04-06T17:37:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/davidrickard\/2012\/04\/06\/datetime-and-datetimeoffset-in-net-good-practices-and-common-pitfalls\/"},"modified":"2021-06-01T06:00:55","modified_gmt":"2021-06-01T06:00:55","slug":"datetime-and-datetimeoffset-in-net-good-practices-and-common-pitfalls","status":"publish","type":"post","link":"https:\/\/engy.us\/blog\/2012\/04\/06\/datetime-and-datetimeoffset-in-net-good-practices-and-common-pitfalls\/","title":{"rendered":"DateTime and DateTimeOffset in .NET: Good practices and common pitfalls"},"content":{"rendered":"

It becomes necessary to deal with dates and times in most .NET programs. A lot of programs use DateTime but that structure is frought with potential issues when you start serializing, parsing, comparing\u00a0and displaying dates from\u00a0different time zones and cultures. In this post I will go over these issues and\u00a0the APIs and practices you should use to avoid them.<\/p>\n

Background<\/strong><\/p>\n

The DateTime structure stores only two pieces of information: Ticks and Kind. 1 tick is 100 nanoseconds (10,000 ticks in a millisecond). The ticks counter represents how many 100ns ticks you are away from 1\/1\/0001 12:00 AM. It’s the part that determines that it’s April 6th, 2012, 3:32:07 PM.<\/p>\n

Another bit of data is the Kind: represented as a DateTimeKind enumeration. Utc, Local and Unspecified\u00a0are the possible values. Utc means that the ticks counter represents a Coordinated Universal Time<\/a> (that doesn’t change due to daylight savings\u00a0or time zones). Local means that it represents the local time of whatever time zone the computer is set to. This one is sensitive to daylight savings. Note that a timezone offset is not<\/em> built in to the DateTime structure. It can only get back to a real UTC time by checking the current time zone settings on the computer. ToUniversalTime() and ToLocalTime() will do these conversions. It will return a new DateTime value with the Ticks adjusted to get the correct year\/month\/day and with the requested type. Calling ToUniversalTime() on a UTC DateTime or ToLocalTime() on a Local DateTime has no effect. Remember that these functions are generating a new<\/em> DateTime value and not modifying the original.<\/p>\n

There’s also\u00a0a third type: Unspecified. This means we don’t know whether it’s local or UTC. All we know is the year, month, day, etc. When working with DateTime values, Unspecified is not very helpful since we don’t know what to do when we want to get a local or UTC time from it. If you call ToUniversalTime() on one of these, it assumes that the type must have been Local and converts based on that. If you call ToLocalTime() it assumes that the type must have been UTC and converts in that direction.<\/p>\n

DateTimeOffset is a newer structure. It is also based on ticks but instead of storing a Kind, it keeps track of the offset from UTC as a TimeSpan. A DateTimeOffset always knows what time zone it’s in. Calling ToUniversalTime() will always result in a TimeSpan.Zero offset, and ToLocalTime() will convert and result in an offset of the user’s current time zone.<\/p>\n

Use DateTimeOffset, not DateTime<\/strong><\/p>\n

DateTime has countless traps in it that are likely to give your code bugs:<\/p>\n