c# - DateTime vs DateTimeOffset -

currently have standard way of dealing .net datetimes in timezone aware way: whenever produce datetime in utc (e.g. using datetime.utcnow), , whenever display one, convert utc user's local time.

that works fine, i've been reading datetimeoffset , how captures local , utc time in object itself. question is, advantages of using datetimeoffset vs have been doing?

datetimeoffset representation of instantaneous time (also known absolute time). that, mean moment in time universal (not accounting leap seconds, or relativistic effects of time dilation). way represent instantaneous time datetime .kind datetimekind.utc.

this distinct calendar time (also known civil time), position on someone's calendar, , there many different calendars on globe. call these calendars time zones. calendar time represented datetime .kind datetimekind.unspecified, or datetimekind.local. , .local meaningful in scenarios have implied understanding of computer using result positioned. (for example, user's workstation)

so then, why datetimeoffset instead of utc datetime? it's perspective. let's use analogy - we'll pretend photographers.

imagine standing on calendar timeline, pointing camera @ person on instantaneous timeline laid out in front of you. line camera according rules of timezone - change periodically due daylight saving time, or due other changes legal definition of time zone. (you don't have steady hand, camera shaky.)

the person standing in photo see angle @ camera came from. if others taking pictures, different angles. offset part of datetimeoffset represents.

so if label camera "eastern time", pointing -5, , pointing -4. there cameras on world, labeled different things, , pointing @ same instantaneous timeline different angles. of them right next (or on top of) each other, knowing offset isn't enough determine timezone time related to.

and utc? well, it's 1 camera out there guaranteed have steady hand. it's on tripod, firmly anchored ground. it's not going anywhere. call angle of perspective 0 offset.

so - analogy tell us? provides intuitive guidelines.

• if representing time relative place in particular, represent in calendar time datetime. sure don't ever confuse 1 calendar another. unspecified should assumption. local useful coming datetime.now. example, might datetime.now , save in database - when retrieve it, have assume unspecified. can't rely local calendar same calendar taken from.

• if must of moment, make sure representing instantaneous time. use datetimeoffset enforce it, or use utc datetime convention.

• if need track moment of instantaneous time, want know "what time did user think on local calendar?" - must use datetimeoffset. important timekeeping systems, example - both technical , legal concerns.

• if ever need modify recorded datetimeoffset - don't have enough information in offset alone ensure new offset still relevant user. must also store timezone identifier (think - need name of camera can take new picture if position has changed).

  it should pointed out noda time has representation called zoneddatetime this, while .net base class library not have similar. need store both datetimeoffset , timezoneinfo.id value.

• occasionally, want represent calendar time local "whomever looking @ it". example, when defining today means. today midnight midnight, these represent near-infinite number of overlapping ranges on instantaneous timeline. (in practice have finite number of timezones, can express offsets down tick) in these situations, make sure understand how either limit "who's asking?" question down single time zone, or deal translating them instantaneous time appropriate.

here few other little bits datetimeoffset analogy, , tips keeping straight:

• if compare 2 datetimeoffset values, first normalized 0 offset before comparing. in other words, 2012-01-01t00:00:00+00:00 , 2012-01-01t02:00:00+02:00 refer same instantaneous moment, , therefore equivalent.

• if doing unit testing , need of offset, test both datetimeoffset value, , .offset property separately.

• there one-way implicit conversion built in .net framework lets pass datetime datetimeoffset parameter or variable. when doing so, the .kind matters. if pass utc kind, carry in 0 offset, if pass either .local or .unspecified, assume local. framework saying, "well, asked me convert calendar time instantaneous time, have no idea came from, i'm going use local calendar." huge gotcha if load unspecified datetime on computer different timezone. (imho - should throw exception - doesn't.)

shameless plug:

many people have shared me find analogy extremely valuable, included in pluralsight course, date , time fundamentals. you'll find step-by-step walkthrough of camera analogy in second module, "context matters", in clip titled "calendar time vs. instantaneous time".