skip to content

In .NET, why should an invoicing service record payment and due instants as DateTimeOffset rather than DateTime, and what does DateTime.Kind fail to capture?

level: juniorimportance: must knowfreq 62%

answer

  1. three-valued flag, no offset
  2. equality compares ticks only
  3. an instant plus its offset
  4. offset is not a time zone

basics

~20 s

A DateTime carries only a Kind flag (Utc, Local or Unspecified), and equality ignores it, so values from different zones mix silently. DateTimeOffset stores the UTC offset and compares by instant, though an offset is not a time zone.

solid answer

~40 s

A `DateTime` is a tick count plus `Kind`: `Utc`, `Local` (whatever zone the *server* runs in) or `Unspecified`. `DateTime.Parse("2026-11-30T17:00:00")` gives `Unspecified`, and `==` compares ticks only, so a UTC value and a local value with the same digits are "equal". `DateTimeOffset` keeps the offset next to the clock time, so 17:00 +01:00 and 16:00 +00:00 compare equal as the same instant (`EqualsExact` also compares the offset). That makes it the right type for payment timestamps and due instants sent to partners. It is still not a zone: it does not know when daylight saving time changes, so to show a customer's local date you convert with `TimeZoneInfo.ConvertTime`, and a pure calendar due date fits `DateOnly` (.NET 6).

code

csharp · 20 lines
csharp
using System.Globalization;
CultureInfo.CurrentCulture = CultureInfo.InvariantCulture;

var parsed = DateTime.Parse("2026-11-30T17:00:00");
Console.WriteLine(parsed.Kind);                         // Unspecified

var utc = new DateTime(2026, 11, 30, 17, 0, 0, DateTimeKind.Utc);
var local = new DateTime(2026, 11, 30, 17, 0, 0, DateTimeKind.Local);
Console.WriteLine(utc == local);                        // True: Kind is ignored

var berlin5pm = new DateTimeOffset(2026, 11, 30, 17, 0, 0, TimeSpan.FromHours(1));
var london4pm = new DateTimeOffset(2026, 11, 30, 16, 0, 0, TimeSpan.Zero);
Console.WriteLine(berlin5pm == london4pm);              // True: same instant
Console.WriteLine(berlin5pm.EqualsExact(london4pm));    // False: offsets differ

var paidAt = new DateTimeOffset(2026, 11, 30, 23, 30, 0, TimeSpan.Zero);
var berlin = TimeZoneInfo.FindSystemTimeZoneById("Europe/Berlin");
var seen = TimeZoneInfo.ConvertTime(paidAt, berlin);
Console.WriteLine(seen.ToString("yyyy-MM-dd HH:mm zzz")); // 2026-12-01 00:30 +01:00
Console.WriteLine(DateOnly.FromDateTime(seen.DateTime).ToString("yyyy-MM-dd")); // 2026-12-01

go deeper

for a junior

Know the three DateTimeKind values, that DateTime equality ignores Kind, and that DateTimeOffset adds the UTC offset so a value names one instant.

for a middle

Explain why an offset is not a zone, how TimeZoneInfo.ConvertTime produces a customer's local date, and when DateOnly or TimeOnly fit better than either full type.

for a senior

Show the production traps: Unspecified values shifted by ToUniversalTime on servers in different zones, JSON without an offset, invalid and ambiguous local times, and the IANA lookup failing in invariant globalization mode.

for a principal

Frame the team convention: instants stored as DateTimeOffset or UTC, a zone id kept beside anything shown locally, and TimeProvider injected wherever business rules read the clock.

## What a DateTime actually stores A **`DateTime`** is a count of 100-nanosecond ticks since 0001-01-01 plus a **`Kind`** property of type `DateTimeKind`: - **`DateTimeKind.Utc`**: the value is Coordinated Universal Time. - **`DateTimeKind.Local`**: the value is in the time zone of the machine running the code, which for a service is the server's zone, not the customer's. - **`DateTimeKind.Unspecified`**: nobody said. `DateTime.Parse` of an ISO string without an offset, `new DateTime(y, m, d)` and many database drivers produce this. `Kind` is not a zone and not an offset; it is a hint, and much of the API ignores it. The `==` operator and `Equals` compare ticks only, so `new DateTime(2026, 11, 30, 17, 0, 0, DateTimeKind.Utc) == new DateTime(2026, 11, 30, 17, 0, 0, DateTimeKind.Local)` is `true` even though the two moments differ by the server's offset. `ToUniversalTime()` treats an `Unspecified` value as local time and shifts it, so the same stored value converts differently on servers in different zones. System.Text.Json writes an `Unspecified` value with no suffix (`"2026-11-30T17:00:00"`) and a `Utc` one with `Z`, so a partner reading the first cannot tell which instant you meant. ## DateTimeOffset: an instant plus the offset it was seen at A **`DateTimeOffset`** stores the clock time and the **offset from UTC** together, for example 17:00 +01:00. Two consequences matter for an invoicing service: - It identifies one **unambiguous instant**. Comparison operators and `Equals` compare the UTC instant, so 17:00 +01:00 equals 16:00 +00:00. `EqualsExact` compares the offset as well and returns `false` for that pair. - It keeps the **local reading** too: an audit log can show that the customer paid at 17:00 their time without a second column. The .NET date and time guide suggests considering `DateTimeOffset` the default date and time type for application development, because recording "when did this happen" is far more common than working with abstract clock values. ## An offset is not a time zone An offset is a single number; a **time zone** is a set of rules that maps instants to offsets and changes them for daylight saving time. A `DateTimeOffset` does not know which zone produced it, so arithmetic keeps the old offset: adding 24 hours to 12:00 +01:00 on the Saturday before Europe's spring change gives 12:00 +01:00 on Sunday, which is a correct instant but not the Berlin wall-clock reading (13:00 +02:00). To get a customer's local date you need a **`TimeZoneInfo`**: 1. Store the instant (`DateTimeOffset`, or UTC) and the customer's zone id, for example `Europe/Berlin`. 2. Convert with `TimeZoneInfo.ConvertTime(instant, zone)` when you display or compute a local date. 3. Take `DateOnly.FromDateTime(local.DateTime)` when you need the calendar day. Since .NET 6, `TimeZoneInfo.FindSystemTimeZoneById` accepts IANA ids (`Europe/Berlin`) and Windows ids (`W. Europe Standard Time`) on any OS that has time zone data, converting between the two when the requested form is not found. The globalization docs note this cross-format lookup is unavailable in globalization-invariant mode and NLS mode. Local wall-clock times can also be **invalid** (skipped by a spring change) or **ambiguous** (repeated in autumn); `TimeZoneInfo.IsInvalidTime` and `IsAmbiguousTime` detect them, and `ConvertTimeToUtc` throws `ArgumentException` for an invalid one. ## Round-tripping through JSON and storage The type you pick also decides what leaves the process: - System.Text.Json writes a `DateTimeOffset` with its offset, for example `"2026-11-30T17:00:00-05:00"`, so a partner can recover the exact instant. - A `DateTime` with `Kind` `Utc` is written with a `Z` suffix, a `Local` one with the *server's* offset (`+04:00` on a machine in a UTC+4 zone), and an `Unspecified` one with no suffix at all, so the same code emits different contracts depending on where it runs and how the value was created. - A `DateOnly` is written as `"2026-11-30"`, with no time to be shifted by a reader in another zone. - When a database column has no offset, store UTC and convert at the edges; do not store server-local times, because a second region or a daylight saving change makes them ambiguous. A quick review heuristic: any `DateTime.Now` in service code, any `DateTime` property on a wire contract, and any comparison between values from different sources deserves a question about which reference frame it assumes. ## Choosing a type per invoice field | Field | Type | Why | |---|---|---| | Payment received, invoice issued | `DateTimeOffset` | A real instant; keeps the offset it was seen at | | Due date shown as a calendar day | `DateOnly` (.NET 6) plus the customer's zone id | No time part, no midnight-UTC day shift | | Daily cut-off such as 17:00 | `TimeOnly` (.NET 6) | A clock reading, not an instant | | Internal arithmetic and storage | `DateTimeOffset` or `DateTime` with `Kind` `Utc` | One reference frame for every server | ## Testable "now" Code that calls `DateTime.Now` or `DateTimeOffset.UtcNow` directly cannot be tested at a chosen moment. Since .NET 8 the base library has the abstract **`TimeProvider`** class: inject `TimeProvider.System` in production and call `GetUtcNow()`, which returns a `DateTimeOffset`; `LocalTimeZone` and `CreateTimer` route zones and timers through the same seam. A controllable fake lives in the Microsoft.Extensions.TimeProvider.Testing package, and older targets get the type from Microsoft.Bcl.TimeProvider.

  • How do you turn a stored payment instant into the calendar date a customer in New York sees?
    Look up the zone with `TimeZoneInfo.FindSystemTimeZoneById("America/New_York")`, convert with `TimeZoneInfo.ConvertTime(instant, zone)`, then take `DateOnly.FromDateTime(local.DateTime)`. An instant of 23:30 UTC on 30 November is 18:30 -05:00 the same day in New York but 00:30 on 1 December in Berlin, so the calendar day depends on the zone, not on the offset you stored.
  • Why does adding 24 hours to a DateTimeOffset across a daylight saving change give a surprising local time?
    `DateTimeOffset` arithmetic keeps the original offset because the type has no zone rules. The resulting instant is correct, but its clock reading uses the old offset. Re-project the result with `TimeZoneInfo.ConvertTime` to get the wall-clock time the customer actually sees.
  • How do you make due-date logic testable without calling DateTime.Now?
    Inject `TimeProvider` (in the base library since .NET 8) and call `GetUtcNow()`. Production passes `TimeProvider.System`; tests pass a fake, such as `FakeTimeProvider` from Microsoft.Extensions.TimeProvider.Testing, set to the moment under test.

A DateTime with Kind is a parcel stamped "local time" without saying whose locality; a DateTimeOffset is stamped "17:00, one hour ahead of Greenwich", which pins the moment but still does not say which country's summer-time rules apply next week.

  • DateTimeOffset stores the customer's time zone, so daylight saving time is handled automatically.
  • Two DateTime values with different Kind values never compare equal.
  • DateTime.Parse of an ISO string without an offset returns a UTC value.
  • A calendar due date should be a DateTimeOffset at midnight UTC.
  • DateTime.Now is safe on servers because every server runs in UTC.