Skip to content
This repository has been archived by the owner on Nov 3, 2018. It is now read-only.

About DateTimeOffset

mj1856 edited this page Jan 26, 2013 · 2 revisions

Every date in the Temporal Versioning bundle is a DateTimeOffset. This ensures that you are tracking instantaneous time, not calendar time. This is an important concern, as it prevents you from having issues such as times in different time zones, and daylight savings time changes.

It doesn't matter what offset you provide, as things will be converted to UTC where needed. But you should be aware of a few important quirks:

  • You can pass a DateTime in to any DateTimeOffset field. There is a one-way, implicit conversion. But be aware of the .Kind property of your DateTime values.
  • If you pass a DateTime with Local or Unspecified kind, the time zone of the computer where the code is running will be used and the DateTime value can change! Local comes from DateTime.Now() while Unspecified comes from new DateTime() or DateTime.Parse() when you don't explicitly set the kind parameter.
  • Utc kinds are safer. These come from methods such as DateTime.UtcNow().
  • It is much easier just to pass a DateTimeOffset instance. They are unambiguous.
  • Be aware that two DateTimeOffset values are equal if their UTC converted times are equal. For example, 2012-01-01T00:00:00+00:00 and 2012-01-01T02:00:00+02:00 refer to the same instantaneous moment, and are therefore equivalent. You can use an offset that is contextually relevant for your own purposes without regard to conversion. If you have no context, or just don't care, then use UTC.
  • RavenDB stores all DateTime and DateTimeOffset value in ISO8601 format. This is available in .Net via the round trip string formatter, .ToString("o").
  • A DateTimeOffset in a Raven document or metadata will maintain its offset, but when used in an index map, it will be converted to a UTC DateTime. This is important and desired behavior such that sorting and filtering is alwways done over instantaneous time.

For a deeper understanding of DateTimeOffset, see this post on StackOverflow that I wrote.