NodaTime para C# (.NET): guia completo com exemplos práticos

Trabalhar com data e hora é uma das tarefas mais complexas e propensas a erros no desenvolvimento de software. Os tipos nativos DateTime e DateTimeOffset do .NET apresentam problemas fundamentais: confusão entre hora local e UTC, falta de separação clara entre "instante no tempo" e "data do calendário", ambiguidade ao lidar com fusos horários e horário de verão. A biblioteca NodaTime foi criada para resolver esses problemas, oferecendo aos desenvolvedores uma API segura, expressiva e type-safe para manipulação de tempo.

NodaTime é uma biblioteca alternativa para trabalhar com data e hora no .NET, inspirada na biblioteca Joda-Time para Java. Ela fornece uma separação clara entre diferentes conceitos de tempo: Instant (instante no tempo), LocalDateTime (data e hora sem fuso horário), ZonedDateTime (data e hora com fuso horário), Duration (intervalo de tempo em nanossegundos) e Period (intervalo de tempo em unidades de calendário). A biblioteca utiliza dados de fusos horários da IANA (base tzdata), tornando-a mais precisa e atualizada que os mecanismos nativos do Windows.

O principal objetivo do NodaTime é tornar operações inválidas com tempo impossíveis em tempo de compilação. Por exemplo, você não conseguirá somar acidentalmente um LocalDateTime com um Duration (pois isso não faz sentido sem um fuso horário), nem comparar um Instant com um LocalDate. A biblioteca também oferece recursos poderosos para formatação, parsing, manipulação de fusos horários e sistemas de calendário (incluindo calendários juliano, islâmico e hebraico).

Instalação

Para instalar o NodaTime em um projeto .NET, use o Gerenciador de Pacotes NuGet. Execute um dos seguintes comandos:

# Via .NET CLI (recomendado)
dotnet add package NodaTime

# Via Package Manager Console (Visual Studio)
Install-Package NodaTime

# Ou via interface do NuGet Package Manager: procure por "NodaTime"

Após a instalação, adicione a diretiva using NodaTime; no início do seu arquivo. Para trabalhar com fusos horários, você também pode precisar de using NodaTime.TimeZones;.

Início rápido

Um exemplo mínimo funcional demonstrando os principais recursos do NodaTime:

using NodaTime;
using NodaTime.Text;

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

// 2. Conversão para hora local (São Paulo)
DateTimeZone saoPauloZone = DateTimeZoneProviders.Tzdb["America/Sao_Paulo"];
ZonedDateTime saoPauloTime = now.InZone(saoPauloZone);
Console.WriteLine($"Hora em São Paulo: {saoPauloTime}");

// 3. Criando uma data e hora específica
LocalDateTime localDate = new LocalDateTime(2024, 12, 25, 10, 30, 0);
Console.WriteLine($"Data local: {localDate}");

// 4. Parsing de string
var pattern = LocalDateTimePattern.CreateWithInvariantCulture("yyyy-MM-dd HH:mm:ss");
LocalDateTime parsed = pattern.Parse("2024-12-25 10:30:00").Value;
Console.WriteLine($"Parseado: {parsed}");

// 5. Trabalhando com durações
Duration duration = Duration.FromHours(2.5);
Instant future = now + duration;
Console.WriteLine($"Daqui a 2.5 horas: {future.InZone(saoPauloZone)}");

Principais classes e métodos

1. Instant — instante no tempo

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

O que faz: Representa um ponto na linha do tempo, medido em nanossegundos desde a época Unix (1º de janeiro de 1970, 00:00:00 UTC). Não depende de fusos horários.

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