TimeZoneInfo cross-platform ID mapping for DateTimeOffset conversions

Recommended approach

Store canonical IANA time zone IDs, such as America/New_York, in application configuration. Resolve each ID to the current operating system's identifier at startup, cache the resulting TimeZoneInfo, and use that cached object for all DateTimeOffset conversions.

Likely explanation

The same region string is not valid everywhere. Windows registry IDs and IANA IDs are separate namespaces, so a configuration value that works on Windows fails on Linux or macOS before any conversion runs.

Confirmed facts

• TimeZoneInfo.FindSystemTimeZoneById reads the host OS time zone database. Windows expects IDs such as Eastern Standard Time; Linux and macOS expect IANA IDs such as America/New_York.
• .NET does not provide a built-in public API that automatically translates between Windows and IANA IDs. Passing an unsupported ID throws TimeZoneNotFoundException at resolution time.
• TimeZoneInfo.ConvertTime(DateTimeOffset, TimeZoneInfo) preserves the offset and avoids DateTime.Kind ambiguity.

Steps for this case

1. Add a library that knows both ID systems. Noda Time bundles its own time zone database and can produce BCL TimeZoneInfo objects; TimeZoneConverter is a lighter mapping alternative.
2. Configure regions using IANA IDs only:

{
  "RegionalTimeZones": {
    "NewYork": "America/New_York",
    "London": "Europe/London",
    "Tokyo": "Asia/Tokyo"
  }
}

1. Resolve and cache once at startup:

foreach (var region in config.RegionalTimeZones)
{
    var timeZone = ResolveTimeZone(region.Value);
    cache[region.Key] = timeZone;
}

1. Convert using the cached object:

var converted = TimeZoneInfo.ConvertTime(source, cache["NewYork"]);

If you cannot add a library

Maintain a minimal mapping table only for the regions your application supports. Do not enumerate every Windows/IANA pair; OS updates can add, remove, or change IDs.

Verification

• Call TimeZoneInfo.GetSystemTimeZones() on each target OS and confirm the resolved ID appears before deployment.
• Wrap FindSystemTimeZoneById in try/catch TimeZoneNotFoundException during startup validation.
• Convert a fixed DateTimeOffset across a DST transition on Windows, Linux, and macOS, then compare the resulting offset against the expected IANA offset.

Assumption: the host can read the operating system time zone database or ICU data. Uncertainty: exact ID strings can change with OS updates, so validation must run on each target OS rather than being assumed portable.

One missing diagnostic detail can change this recommendation: are you targeting .NET Framework or .NET Core / .NET 5 and later? .NET Framework depends on the Windows registry, while later .NET versions rely on ICU on Linux and macOS. If you are on .NET Framework and cannot add a library, a manual mapping table is effectively required.