TimeZoneConverter

Supported Frameworks

• .NET 6, .NET 8, .NET 9
• .NET Core 2.0 or greater
• .NET Framework 4.6.2 and greater

OS Dependencies

While the library has no external data dependencies at runtime (data is embedded), certain methods like TZConvert.GetTimeZoneInfo rely on the underlying operating system's time zone data:

• Windows: Data is retrieved from the registry via Windows Updates.
• OSX/Linux: Data is retrieved from the IANA time zone database (usually the tzdata package).

Note for Docker users: Alpine Linux Docker images for .NET Core do not include tzdata by default; you must install it for TZConvert.GetTimeZoneInfo to function correctly.

A zone is considered 'unmappable' if there is no logical equivalent between types.

• IANA to Windows: Currently, Antarctica/Troll is unmappable to Windows and will throw a TimeZoneNotFoundException.
• To Rails: Many zones are unmappable to Rails.

Additionally, if you convert a zone to a Windows ID that the local OS does not yet recognize (e.g., due to missing Windows Updates), TimeZoneInfo operations may throw a TimeZoneNotFoundException.

To use TimeZoneConverter in your project, add the TimeZoneConverter NuGet package and import the TimeZoneConverter namespace.

dotnet add package TimeZoneConverter

Use the PosixTimeZone class to convert standard time zone identifiers into POSIX time zone strings. This is useful for environments like IoT devices that lack full time zone data.

Note that TimeZoneConverter.Posix requires both TimeZoneConverter and Noda Time as runtime dependencies.

// From a Windows time zone ID
string posix = PosixTimeZone.FromWindowsTimeZoneId("Eastern Standard Time");
// Result: "EST5EDT,M3.2.0,M11.1.0"

// From an IANA time zone name
string posix = PosixTimeZone.FromIanaTimeZoneName("Australia/Sydney");
// Result: "AEST-10AEDT,M10.1.0,M4.1.0/3"

// From a TimeZoneInfo object
string posix = PosixTimeZone.FromTimeZoneInfo(TimeZoneInfo.Local);

The library supports mapping Rails ActiveSupport::TimeZone names to both IANA and Windows identifiers. Note that some Rails zones may map to multiple IANA zones.

// Rails to IANA
string tz = TZConvert.RailsToIana("Mexico City");
// Result: "America/Mexico_City"

// Rails to Windows
string tz = TZConvert.RailsToWindows("Mexico City");
// Result: "Central Standard Time (Mexico)"

// IANA to Rails (returns a list as one IANA zone can map to multiple Rails names)
IList<string> tz = TZConvert.IanaToRails("America/Mexico_City");
// Result: { "Guadalajara", "Mexico City" }

// Windows to Rails (returns a list)
IList<string> tz = TZConvert.WindowsToRails("Central Standard Time (Mexico)");
// Result: { "Guadalajara", "Mexico City" }

Use TZConvert.GetTimeZoneInfo to retrieve a .NET TimeZoneInfo object using either an IANA or a Windows identifier, regardless of the operating system the code is running on.

// Works on any platform:
TimeZoneInfo tzi = TZConvert.GetTimeZoneInfo("Eastern Standard Time");
TimeZoneInfo tzi = TZConvert.GetTimeZoneInfo("America/New_York");

Use TZConvert to map between IANA (e.g., America/New_York) and Windows (e.g., Eastern Standard Time) time zone identifiers.

// IANA to Windows
string tz = TZConvert.IanaToWindows("America/New_York");
// Result: "Eastern Standard Time"

// Windows to IANA
string tz = TZConvert.WindowsToIana("Eastern Standard Time");
// Result: "America/New_York"

// Windows to IANA with country context (e.g., "CA" for Canada)
string tz = TZConvert.WindowsToIana("Eastern Standard Time", "CA");
// Result: "America/Toronto"

Access lists of supported time zone names or filter IANA names by territory using the following properties and methods:

• TZConvert.KnownIanaTimeZoneNames: List of known IANA names.
• TZConvert.KnownWindowsTimeZoneIds: List of known Windows IDs.
• TZConvert.KnownRailsTimeZoneNames: List of known Rails names.
• TZConvert.GetIanaTimeZoneNamesByTerritory(): Returns IANA time zones applicable to a specific region.

As of version 5.0.0, TimeZoneConverter.Posix is compatible with:

• .NET 6 or greater
• .NET Core 2.0 or greater
• .NET Framework 4.6.2 and greater

Note: .NET Framework versions earlier than 4.6.2 are not supported.