NodaTime pour C# (.NET) : guide complet avec exemples

La gestion des dates et heures est l'une des tâches les plus complexes et sujettes aux erreurs en développement logiciel. Les types intégrés DateTime et DateTimeOffset dans .NET présentent plusieurs problèmes fondamentaux : confusion entre l'heure locale et UTC, absence de séparation claire entre un "instant dans le temps" et une "date calendaire", ambiguïté lors de la gestion des fuseaux horaires et de l'heure d'été. La bibliothèque NodaTime a été créée pour résoudre ces problèmes, offrant aux développeurs une API sécurisée, expressive et typée pour la gestion du temps.

NodaTime est une bibliothèque alternative pour la gestion des dates et heures dans .NET, inspirée de Joda-Time pour Java. Elle propose une séparation nette entre différents concepts temporels : Instant (un moment dans le temps), LocalDateTime (date et heure sans fuseau horaire), ZonedDateTime (date et heure avec fuseau horaire), Duration (intervalle de temps en nanosecondes) et Period (intervalle de temps en unités calendaires). La bibliothèque utilise les données de fuseaux horaires de l'IANA (base tzdata), ce qui la rend plus précise et à jour que les mécanismes intégrés de Windows.

L'objectif principal de NodaTime est de rendre les opérations temporelles incorrectes impossibles au niveau de la compilation. Par exemple, vous ne pouvez pas accidentellement additionner un LocalDateTime avec une Duration (car cela n'a pas de sens sans fuseau horaire), ni comparer un Instant avec un LocalDate. La bibliothèque offre également des fonctionnalités puissantes pour le formatage, l'analyse, la gestion des fuseaux horaires et des systèmes calendaires (y compris les calendriers julien, islamique et hébreu).

Installation

Pour installer NodaTime dans un projet .NET, utilisez le gestionnaire de packages NuGet. Exécutez l'une des commandes suivantes :

# Via .NET CLI (recommandé)
dotnet add package NodaTime

# Via la console du gestionnaire de packages (Visual Studio)
Install-Package NodaTime

# Ou via l'interface utilisateur NuGet : recherchez "NodaTime"

Après l'installation, ajoutez la directive using NodaTime; au début de votre fichier. Pour travailler avec les fuseaux horaires, vous aurez peut-être aussi besoin de using NodaTime.TimeZones;.

Démarrage rapide

Un exemple minimal fonctionnel illustrant les principales fonctionnalités de NodaTime :

using NodaTime;
using NodaTime.Text;

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

// 2. Conversion en heure locale (Paris)
DateTimeZone parisZone = DateTimeZoneProviders.Tzdb["Europe/Paris"];
ZonedDateTime parisTime = now.InZone(parisZone);
Console.WriteLine($"Heure à Paris : {parisTime}");

// 3. Création d'une date et heure spécifique
LocalDateTime localDate = new LocalDateTime(2024, 12, 25, 10, 30, 0);
Console.WriteLine($"Date locale : {localDate}");

// 4. Analyse d'une chaîne de caractères
var pattern = LocalDateTimePattern.CreateWithInvariantCulture("yyyy-MM-dd HH:mm:ss");
LocalDateTime parsed = pattern.Parse("2024-12-25 10:30:00").Value;
Console.WriteLine($"Chaîne analysée : {parsed}");

// 5. Travail avec les durées
Duration duration = Duration.FromHours(2.5);
Instant future = now + duration;
Console.WriteLine($"Dans 2,5 heures : {future.InZone(parisZone)}");

Classes et méthodes principales

1. Instant — un moment dans le temps

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

Fonction : Représente un point sur la ligne temporelle, mesuré en nanosecondes depuis l'époque Unix (1er janvier 1970, 00:00:00 UTC). Indépendant des fuseaux horaires.

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