Glossary / DateTime and DateTimeOffset
DateTime and DateTimeOffset
DateTime represents a date/time value with a Kind hint (Unspecified, Utc, or Local), while DateTimeOffset represents a clock time together with an explicit offset from UTC. Neither alone models every time-zone or calendar rule; choose based on whether the value is an instant, a local wall-clock appointment, or a date without time.
Instants and local time
DateTimeOffset is usually safer for representing an instant because it carries an offset and can be normalized to UTC. Offsets are not time zones: a zone such as Europe/Budapest has daylight-saving and historical rules that change offsets over time. Use TimeZoneInfo to convert instants and resolve local times. DateTimeKind.Unspecified is ambiguous unless the application defines its interpretation.
A local wall-clock time during daylight-saving transitions can be invalid (clock jumps forward) or ambiguous (clock repeats). Define policy for such input. Date-only values such as birthdays should use DateOnly; time-of-day values can use TimeOnly rather than inventing an arbitrary date.
Persistence and serialization
Store instants in UTC or as offset-aware values according to system contract; preserve original time-zone ID separately if future local display/recurrence matters. ISO 8601 round-trip formats are common. Avoid parsing/formatting with current culture for machine protocols. Database types and serializers may normalize or discard offset/zone information; verify behavior end to end.
Interview questions
- DateTimeOffset vs time zone? Offset is a fixed displacement at that instant; a time zone has historical/future rules.
- When use DateTimeKind.Unspecified? Only with a clear domain contract for local or floating wall time.
- What is DST ambiguity? A local clock time can map to zero or two instants at transition boundaries.
- What for birthdays? DateOnly, not a timestamp.
- How persist instants? Use UTC/offset-aware representation and preserve zone separately if recurrence/display needs it.