Skip to content
Tutorials Center
My learning

Topics

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.

C#
var utc = TimeZoneInfo.Utc;
var local = TimeZoneInfo.Local;

Try it

C# Convert an instant with a custom zone

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.

C# Looking up system zones safely

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

C#
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 (DateTime of kind Utc or DateTimeOffset), 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; GetAmbiguousTimeOffsets lists 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 tzdata package in containers) up to date.
  • Containers. Slim Linux images often have no time zone database, so FindSystemTimeZoneById can fail for all ids except UTC.
  • Local is the server's zone, not the user's. Web code should never use it for user-facing times.
  • DateTimeKind is checked. ConvertTime(dateTime, destination) uses the Kind to pick the source zone; for Unspecified it assumes Local. Pass the source zone explicitly to avoid surprises.