Vali-TimeZone 1.0.0

.NET 8.0

dotnet add package Vali-TimeZone --version 1.0.0

NuGet\Install-Package Vali-TimeZone -Version 1.0.0

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="Vali-TimeZone" Version="1.0.0" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="Vali-TimeZone" Version="1.0.0" />
                    

                            Directory.Packages.props

<PackageReference Include="Vali-TimeZone" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add Vali-TimeZone --version 1.0.0

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: Vali-TimeZone, 1.0.0"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package Vali-TimeZone@1.0.0

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=Vali-TimeZone&version=1.0.0
                    

                            Install as a Cake Addin

#tool nuget:?package=Vali-TimeZone&version=1.0.0
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Vali-TimeZone

Vali-TimeZone is the timezone-aware module of the Vali-Tempo ecosystem. It provides conversion between timezones, UTC offset calculations, DST detection, and a curated catalog of IANA-compatible timezone identifiers for 30+ countries.

Features

Convert DateTime between any two timezones
Convert DateTimeOffset preserving the absolute UTC instant
Get current time or today's date in any timezone
Detect Daylight Saving Time (DST) at a specific moment
Calculate UTC offset differences between two zones
Discover timezones by country code
Validate any IANA or Windows timezone ID
Format date-times with timezone offset included
Check if two local times in different zones are the same instant
45+ curated timezone entries (LATAM, Europe, North America, Asia, Oceania, UTC)

Installation

dotnet add package Vali-TimeZone

Compiled targets: net8.0 · net9.0. Compatible with .NET 6 and .NET 7 via NuGet backward compatibility — no separate build needed.

Quick Start

using Vali_TimeZone.Core;

var tz = new ValiTimeZone();

// Convert Lima → Madrid
var lima   = new DateTime(2025, 7, 15, 10, 0, 0);
var madrid = tz.Convert(lima, "America/Lima", "Europe/Madrid");
// madrid → 2025-07-15 17:00:00

// Get current time in Tokyo
var tokyoNow = tz.Now("Asia/Tokyo");

// Is Lima currently in DST?
var isDst = tz.IsDst(DateTime.Now, "America/Lima"); // false

// Offset difference Lima ↔ New York
var diff = tz.OffsetDiff("America/Lima", "America/New_York"); // 0 (both UTC-5)

// Format with offset
var formatted = tz.FormatWithZone(lima, "America/Lima");
// "2025-07-15 10:00:00 -05:00"

// Find all timezones for Chile
var zones = tz.ZonesForCountry("CL");

Dependency Injection

// Program.cs
builder.Services.AddValiTimeZone();

// Optional: provide a custom IClock (defaults to DateTime.UtcNow)
// builder.Services.AddSingleton<IClock, MyCustomClock>();

ValiTimeZone accepts an optional IClock in its constructor. When registered via AddValiTimeZone(), it automatically resolves IClock from the container if one is registered, or falls back to SystemClock.Instance.

// Service constructor
public class MyService(IValiTimeZone timeZone)
{
    public DateTime GetLondonTime(DateTime utcTime) =>
        timeZone.FromUtc(utcTime, "Europe/London");
}

Core API

Conversion

Method	Description
`Convert(dt, fromZone, toZone)`	Convert DateTime between two timezones
`ConvertOffset(dto, toZone)`	Convert DateTimeOffset to another timezone
`ToUtc(local, fromZone)`	Convert local DateTime to UTC
`FromUtc(utc, toZone)`	Convert UTC DateTime to local time
`ToDateTimeOffset(dt, zone)`	Wrap DateTime as DateTimeOffset with zone offset

Timezone Info

Method	Description
`GetOffset(zone, at?)`	UTC offset at a specific instant (DST-aware)
`GetBaseOffset(zone)`	Standard UTC offset (no DST)
`IsDst(dt, zone)`	Whether the datetime falls in DST
`OffsetDiff(zone1, zone2, at?)`	Difference in hours between two zones

Discovery

Method	Description
`FindZone(id)`	Lookup a `ValiZoneInfo` by IANA ID
`AllZones()`	All curated timezone entries
`ZonesForCountry(code)`	Timezones for a country (ISO 3166-1 alpha-2)
`IsValidZone(id)`	Validate IANA or Windows timezone ID

Utilities

Method	Description
`Now(zone)`	Current time in a timezone
`Today(zone)`	Today's date (midnight) in a timezone
`IsSameInstant(a, zA, b, zB)`	Whether two local times are the same UTC instant
`FormatWithZone(dt, zone, fmt?)`	Format a DateTime with its timezone offset

ValiZoneInfo

Each curated entry exposes:

Property	Type	Description
`Id`	`string`	IANA identifier (e.g. `"America/Lima"`)
`DisplayName`	`string`	Human-readable name with UTC offset
`StandardName`	`string`	Windows/BCL name for `TimeZoneInfo` fallback
`BaseOffset`	`TimeSpan`	Standard UTC offset (no DST)
`SupportsDst`	`bool`	Whether DST is observed
`CountryCode`	`string`	ISO 3166-1 alpha-2 code
`CountryName`	`string`	Full English country name

Supported Timezone Catalog

Latin America

America/Lima · America/Bogota · America/Guayaquil · America/Santiago · America/Argentina/Buenos_Aires · America/Sao_Paulo · America/Mexico_City · America/Caracas · America/La_Paz · America/Asuncion · America/Montevideo · America/Panama · America/Costa_Rica · America/Santo_Domingo · America/Havana · America/Guatemala

North America

America/New_York · America/Chicago · America/Denver · America/Los_Angeles · America/Phoenix · America/Anchorage · America/Honolulu · America/Toronto · America/Vancouver

Europe

Europe/Madrid · Europe/London · Europe/Paris · Europe/Berlin · Europe/Rome · Europe/Amsterdam · Europe/Lisbon · Europe/Brussels · Europe/Vienna · Europe/Warsaw · Europe/Stockholm · Europe/Oslo · Europe/Copenhagen · Europe/Helsinki · Europe/Dublin · Europe/Zurich

Asia & Oceania

Asia/Tokyo · Asia/Shanghai · Asia/Kolkata · Asia/Singapore · Asia/Dubai · Asia/Seoul · Asia/Bangkok · Australia/Sydney

UTC

UTC

Part of the Vali-Tempo Ecosystem

Package	Description
Vali-Time	Core time conversion and formatting
Vali-Date	Date arithmetic and calendar operations
Vali-Range	Date range operations
Vali-Calendar	Workday and week calculations
Vali-Duration	High-precision duration struct
Vali-CountDown	Countdown and deadline tracking
Vali-Age	Age calculation utilities
Vali-Schedule	Recurring event scheduling
Vali-Holiday	Holiday providers for 35+ countries
Vali-TimeZone	Timezone conversion and discovery
Vali-Tempo	Meta-package: all of the above

License

Donations

If this package is useful to you, consider supporting its development:

Latin America — MercadoPago
International — PayPal

Product	Compatible and additional computed target framework versions.
.NET	net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 is compatible. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed.

Product

.NET

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

net8.0
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 9.0.0)
- Vali-Time (>= 1.0.1)
net9.0
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 9.0.0)
- Vali-Time (>= 1.0.1)

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Vali-TimeZone:

Package	Downloads
Vali-Tempo Vali-Tempo is the all-in-one meta-package for the Vali-Tempo ecosystem. Installing it gives you every module — Vali-Time, Vali-Range, Vali-Calendar, Vali-CountDown, Vali-Age, Vali-Holiday, Vali-TimeZone, Vali-Schedule, and Vali-Duration — with a single NuGet reference and a single DI registration call.	85

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
1.0.0	96	3/26/2026

Vali-TimeZone v1.0.0 — initial release: ValiTimeZone class with Convert, ToUtc, FromUtc, GetOffset, IsDst, FindZone, AllZones, ZonesForCountry, IsValidZone, Now, Today, IsSameInstant, FormatWithZone, and DateTimeOffset interoperability.