Analyse du Timestamp Unix en C# : de l'horodatage à DateTime et inversement

Introduction : Pourquoi le Timestamp Unix n'est pas qu'un simple nombre

Chaque développeur travaillant avec des API, des bases de données ou des logs rencontre tôt ou tard le timestamp Unix. C'est un nombre entier (ou à virgule flottante) qui représente le nombre de secondes écoulées depuis le 1er janvier 1970 à 00:00:00 UTC — ce qu'on appelle l'époque Unix (Unix epoch).

Mais lorsque vous voyez le nombre 1719878400 dans une réponse serveur, votre cerveau ne peut pas immédiatement dire : « Ah, c'est le 2 juillet 2024 ». Nous devons le convertir en un DateTime familier. Et inversement — enregistrer une date sous forme d'horodatage pour la transmission.

Sur Stack Overflow, la question « How can I convert a Unix timestamp to DateTime and vice versa? » a accumulé des centaines de milliers de vues. Cela signifie que même les développeurs C# expérimentés se perdent parfois dans les nuances. Dans cet article, nous ne donnerons pas seulement des recettes toutes faites, mais nous regarderons sous le capot : nous analyserons comment fonctionnent DateTime, DateTimeOffset, les ticks et les fuseaux horaires.

Qu'est-ce qu'un Timestamp Unix en réalité ?

Avant d'écrire du code, mettons-nous d'accord sur les termes. Le timestamp Unix est le nombre de secondes (parfois de millisecondes) depuis minuit le 1er janvier 1970 UTC. Important : c'est un moment absolu dans le temps, indépendant du fuseau horaire. C'est pourquoi il est si pratique à utiliser dans les systèmes distribués.

En C#, nous travaillons avec deux types principaux :

\n
• DateTime — le type classique, qui peut être soit en UTC, soit en heure locale (propriété Kind).
\n
• DateTimeOffset — un type plus moderne, qui stocke explicitement le décalage par rapport à UTC. Recommandé pour les nouveaux projets.
\n

Sous le capot, DateTime stocke le nombre de ticks (intervalles de 100 nanosecondes) depuis le 1er janvier de l'an 0001. Et le timestamp Unix est simplement le nombre de secondes depuis 1970. Pour passer de l'un à l'autre, il faut calculer la différence entre ces deux époques.

Conversion d'un Timestamp Unix en DateTime (et inversement) — méthodes de base

Depuis .NET Framework 4.6 et .NET Core, des méthodes intégrées sont apparues en C# pour simplifier la vie. Voyons-les.

1. Du timestamp Unix (secondes) vers DateTime

La méthode la plus simple consiste à utiliser DateTimeOffset.FromUnixTimeSeconds(). Elle retourne un DateTimeOffset, qui peut ensuite être converti en DateTime.

long unixTimestamp = 1719878400; // 2 juillet 2024, 00:00:00 UTC\n\n// On obtient un DateTimeOffset\nDateTimeOffset dateTimeOffset = DateTimeOffset.FromUnixTimeSeconds(unixTimestamp);\n\n// Conversion en DateTime (UTC)\nDateTime utcDateTime = dateTimeOffset.UtcDateTime;\n\nConsole.WriteLine(utcDateTime); // 02.07.2024 0:00:00

Si vous avez besoin de l'heure locale (par exemple, pour l'afficher à l'utilisateur), utilisez dateTimeOffset.LocalDateTime. Mais attention : l'heure locale dépend des paramètres du serveur ou de l'ordinateur.

2. De DateTime vers un timestamp Unix

La conversion inverse se fait via la méthode ToUnixTimeSeconds() de DateTimeOffset.

DateTime utcDateTime = new DateTime(2024, 7, 2, 0, 0, 0, DateTimeKind.Utc);\n\n// Création d'un DateTimeOffset avec indication explicite de l'UTC\nDateTimeOffset dateTimeOffset = new DateTimeOffset(utcDateTime);\n\nlong unixTimestamp = dateTimeOffset.ToUnixTimeSeconds();\n\nConsole.WriteLine(unixTimestamp); // 1719878400

Il est crucial de toujours spécifier DateTimeKind.Utc lors de la création d'un DateTime que vous comptez convertir. Si vous ne le faites pas, DateTimeOffset considérera que l'heure est locale et vous obtiendrez un timestamp incorrect — décalé de votre fuseau horaire.

3. Travail avec les millisecondes

Parfois, le timestamp est transmis en millisecondes (par exemple, depuis JavaScript). Pour cela, e