Dotnet Timezone

.NET Timezone

Resolve timezone questions for .NET and C# code with production-safe guidance and copy-paste-ready snippets.

Start With The Right Path

Identify the request type first:

• Address or location lookup
• Timezone ID lookup
• UTC/local conversion
• Cross-platform timezone compatibility
• Scheduling or DST handling
• API or persistence design

If the library is unclear, default to TimeZoneConverter for cross-platform work. If the scenario involves recurring schedules or strict DST rules, prefer NodaTime.

Resolve Addresses And Locations

If the user provides an address, city, region, country, or document containing place names:

1. Extract each location from the input. 2. Read references/timezone-index.md for common Windows and IANA mappings. 3. If the exact location is not listed, infer the correct IANA zone from geography, then map it to the Windows ID. 4. Return both IDs and a ready-to-use C# example.

For each resolved location, provide:

Location: <resolved place>
Windows ID: <windows id>
IANA ID: <iana id>
UTC offset: <standard offset and DST offset when relevant>
DST: <yes/no>

Then include a cross-platform snippet like:

using TimeZoneConverter;

TimeZoneInfo tz = TZConvert.GetTimeZoneInfo("Asia/Colombo");
DateTime local = TimeZoneInfo.ConvertTimeFromUtc(DateTime.UtcNow, tz);

If multiple locations are present, include one block per location and then a combined multi-timezone snippet.

If a location is ambiguous, list the possible timezone matches and ask the user to choose the correct one.

Look Up Timezone IDs

Use references/timezone-index.md for Windows to IANA mappings.

Always provide both formats:

• Windows ID for TimeZoneInfo.FindSystemTimeZoneById() on Windows
• IANA ID for Linux, containers, NodaTime, and TimeZoneConverter

Generate Code

Use references/code-patterns.md and pick the smallest pattern that fits:

• Pattern 1: TimeZoneInfo for Windows-only code
• Pattern 2: TimeZoneConverter for cross-platform conversion
• Pattern 3: NodaTime for strict timezone arithmetic and DST-sensitive scheduling
• Pattern 4: DateTimeOffset for APIs and data transfer
• Pattern 5: ASP.NET Core persistence and presentation
• Pattern 6: recurring jobs and schedulers
• Pattern 7: ambiguous and invalid DST timestamps

Always include package guidance when recommending third-party libraries.

Warn About Common Pitfalls

Mention the relevant warning when applicable:

• TimeZoneInfo.FindSystemTimeZoneById() is platform-specific for timezone IDs.
• Avoid storing DateTime.Now in databases; store UTC instead.
• Treat DateTimeKind.Unspecified as a bug risk unless it is deliberate input.
• DST transitions can skip or repeat local times.
• Azure Windows and Azure Linux environments may expect different timezone ID formats.

Response Shape

For address and location requests:

1. Return the resolved timezone block for each location. 2. State the recommended implementation in one sentence. 3. Include a copy-paste-ready C# snippet.

For code and architecture requests:

1. State the recommended approach in one sentence. 2. Provide the timezone IDs if relevant. 3. Include the minimal working code snippet. 4. Mention the package requirement if needed. 5. Add one pitfall warning if it matters.

Keep responses concise and code-first.

References

• references/timezone-index.md: common Windows and IANA timezone mappings
• references/code-patterns.md: ready-to-use .NET timezone patterns

.NET Timezone Code Patterns

Pattern 1: Basic TimeZoneInfo

Use this only when the application is Windows-only and Windows timezone IDs are acceptable.

DateTime utcNow = DateTime.UtcNow;
TimeZoneInfo sriLankaTz = TimeZoneInfo.FindSystemTimeZoneById("Sri Lanka Standard Time");
DateTime localTime = TimeZoneInfo.ConvertTimeFromUtc(utcNow, sriLankaTz);

DateTime backToUtc = TimeZoneInfo.ConvertTimeToUtc(localTime, sriLankaTz);

TimeZoneInfo tokyoTz = TimeZoneInfo.FindSystemTimeZoneById("Tokyo Standard Time");
DateTime tokyoTime = TimeZoneInfo.ConvertTime(localTime, sriLankaTz, tokyoTz);

Use TimeZoneConverter or NodaTime instead for Linux, containers, or mixed environments.

Pattern 2: Cross-Platform With TimeZoneConverter

Recommended default for most .NET apps that run across Windows and Linux.

<PackageReference Include="TimeZoneConverter" Version="6.*" />

using TimeZoneConverter;

TimeZoneInfo tz = TZConvert.GetTimeZoneInfo("Asia/Colombo");
DateTime converted = TimeZoneInfo.ConvertTimeFromUtc(DateTime.UtcNow, tz);

This also accepts Windows IDs:

TimeZoneInfo tz = TZConvert.GetTimeZoneInfo("Sri Lanka Standard Time");

Pattern 3: NodaTime

Use this for strict timezone arithmetic, recurring schedules, or DST edge cases where correctness matters more than minimal dependencies.

<PackageReference Include="NodaTime" Version="3.*" />

using NodaTime;

DateTimeZone colomboZone = DateTimeZoneProviders.Tzdb["Asia/Colombo"];
Instant now = SystemClock.Instance.GetCurrentInstant();
ZonedDateTime colomboTime = now.InZone(colomboZone);

DateTimeZone tokyoZone = DateTimeZoneProviders.Tzdb["Asia/Tokyo"];
ZonedDateTime tokyoTime = colomboTime.WithZone(tokyoZone);

LocalDateTime localDt = new LocalDateTime(2024, 6, 15, 14, 30, 0);
ZonedDateTime zoned = colomboZone.AtStrictly(localDt);
Instant utcInstant = zoned.ToInstant();

Pattern 4: DateTimeOffset For APIs

Prefer DateTimeOffset for values crossing service or process boundaries.

using TimeZoneConverter;

DateTimeOffset utcNow = DateTimeOffset.UtcNow;
TimeZoneInfo tz = TZConvert.GetTimeZoneInfo("Asia/Colombo");
DateTimeOffset colomboTime = TimeZoneInfo.ConvertTime(utcNow, tz);

Pattern 5: ASP.NET Core Persistence And Presentation

Store UTC, convert at the edges.

using TimeZoneConverter;

entity.CreatedAtUtc = DateTime.UtcNow;

public DateTimeOffset ToUserTime(DateTime utc, string userIanaTimezone)
{
    var tz = TZConvert.GetTimeZoneInfo(userIanaTimezone);
    return TimeZoneInfo.ConvertTimeFromUtc(utc, tz);
}

Pattern 6: Scheduling And Recurring Jobs

Translate a user-facing local time to UTC before scheduling.

using TimeZoneConverter;

TimeZoneInfo tz = TZConvert.GetTimeZoneInfo("Asia/Colombo");
DateTime scheduledLocal = new DateTime(2024, 12, 1, 9, 0, 0, DateTimeKind.Unspecified);
DateTime scheduledUtc = TimeZoneInfo.ConvertTimeToUtc(scheduledLocal, tz);

With Hangfire:

RecurringJob.AddOrUpdate(
    "morning-job",
    () => DoWork(),
    "0 9 * * *",
    new RecurringJobOptions { TimeZone = tz });

Pattern 7: Ambiguous And Invalid DST Times

Check for repeated or skipped local timestamps when the timezone observes daylight saving time.

using TimeZoneConverter;

TimeZoneInfo tz = TZConvert.GetTimeZoneInfo("America/New_York");
DateTime localTime = new DateTime(2024, 11, 3, 1, 30, 0);

if (tz.IsAmbiguousTime(localTime))
{
    var offsets = tz.GetAmbiguousTimeOffsets(localTime);
    var standardOffset = offsets.Min();
    var dto = new DateTimeOffset(localTime, standardOffset);
}

if (tz.IsInvalidTime(localTime))
{
    localTime = localTime.AddHours(1);
}

Common Mistakes

Decision Guide

• Use TimeZoneInfo only for Windows-only code with Windows IDs.
• Use TimeZoneConverter for most cross-platform applications.
• Use NodaTime when DST arithmetic or calendaring accuracy is central.
• Use DateTimeOffset for APIs and serialized timestamps.

.NET Timezone Reference Index

Windows To IANA Mapping

Use this file for common mappings between Windows timezone IDs and IANA timezone IDs.

Asia And Pacific

Europe

Americas

Africa

NodaTime Providers

DateTimeZoneProviders.Tzdb["Asia/Colombo"]
DateTimeZoneProviders.Bcl["Sri Lanka Standard Time"]

TimeZoneConverter Examples

string ianaId = TZConvert.WindowsToIana("Sri Lanka Standard Time");
string windowsId = TZConvert.IanaToWindows("Asia/Colombo");
TimeZoneInfo tz = TZConvert.GetTimeZoneInfo("Asia/Colombo");

Programmatic Discovery

foreach (var tz in TimeZoneInfo.GetSystemTimeZones())
{
    Console.WriteLine($"ID: {tz.Id} | Display: {tz.DisplayName}");
}