github/awesome-copilot / skills/dotnet-timezone
dotnet-timezone
Unverified.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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.8 KB |
| references/code-patterns.md | markdown | 4.5 KB |
| references/timezone-index.md | markdown | 4.3 KB |
references/code-patterns.md
View on GitHub# .NET Timezone Code Patterns
## Pattern 1: Basic TimeZoneInfo
Use this only when the application is Windows-only and Windows timezone IDs are acceptable.
```csharp
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.
```xml
<PackageReference Include="TimeZoneConverter" Version="6.*" />
```
```csharp
using TimeZoneConverter;
TimeZoneInfo tz = TZConvert.GetTimeZoneInfo("Asia/Colombo");
DateTime converted = TimeZoneInfo.ConvertTimeFromUtc(DateTime.UtcNow, tz);
```
This also accepts Windows IDs:
```csharp
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.
```xml
<PackageReference Include="NodaTime" Version="3.*" />
```
```csharp
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.
```csharp
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.
```csharp
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.
```csharp
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:
```csharp
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.
```csharp
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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |