About DateTimeOffset
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 anyDateTimeOffset
field. There is a one-way, implicit conversion. But be aware of the.Kind
property of yourDateTime
values. - If you pass a
DateTime
withLocal
orUnspecified
kind, the time zone of the computer where the code is running will be used and theDateTime
value can change!Local
comes fromDateTime.Now()
whileUnspecified
comes fromnew DateTime()
orDateTime.Parse()
when you don't explicitly set thekind
parameter. -
Utc
kinds are safer. These come from methods such asDateTime.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
and2012-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
andDateTimeOffset
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 UTCDateTime
. 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.
Introduction
Home
About Temporal Versioning
About DateTimeOffset
Setup
Installation
Enabling The Bundle
Client Initialization
Configuration
Migration
Usage
Specifying Effective Dates
Basic CRUD Operations
Temporal Activation
Querying Temporal Data
Querying Dynamically
Querying a Static Index
Map/Reduce of Current Data
Advanced
Temporal Map/Reduce
Temporal Relationships
Guidance
Getting an Audit Trail
Practical Application Guidance
Reference
Misc