NodaTime para C# (.NET): guía completa con ejemplos

Trabajar con fechas y horas es una de las tareas más complejas y propensas a errores en el desarrollo de software. Los tipos integrados DateTime y DateTimeOffset en .NET tienen varios problemas fundamentales: confusión entre hora local y UTC, falta de una separación clara entre "instante en el tiempo" y "fecha del calendario", ambigüedad al trabajar con zonas horarias y horario de verano. La librería NodaTime fue creada para resolver estos problemas, ofreciendo a los desarrolladores una API segura, expresiva y tipográficamente robusta para el manejo del tiempo.

NodaTime es una librería alternativa para trabajar con fechas y horas en .NET, inspirada en la librería Joda-Time para Java. Proporciona una separación clara entre diferentes conceptos temporales: Instant (instante en el tiempo), LocalDateTime (fecha y hora sin zona horaria), ZonedDateTime (fecha y hora con zona horaria), Duration (intervalo de tiempo en nanosegundos) y Period (intervalo de tiempo en unidades de calendario). La librería utiliza datos de zonas horarias de IANA (base de datos tzdata), lo que la hace más precisa y actualizada que los mecanismos integrados de Windows.

El objetivo principal de NodaTime es hacer que las operaciones incorrectas con el tiempo sean imposibles a nivel de compilación. Por ejemplo, no podrás sumar accidentalmente un LocalDateTime con un Duration (porque no tiene sentido sin una zona horaria), ni comparar un Instant con un LocalDate. La librería también ofrece potentes capacidades para formateo, análisis sintáctico, trabajo con zonas horarias y sistemas de calendario (incluyendo los calendarios juliano, islámico y hebreo).

Instalación

Para instalar NodaTime en un proyecto .NET, usa el Administrador de Paquetes NuGet. Ejecuta uno de los siguientes comandos:

# A través de .NET CLI (recomendado)
dotnet add package NodaTime

# A través de Package Manager Console (Visual Studio)
Install-Package NodaTime

# O a través de la interfaz de NuGet Package Manager: busca "NodaTime"

Después de la instalación, añade la directiva using NodaTime; al inicio de tu archivo. Para trabajar con zonas horarias, también puede ser necesario using NodaTime.TimeZones;.

Inicio rápido

Un ejemplo mínimo funcional que demuestra las capacidades principales de NodaTime:

using NodaTime;
using NodaTime.Text;

// 1. Instante actual en UTC
Instant now = SystemClock.Instance.GetCurrentInstant();
Console.WriteLine($"Instante actual (UTC): {now}");

// 2. Conversión a hora local (Ciudad de México)
DateTimeZone mexicoZone = DateTimeZoneProviders.Tzdb["America/Mexico_City"];
ZonedDateTime mexicoTime = now.InZone(mexicoZone);
Console.WriteLine($"Hora en México: {mexicoTime}");

// 3. Creación de una fecha y hora específica
LocalDateTime localDate = new LocalDateTime(2024, 12, 25, 10, 30, 0);
Console.WriteLine($"Fecha local: {localDate}");

// 4. Análisis sintáctico de una cadena
var pattern = LocalDateTimePattern.CreateWithInvariantCulture("yyyy-MM-dd HH:mm:ss");
LocalDateTime parsed = pattern.Parse("2024-12-25 10:30:00").Value;
Console.WriteLine($"Analizado: {parsed}");

// 5. Trabajo con duraciones
Duration duration = Duration.FromHours(2.5);
Instant future = now + duration;
Console.WriteLine($"Dentro de 2.5 horas: {future.InZone(mexicoZone)}");

Clases y métodos principales

1. Instant — instante en el tiempo

Firma: public readonly struct Instant : IEquatable<Instant>, IComparable<Instant>

Qué hace: Representa un punto en la línea de tiempo, medido en nanosegundos desde la época Unix (1 de enero de 1970, 00:00:00 UTC). No depende de zonas horarias.

Instant epoch = Instant.FromUnixTimeTicks(0); // Época Unix
Instant now = Sy