TimeZoneInfo ID Mapping: Adapting .NET 6 Applications for Cross‑Platform Compatibility

Direct Answers

1. Portable storage pattern: Persist time zones as IANA identifiers (e.g., America/New_York). They are the only canonical form that works identically on Windows and Linux.
2. Mapping strategy: Translate Windows IDs to IANA at startup using a maintained mapping table (CLDR windowsZones.xml or NodaTime's WindowsZones.MapTimeZoneId). Do not rely on automatic translation—TimeZoneInfo provides none. For new code, prefer NodaTime (DateTimeZoneProviders.Tzdb) which ships the IANA database and exposes the mapping.
3. DateTimeOffset serialization: DateTimeOffset round-trips correctly in both System.Text.Json and Newtonsoft.Json on all platforms because the offset is part of the value. The risk is DateTime with Kind=Unspecified—ensure all boundary DTOs use DateTimeOffset or DateTime with Kind=Utc.

Implementation Steps

1. Define a canonical IANA-only model

public record UserPreferences(string TimeZoneId); // always IANA, e.g. "America/New_York"

2. Startup mapping helper (BCL-only approach)

private static readonly Dictionary<string, string> WindowsToIana = new()
{
    ["Eastern Standard Time"] = "America/New_York",
    ["Pacific Standard Time"] = "America/Los_Angeles",
    // …add remaining mappings from CLDR windowsZones.xml
};

public static TimeZoneInfo ResolveTimeZone(string id)
{
    try { return TimeZoneInfo.FindSystemTimeZoneById(id); }
    catch (TimeZoneNotFoundException)
    {
        if (WindowsToIana.TryGetValue(id, out var iana))
            return TimeZoneInfo.FindSystemTimeZoneById(iana);
        throw;
    }
}

3. Preferred: NodaTime for all new work

// Program.cs
var tzdb = DateTimeZoneProviders.Tzdb;
var windowsMapping = BclDateTimeZone.ForSystemDefault(); // or WindowsZones.MapTimeZoneId

// Resolve any ID (Windows or IANA) to a NodaTime DateTimeZone
DateTimeZone GetZone(string id)
{
    if (tzdb.GetZoneOrNull(id) is { } zone) return zone;
    var iana = WindowsZones.MapTimeZoneId(id, "001"); // "001" = world
    return tzdb.GetZoneOrNull(iana) ?? throw new TimeZoneNotFoundException(id);
}

4. Serialization safety

• Use DateTimeOffset in DTOs—never DateTime with Kind=Unspecified.
• Configure JSON serializer to reject DateTime without kind:

  options.Converters.Add(new JsonStringEnumConverter());
  options.Converters.Add(new DateTimeOffsetConverter()); // custom if needed

5. Container verification

# Dockerfile (Linux)
RUN apt-get update && apt-get install -y tzdata
# Verify zone exists
RUN ls /usr/share/zoneinfo/America/New_York

One Diagnostic Detail Needed

What JSON serializer and settings are currently in use (System.Text.Json vs Newtonsoft, DateTimeZoneHandling, custom converters)? This determines whether DateTime values with Kind=Unspecified are already being misinterpreted as UTC.