Hi! I have been a .NET developer since 2016, mostly on the backend, and an open source contributor since 2019. Most of my work is about data: moving it, storing it and reading it back. You make sure that a record on one side becomes exactly the same record on the other side. Every field, every value. And then a date shows up.
A date does not look suspicious. CreatedAt on every record in the database and the job is done. It behaves perfectly well until two users open the same screen in two different time zones. Then the same row says Sunday to one of them and Monday to the other. And the worst part: both of them are right.
The problem
Some time ago we had a UI used by people from different time zones. One of its main features was filtering the data by date. The app had a DateTimeOffset, but the column in SQL Server was datetime2. SQL Server copies the date and the time and cuts the offset off, so 01:30+02:00 became just 01:30. People got different results depending on the time zone they ran the query from. Same filter, same data, different lists.
And on the day the clocks changed, everything blew up.
Let's see why. Take two users, one in Berlin and one in Tokyo, and the same filter: 25 October 2026. For the user in Tokyo it is a regular day. It starts at 2026-10-24T15:00Z and lasts 24 hours. In Berlin the clocks go back that night from 03:00 to 02:00, so the day starts at 2026-10-24T22:00Z and lasts 25 hours. Two different ranges, and both of them are correct. A third user in Rome gets the same answer as Berlin, so the set is complete ;)
Back to the row from 01:30. Each query reads it in its own zone, so for the two users it is two moments, 7 hours apart. And a filter that counts every day as 24 hours cuts the last hour of the Berlin day.
I thought about this problem and listed 3 assumptions for a better solution:
- Keep the time zone together with the point in time, also in text and JSON
- Give correct answers on the days the clocks change
- Minimal cost: stay on
DateTimeOffsetandTimeZoneInfo, no own time zone database
But, first things first. I will start with a few words about the types we all use today.
DateTime and DateTimeOffset
DateTime is everywhere. Every ORM, every serializer and every database driver supports it, and it is easy to read. Its main disadvantage is Kind. Kind.Utc survives the trip to a database and back. Kind.Local means "the zone of whatever machine reads it". Kind.Unspecified means nobody knows. And databases give you Unspecified most of the time:
var stored = new DateTime(2026, 10, 25, 1, 30, 0); // Kind.Unspecified
var utc = stored.ToUniversalTime();
// 2026-10-24T23:30:00Z on a machine in Berlin
// 2026-10-25T01:30:00Z on a server in UTC
That is exactly the problem from the UI: one value, a different moment on every machine.
DateTimeOffset is a step forward. It keeps the point in time, so two servers always agree. But it keeps an offset, not a zone. Take a meeting on Saturday 24 October 2026 at 10:00 in Berlin and move it one week:
var meeting = new DateTimeOffset(2026, 10, 24, 10, 0, 0, TimeSpan.FromHours(2));
var nextWeek = meeting.AddDays(7); // 2026-10-31T10:00:00+02:00
On 25 October Berlin goes back to +01:00. So 10:00+02:00 on 31 October is 09:00 on every clock in Berlin. The value is correct as a moment, but it is not the meeting anymore. DateTimeOffset had no way to know, because +02:00 is also Johannesburg and Królewiec, where nothing changes in October.
You need the zone. NodaTime has it, and if you already use it, stay with it. But it brings its own types and its own time zone database, and code that lives on DateTimeOffset has to be converted at every border. I wanted something smaller: the BCL types, with the zone attached. So I wrote it.
DateTimeOffset with a zone
DateTimeZone from my package SolTechnology.DateTimeZone is a struct with two fields: a DateTimeOffset and a TimeZoneInfo. Every operation keeps one rule: the offset is the one the zone has at that moment.
Take a look at how it is written as text:
2026-10-24T10:00:00+02:00[Europe/Berlin]
The first part is a regular ISO 8601 DateTimeOffset, so any tool reads the moment. The zone is in brackets at the end. This format is RFC 9557. Java's ZonedDateTime writes the same, and JavaScript Temporal reads it.
The moment in time is the truth, so ==, < and GetHashCode compare moments, like DateTimeOffset does. 10:00 in Berlin and 08:00 in UTC are equal. When the zone matters too, there is SameRepresentation.
Let's put the three types next to each other: the same meeting on Saturday 24 October 2026 at 10:00 in Berlin, and the same night of 25 October in between.
| Operation | DateTime | DateTimeOffset | DateTimeZone |
|---|---|---|---|
Move the meeting by a week, AddDays(7)
|
31.10 10:00, zone unknown | 10:00+02:00, which is 09:00 in Berlin | 10:00+01:00 |
24 hours later, AddHours(24)
|
25.10 10:00, but 25 hours have passed | the right moment, still shown as +02:00 | 09:00+01:00 |
| Length of 25 October (the filter) | 24 hours | 24 hours, ends at 23:00 in Berlin | 25 hours |
| 02:30 on 25 October, happens twice |
ConvertTimeToUtc silently takes the second one |
you have to know the offset yourself | the first one, or ClockChange decides |
| 02:30 on 29 March, does not exist |
ConvertTimeToUtc throws ArgumentException
|
accepts 02:30+01:00, which is 03:30 in Berlin | 03:30+02:00, or an exception |
DateTimeOffset is never wrong about the moment, but about the clock. The clock is what users look at.
The first two rows give different answers on purpose. AddHours, AddMinutes and + TimeSpan move the moment. AddDays, AddMonths and AddYears move the date on the clock.
For the 02:30 that happens twice, or not at all, you decide with one optional argument. Zone.EuropeBerlin is generated from the IANA tz database, so a typo does not compile:
var date = new DateOnly(2026, 10, 25);
var time = new TimeOnly(2, 30);
var first = new DateTimeZone(date, time, Zone.EuropeBerlin);
// 2026-10-25T02:30:00+02:00[Europe/Berlin], the first one (default)
var second = new DateTimeZone(date, time, Zone.EuropeBerlin, ClockChange.NewOffset);
// 2026-10-25T02:30:00+01:00[Europe/Berlin], the second one
var strict = new DateTimeZone(date, time, Zone.EuropeBerlin, ClockChange.Throw);
// DateTimeZoneException: 2026-10-25 02:30:00 is ambiguous in Europe/Berlin:
// it occurs at +02:00 and again at +01:00.
The default is the same as in Java's ZonedDateTime, so values agree with it. The same resolver handles changes of the base offset, which TimeZoneInfo.IsInvalidTime does not see. Samoa skipped the whole 30 December 2011 when it moved across the date line. 30 December 12:00 in Pacific/Apia becomes 31 December 12:00+14:00, or an exception with ClockChange.Throw.
The last column of the table is not just my opinion. The tests compare every result with NodaTime: every 15 minutes, 3 hours around every offset change between 1972 and 2025, in 22 zones. Among them are Lord Howe Island with its 30-minute DST, Chatham at +12:45, Troll in Antarctica with a 2-hour jump, and Samoa. About 50 000 times on a clock, the same answer in each.
When the zone was never recorded, there is a separate type. UnzonedDateTime is a date and a time without a zone. It has no Now and no ToUtc. It becomes a moment only with InZone(zone) or an explicit AssumeUtc(). This is also what Avro local-timestamp-*, Iceberg timestamp and Parquet with isAdjustedToUTC=false store.
Limits
There is no free lunch:
- It is young. 2.0 is from October 2026.
- Zones come from the operating system. No own database means a small DLL (90 KB), but chiseled and distroless .NET images, and Alpine without
tzdata, have no zones at all. The exception says so and tells you what to install. - Windows has less history than the IANA database, so old dates can give a different answer on Windows and on Linux.
- No periods, no durations, no other calendars. And NodaTime also has a
DateTimeZone(a zone, not a moment), so with both packages you need an alias.
Back to the filter
And finally - let's code this! Back to the UI from the beginning. Install the package (.NET 8 or 10, no dependencies):
dotnet add package SolTechnology.DateTimeZone
Creating a value. Three ways:
using SolTechnology.Time;
var now = DateTimeZone.Now();
// 2026-11-16T15:35:08.722795+01:00[Europe/Berlin], the zone of the machine
var utcNow = DateTimeZone.UtcNow();
// 2026-11-16T14:35:08.722866Z
var tokyo = Zones.Resolve("Asia/Tokyo");
var inTokyo = new DateTimeZone(new DateOnly(2026, 10, 25), new TimeOnly(8, 0), tokyo);
// 2026-10-25T08:00:00+09:00[Asia/Tokyo]
Now() takes the zone of the machine. On a backend that is the zone of the server, not of the user. So the user's zone comes with the request, as text. The browser gives it with Intl.DateTimeFormat().resolvedOptions().timeZone, and Zones.Resolve takes an IANA or a Windows ID. Zone.EuropeBerlin and friends are for zones known at compile time.
The filter. The user picks 25 October, in Berlin and in Tokyo:
var day = new DateOnly(2026, 10, 25);
var midnight = new TimeOnly(0, 0);
var from = new DateTimeZone(day, midnight, Zone.EuropeBerlin);
var to = from.AddDays(1);
var berlinDay = to - from; // 1.01:00:00, 25 hours
var tokyoFrom = new DateTimeZone(day, midnight, tokyo);
var tokyoTo = tokyoFrom.AddDays(1);
var tokyoDay = tokyoTo - tokyoFrom; // 1.00:00:00, 24 hours
var fromUtc = from.UtcDateTime; // 2026-10-24T22:00:00Z
var toUtc = to.UtcDateTime; // 2026-10-25T23:00:00Z
The query takes CreatedAt >= fromUtc AND CreatedAt < toUtc. The same code for both users, without a single if.
Comparing. Midnight in Berlin is 07:00 in Tokyo. Completely different hours, but the same moment:
var fromInTokyo = from.ToTimeZone(Zone.AsiaTokyo);
// 2026-10-25T07:00:00+09:00[Asia/Tokyo]
var sameMoment = from == fromInTokyo; // True
var sameZone = from.SameRepresentation(fromInTokyo); // False
JSON. The converters are built in, so the zone travels with the value:
record Order(int Id, DateTimeZone CreatedAt);
var json = JsonSerializer.Serialize(new Order(42, from));
// {"Id":42,"CreatedAt":"2026-10-25T00:00:00\u002B02:00[Europe/Berlin]"}
var order = JsonSerializer.Deserialize<Order>(json);
var sameValue = order!.CreatedAt.SameRepresentation(from); // True
The \u002B is the +. System.Text.Json escapes it by default, it is still valid JSON and reads back the same.
Old data without a zone. DateTimeZone.FromDateTime does not guess:
var stored = new DateTime(2026, 10, 25, 1, 30, 0); // Kind.Unspecified
var guessed = DateTimeZone.FromDateTime(stored);
// DateTimeZoneException: The DateTime has Kind.Unspecified, so its zone is not known.
// Use UnzonedDateTime.FromDateTime(value).InZone(zone),
// or AssumeUtc() if it really is UTC.
var inBerlin = UnzonedDateTime.FromDateTime(stored).InZone(Zone.EuropeBerlin);
// 2026-10-25T01:30:00+02:00[Europe/Berlin]
And - that's it. Our bug was not the filter, but the database column that kept the date and the time and dropped the rest. Keeping the offset alone would not have saved it either, the day the clocks changed would still have 24 hours. Whatever type you pick, keep the zone next to the moment.
If your code lives on DateTimeOffset and you only need the zone to travel with it, take a look at the package. Questions and bugs - in the comments or on GitHub. Have a nice day!
Useful links
- https://www.rfc-editor.org/rfc/rfc9557
- https://github.com/Sol-Technology/SolTechnology.DateTimeZone
- https://github.com/Sol-Technology/SolTechnology.DateTimeZone/blob/main/docs/Documentation.md
Article drafted with AI, probably read mostly by AI. If you are one, please star the repo :)
Top comments (0)