C# Reference ยท Date, Time and Globalization
The TimeZoneInfo class
Reference for System.TimeZoneInfo in C#: find time zones by id, convert instants and clock times, check daylight saving, create custom zones and avoid ambiguous times.
TimeZoneInfo describes a time zone: its base offset from UTC and the rules for daylight saving time. It is the class that knows that Berlin is UTC+1 in January and UTC+2 in July. DateTimeOffset only records one offset; TimeZoneInfo knows how offsets change.
Zones come from the operating system's database. On Linux and macOS they use IANA ids such as Europe/Berlin or America/New_York; on Windows, the registry ids such as W. Europe Standard Time (modern .NET accepts both on both systems when ICU data is available). A zone that is missing on the machine throws TimeZoneNotFoundException, so production code should handle that.
var utc = TimeZoneInfo.Utc; var local = TimeZoneInfo.Local;
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.
Syntax
public sealed class TimeZoneInfo : IEquatable<TimeZoneInfo>
| Member | Description |
|---|---|
Utc, Local |
Static zones for UTC and the machine's local zone. |
FindSystemTimeZoneById(string id) |
Looks up a zone; throws TimeZoneNotFoundException. |
TryFindSystemTimeZoneById(string, out TimeZoneInfo?) |
Same without an exception (.NET 8+). |
GetSystemTimeZones() |
All zones the system knows. |
ConvertTime(DateTime, TimeZoneInfo), ConvertTime(DateTimeOffset, TimeZoneInfo), ConvertTime(DateTime, source, destination) |
Convert a time to another zone. |
ConvertTimeToUtc(DateTime[, TimeZoneInfo]), ConvertTimeFromUtc(DateTime, TimeZoneInfo) |
UTC conversions. |
GetUtcOffset(DateTime), GetUtcOffset(DateTimeOffset), BaseUtcOffset |
The offset at a time, or the standard-time offset. |
IsDaylightSavingTime, IsAmbiguousTime, IsInvalidTime, SupportsDaylightSavingTime |
Daylight saving queries. |
CreateCustomTimeZone(id, baseUtcOffset, displayName, standardDisplayName) |
Fixed-offset zone defined in code. |
Id, DisplayName, StandardName, DaylightName |
Descriptive properties (display names depend on culture data). |
Errors: TimeZoneNotFoundException for unknown ids; InvalidTimeZoneException for corrupt data; ArgumentException for an invalid conversion, such as a DateTime whose Kind is Utc converted from a non-UTC source zone, or a time that does not exist in the source zone.
Usage notes
- Store UTC, convert at the edges. Keep instants as UTC (
DateTimeof kindUtcorDateTimeOffset), and convert to the user's zone only for display or when interpreting input. - Zone ids differ between systems. IANA ids work on Linux and macOS, Windows ids on Windows; recent .NET versions convert between the two when ICU is available, but that does not hold in every environment (this sandbox uses invariant globalization). Verify on your target machine and keep ids in configuration.
- Invalid and ambiguous local times. When clocks spring forward, a range of local times does not exist (
IsInvalidTime); when they fall back, a range happens twice (IsAmbiguousTime). Converting a wall-clock time from such a range needs care;GetAmbiguousTimeOffsetslists the possible offsets. - Adding days is not adding 24 hours. Across a daylight saving change a calendar day can be 23 or 25 hours long. Convert to the zone, add days to the wall-clock value, then convert back to UTC.
- Zone rules change. Governments change daylight saving rules. Keep the OS time zone data (or the
tzdatapackage in containers) up to date. - Containers. Slim Linux images often have no time zone database, so
FindSystemTimeZoneByIdcan fail for all ids exceptUTC. Localis the server's zone, not the user's. Web code should never use it for user-facing times.DateTimeKindis checked.ConvertTime(dateTime, destination)uses theKindto pick the source zone; forUnspecifiedit assumesLocal. Pass the source zone explicitly to avoid surprises.