C# Reference ยท Date, Time and Globalization
UTC versus local time in C#
Concept page on UTC and local time in C#: DateTimeKind, ToUniversalTime, ToLocalTime, time zone conversion with TimeZoneInfo, and the rules for storing instants.
UTC (Coordinated Universal Time) is a single, global timeline with no daylight saving. Local time is UTC plus an offset that depends on a time zone and on the date, because the offset changes when daylight saving starts or ends. An instant, such as "when the order was placed", is one point on the UTC timeline, but it has a different wall-clock reading in each zone.
.NET models this in two ways. DateTime stores a clock reading plus a Kind label (Utc, Local or Unspecified). DateTimeOffset stores a clock reading plus the exact offset from UTC, so it always identifies one instant. The rule that avoids most date bugs is simple: store and compare instants in UTC, and convert to a time zone only when you display them.
DateTime nowUtc = DateTime.UtcNow; // Kind = Utc DateTimeOffset stamp = DateTimeOffset.UtcNow; // offset +00:00
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
How the pieces fit
| Type | What it stores | Identifies one instant? |
|---|---|---|
DateTime with Kind.Utc |
Clock reading in UTC | Yes |
DateTime with Kind.Local |
Clock reading in the machine's zone | Only if the machine zone and date are known |
DateTime with Kind.Unspecified |
Clock reading, no zone | No |
DateTimeOffset |
Clock reading and offset from UTC | Yes |
TimeZoneInfo |
Rules of a named zone (offsets, daylight saving) | Not a value; used to convert |
DateTime.Now is UtcNow converted with the machine's zone and labeled Local. DateTime.Today is today's date in that zone at midnight. ToUniversalTime() and ToLocalTime() look at Kind: a Local value is converted using the machine zone, a Utc value is returned as is by ToUniversalTime(), and an Unspecified value is assumed to be local by ToUniversalTime() and assumed to be UTC by ToLocalTime(). That asymmetry is why unlabeled values cause bugs.
Usage notes
- Store UTC, display local. Save
DateTime.UtcNoworDateTimeOffset.UtcNowin databases and logs; convert in the user interface, using the user's own zone and not the server's. - Prefer
DateTimeOffsetfor timestamps. It cannot be mislabeled. When you need the original zone (for a meeting in Berlin next year), store the zone id, such asEurope/Berlin, next to the UTC instant. TimeZoneInfo.Localis the machine zone. On a server it is usually UTC, so code that works there can break on a developer machine, and the other way round. The sandbox on this site runs in UTC and its globalization is invariant, but zone ids likeAmerica/New_Yorkdo exist (IANA ids on Linux; Windows ids such as "Eastern Standard Time" work on Windows, and recent .NET versions convert between both forms).- Daylight saving creates gaps and overlaps. A clock time in the spring gap is invalid and
ConvertTimeToUtcthrowsArgumentException; a clock time in the autumn overlap is ambiguous andConvertTimeToUtcpicks the standard-time interpretation. Check withIsInvalidTimeandIsAmbiguousTimewhen you accept user input. - Never add 24 hours to mean "tomorrow" in local time. Days can be 23 or 25 hours long. Add days to a local
DateTime(AddDays), or convert to UTC after you have chosen the local clock time. - Compare in one kind.
==and<compare ticks and ignoreKind, so convert both values to UTC first when they come from different sources. - Use
TimeProviderto inject "now" in tests rather than callingDateTime.UtcNowdirectly. - Fixed offsets are not zones.
TimeSpan.FromHours(-5)is a constant; it does not know about daylight saving.