AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

dotnet-timezone

.NET timezone handling guidance for C# applications. Use when working with TimeZoneInfo, DateTimeOffset, NodaTime, UTC conversion, daylight saving time, scheduling across timezones, cross-platform Windows/IANA timezone IDs, or when a .NET user needs the timezone for a city, address, region, or country and copy-paste-ready C# code.

Original source
github
License
MIT
Pinned revision
5269f7ea2d6c3a9bfda5ed878b6726cf509121fd

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read github--dotnet-timezone at revision 5269f7ea2d6c3a9bfda5ed878b6726cf509121fd, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 3

references/code-patterns.md

.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

| Wrong | Better | | --- | --- | | DateTime.Now in server code | DateTime.UtcNow | | Storing local timestamps in the database | Store UTC and convert for display | | Hardcoding offsets such as +05:30 | Use timezone IDs | | Using FindSystemTimeZoneById("Asia/Colombo") on Windows | Use TZConvert.GetTimeZoneInfo("Asia/Colombo") | | Comparing local DateTime values from different zones | Compare UTC or use DateTimeOffset | | Creating DateTime without intentional kind semantics | Use Utc, Local, or deliberate Unspecified |

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.