.NET timezone
Resolve timezone IDs, conversions, scheduling, and persistence for .NET applications by selecting the right library, mapping Windows and IANA identifiers, and returning concise C# code that is safe across daylight saving time and platforms.
When to invoke
- "What timezone should I use for this city in .NET?"
- "Convert UTC to local time with TimeZoneInfo."
- "Make this timezone code work on Windows and Linux."
- "Handle daylight saving time in a C# scheduler."
- "Should I use DateTimeOffset or NodaTime?"
Prerequisites and context
- Read
references/timezone-index.md for common Windows and IANA mappings.
- Read
references/code-patterns.md for ready-to-use .NET timezone patterns.
- Default to
TimeZoneConverter for cross-platform Windows/IANA compatibility when the target runtime is unclear.
- Prefer
NodaTime for recurring schedules, strict timezone arithmetic, and DST-sensitive workflows.
Request routing
| Request type |
Recommended path |
| Address or location lookup |
Resolve geography to IANA zone, map to Windows ID, then return both IDs and offset/DST notes. |
| Timezone ID lookup |
Use references/timezone-index.md; always provide Windows and IANA formats. |
| UTC/local conversion |
Use TimeZoneInfo for platform-specific IDs or TimeZoneConverter for cross-platform IDs. |
| Cross-platform compatibility |
Use TZConvert.GetTimeZoneInfo(...) from TimeZoneConverter. |
| Scheduling or DST handling |
Use NodaTime and explicitly handle ambiguous and invalid local times. |
| API or persistence design |
Store instants in UTC and use DateTimeOffset for data transfer; persist a timezone ID when future local scheduling matters. |
Location resolution output
For every address, city, region, country, or place name, return this block and then a C# snippet.
Location: <resolved place>
Windows ID: <windows id>
IANA ID: <iana id>
UTC offset: <standard offset and DST offset when relevant>
DST: <yes/no>
If multiple locations are present, include one block per location and a combined multi-timezone snippet. If a location is ambiguous, list possible timezone matches and ask the user to choose.
Code patterns
| Pattern |
Use when |
Core API |
TimeZoneInfo |
Windows-only code or known platform-specific ID. |
TimeZoneInfo.FindSystemTimeZoneById(), TimeZoneInfo.ConvertTimeFromUtc(...). |
TimeZoneConverter |
Cross-platform conversion across Windows, Linux, containers, and Azure. |
TZConvert.GetTimeZoneInfo("Asia/Colombo"). |
NodaTime |
Recurring schedules, strict arithmetic, DST-sensitive jobs. |
DateTimeZone, Instant, ZonedDateTime, resolvers for skipped/repeated local times. |
DateTimeOffset |
APIs and data transfer where offset must travel with the value. |
DateTimeOffset and UTC normalization. |
| ASP.NET Core persistence/presentation |
Store UTC instants and display in user-selected zone. |
Database UTC column plus user timezone ID. |
| Recurring jobs and schedulers |
Future local time must stay local after DST changes. |
Store local schedule + zone ID, compute next occurrence with timezone rules. |
| Ambiguous and invalid DST timestamps |
Local time may repeat or not exist. |
Validate with TimeZoneInfo.IsAmbiguousTime() and TimeZoneInfo.IsInvalidTime() or NodaTime resolvers. |
using TimeZoneConverter;
TimeZoneInfo tz = TZConvert.GetTimeZoneInfo("Asia/Colombo");
DateTime local = TimeZoneInfo.ConvertTimeFromUtc(DateTime.UtcNow, tz);
Pitfall warnings
| Pitfall |
Corrective rule |
TimeZoneInfo.FindSystemTimeZoneById() is platform-specific |
Use Windows IDs on Windows, IANA IDs on Linux/containers, or TimeZoneConverter to bridge both. |
Storing DateTime.Now in databases |
Store UTC instants; convert only at boundaries and presentation. |
DateTimeKind.Unspecified leaks into conversions |
Treat it as a bug risk unless it deliberately represents user-entered local wall time. |
| DST transitions skip or repeat local times |
Validate invalid and ambiguous local timestamps before scheduling or converting. |
| Azure Windows and Azure Linux differ |
Use the ID format expected by the host OS or use TimeZoneConverter. |
Keep answers production-safe, code-first, and explicit about third-party package requirements.
Output template
## .NET timezone result
**Status:** resolved | ambiguous | blocked
**Recommended approach:** <TimeZoneInfo | TimeZoneConverter | NodaTime | DateTimeOffset>
| Location or scenario | Windows ID | IANA ID | Offset/DST | Notes |
| --- | --- | --- | --- | --- |
| `<place or code path>` | `<windows>` | `<iana>` | `<offsets>` | `<pitfall>` |
<copy-paste-ready C# snippet>
**Package requirement:** `<none | TimeZoneConverter | NodaTime>`
**Warning:** <relevant pitfall>
Quality gate
Progressive disclosure and bundled resources
references/timezone-index.md: common Windows and IANA timezone mappings.references/code-patterns.md: ready-to-use .NET timezone patterns.
1---2name: dotnet-timezone-23description: Resolve .NET and C# timezone questions with TimeZoneInfo, DateTimeOffset, TimeZoneConverter, NodaTime, UTC conversion, daylight saving time, scheduling, Windows and IANA timezone IDs, location lookup, and copy-paste-ready code. Use this skill when a .NET user needs the timezone for a city, address, region, or country, or asks about cross-platform timezone handling.4---56# .NET timezone78Resolve timezone IDs, conversions, scheduling, and persistence for .NET applications by selecting the right library, mapping Windows and IANA identifiers, and returning concise C# code that is safe across daylight saving time and platforms.910## When to invoke1112- "What timezone should I use for this city in .NET?"13- "Convert UTC to local time with TimeZoneInfo."14- "Make this timezone code work on Windows and Linux."15- "Handle daylight saving time in a C# scheduler."16- "Should I use DateTimeOffset or NodaTime?"1718## Prerequisites and context1920- Read `references/timezone-index.md` for common Windows and IANA mappings.21- Read `references/code-patterns.md` for ready-to-use .NET timezone patterns.22- Default to `TimeZoneConverter` for cross-platform Windows/IANA compatibility when the target runtime is unclear.23- Prefer `NodaTime` for recurring schedules, strict timezone arithmetic, and DST-sensitive workflows.2425## Request routing2627| Request type | Recommended path |28| --- | --- |29| Address or location lookup | Resolve geography to IANA zone, map to Windows ID, then return both IDs and offset/DST notes. |30| Timezone ID lookup | Use `references/timezone-index.md`; always provide Windows and IANA formats. |31| UTC/local conversion | Use `TimeZoneInfo` for platform-specific IDs or `TimeZoneConverter` for cross-platform IDs. |32| Cross-platform compatibility | Use `TZConvert.GetTimeZoneInfo(...)` from `TimeZoneConverter`. |33| Scheduling or DST handling | Use `NodaTime` and explicitly handle ambiguous and invalid local times. |34| API or persistence design | Store instants in UTC and use `DateTimeOffset` for data transfer; persist a timezone ID when future local scheduling matters. |3536## Location resolution output3738For every address, city, region, country, or place name, return this block and then a C# snippet.3940```text41Location: <resolved place>42Windows ID: <windows id>43IANA ID: <iana id>44UTC offset: <standard offset and DST offset when relevant>45DST: <yes/no>46```4748If multiple locations are present, include one block per location and a combined multi-timezone snippet. If a location is ambiguous, list possible timezone matches and ask the user to choose.4950## Code patterns5152| Pattern | Use when | Core API |53| --- | --- | --- |54| `TimeZoneInfo` | Windows-only code or known platform-specific ID. | `TimeZoneInfo.FindSystemTimeZoneById()`, `TimeZoneInfo.ConvertTimeFromUtc(...)`. |55| `TimeZoneConverter` | Cross-platform conversion across Windows, Linux, containers, and Azure. | `TZConvert.GetTimeZoneInfo("Asia/Colombo")`. |56| `NodaTime` | Recurring schedules, strict arithmetic, DST-sensitive jobs. | `DateTimeZone`, `Instant`, `ZonedDateTime`, resolvers for skipped/repeated local times. |57| `DateTimeOffset` | APIs and data transfer where offset must travel with the value. | `DateTimeOffset` and UTC normalization. |58| ASP.NET Core persistence/presentation | Store UTC instants and display in user-selected zone. | Database UTC column plus user timezone ID. |59| Recurring jobs and schedulers | Future local time must stay local after DST changes. | Store local schedule + zone ID, compute next occurrence with timezone rules. |60| Ambiguous and invalid DST timestamps | Local time may repeat or not exist. | Validate with `TimeZoneInfo.IsAmbiguousTime()` and `TimeZoneInfo.IsInvalidTime()` or NodaTime resolvers. |6162```csharp63using TimeZoneConverter;6465TimeZoneInfo tz = TZConvert.GetTimeZoneInfo("Asia/Colombo");66DateTime local = TimeZoneInfo.ConvertTimeFromUtc(DateTime.UtcNow, tz);67```6869## Pitfall warnings7071| Pitfall | Corrective rule |72| --- | --- |73| `TimeZoneInfo.FindSystemTimeZoneById()` is platform-specific | Use Windows IDs on Windows, IANA IDs on Linux/containers, or `TimeZoneConverter` to bridge both. |74| Storing `DateTime.Now` in databases | Store UTC instants; convert only at boundaries and presentation. |75| `DateTimeKind.Unspecified` leaks into conversions | Treat it as a bug risk unless it deliberately represents user-entered local wall time. |76| DST transitions skip or repeat local times | Validate invalid and ambiguous local timestamps before scheduling or converting. |77| Azure Windows and Azure Linux differ | Use the ID format expected by the host OS or use `TimeZoneConverter`. |7879Keep answers production-safe, code-first, and explicit about third-party package requirements.8081## Output template8283```markdown84## .NET timezone result8586**Status:** resolved | ambiguous | blocked87**Recommended approach:** <TimeZoneInfo | TimeZoneConverter | NodaTime | DateTimeOffset>8889| Location or scenario | Windows ID | IANA ID | Offset/DST | Notes |90| --- | --- | --- | --- | --- |91| `<place or code path>` | `<windows>` | `<iana>` | `<offsets>` | `<pitfall>` |9293 <copy-paste-ready C# snippet>9495**Package requirement:** `<none | TimeZoneConverter | NodaTime>`96**Warning:** <relevant pitfall>97```9899## Quality gate100101- [ ] The request type was identified before choosing a library.102- [ ] Location requests include Windows ID, IANA ID, UTC offset, and DST status for each resolved place.103- [ ] Cross-platform code uses `TimeZoneConverter` unless the platform-specific ID requirement is explicit.104- [ ] Recurring schedules or strict DST logic use or recommend `NodaTime`.105- [ ] API and persistence guidance stores UTC and preserves timezone IDs when future local scheduling matters.106- [ ] The response includes a minimal copy-paste-ready C# snippet and package guidance.107- [ ] Ambiguous locations or DST timestamps are not silently guessed.108109## Progressive disclosure and bundled resources110111- `references/timezone-index.md`: common Windows and IANA timezone mappings.112- `references/code-patterns.md`: ready-to-use .NET timezone patterns.
paulasilvatech