Subchapter 144.1
references/code-patterns.mdMarkdown4 KBView on GitHub
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.
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");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();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);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);
}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 });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);
}| 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 |
TimeZoneInfo only for Windows-only code with Windows IDs.TimeZoneConverter for most cross-platform applications.NodaTime when DST arithmetic or calendaring accuracy is central.DateTimeOffset for APIs and serialized timestamps.