Analizando Unix Timestamp en C#: de marca de tiempo a DateTime y viceversa

Introducción: Por qué Unix Timestamp no es solo un número

Cada desarrollador que trabaja con API, bases de datos o registros, tarde o temprano se encuentra con el Unix timestamp. Es un número entero (o número de punto flotante) que indica la cantidad de segundos transcurridos desde el 1 de enero de 1970 a las 00:00:00 UTC — la llamada época Unix (Unix epoch).

Pero cuando ves el número 1719878400 en la respuesta de un servidor, tu cerebro no puede decir inmediatamente: «Ajá, esto es el 2 de julio de 2024». Necesitamos convertirlo en un DateTime familiar. Y viceversa — guardar una fecha como una marca para su transmisión.

En Stack Overflow, la pregunta «How can I convert a Unix timestamp to DateTime and vice versa?» ha obtenido cientos de miles de visitas. Esto significa que incluso los desarrolladores experimentados en C# a veces se confunden con los matices. En este artículo no solo daremos recetas listas, sino que también miraremos bajo el capó: analizaremos cómo funcionan DateTime, DateTimeOffset, los tics y las zonas horarias.

¿Qué es realmente Unix Timestamp?

Antes de escribir código, acordemos los términos. Unix timestamp es la cantidad de segundos (a veces milisegundos) desde la medianoche del 1 de enero de 1970 UTC. Importante: es un momento absoluto en el tiempo, independiente de la zona horaria. Por eso es tan conveniente usarlo en sistemas distribuidos.

En C# trabajamos con dos tipos principales:

\n
• DateTime — el tipo clásico, que puede estar tanto en UTC como en hora local (propiedad Kind).
\n
• DateTimeOffset — un tipo más moderno que almacena explícitamente el desplazamiento de UTC. Se recomienda para proyectos nuevos.
\n

Bajo el capó, DateTime almacena la cantidad de tics (intervalos de 100 nanosegundos) desde el 1 de enero del año 1. Y Unix timestamp es simplemente la cantidad de segundos desde 1970. Para pasar de uno a otro, necesitamos calcular la diferencia entre estas dos épocas.

Conversión de Unix Timestamp a DateTime (y viceversa) — métodos básicos

A partir de .NET Framework 4.6 y .NET Core, aparecieron en C# métodos integrados que facilitan la vida. Veámoslos.

1. De Unix timestamp (segundos) a DateTime

La forma más sencilla es usar DateTimeOffset.FromUnixTimeSeconds(). Devuelve un DateTimeOffset, que luego se puede convertir a DateTime.

long unixTimestamp = 1719878400; // 2 de julio de 2024, 00:00:00 UTC\n\n// Obtenemos DateTimeOffset\nDateTimeOffset dateTimeOffset = DateTimeOffset.FromUnixTimeSeconds(unixTimestamp);\n\n// Convertimos a DateTime (UTC)\nDateTime utcDateTime = dateTimeOffset.UtcDateTime;\n\nConsole.WriteLine(utcDateTime); // 02.07.2024 0:00:00

Si necesita la hora local (por ejemplo, para mostrarla al usuario), use dateTimeOffset.LocalDateTime. Pero tenga cuidado: la hora local depende de la configuración del servidor o del ordenador.

2. De DateTime a Unix timestamp

La conversión inversa — mediante el método ToUnixTimeSeconds() de DateTimeOffset.

DateTime utcDateTime = new DateTime(2024, 7, 2, 0, 0, 0, DateTimeKind.Utc);\n\n// Creamos DateTimeOffset con indicación explícita de UTC\nDateTimeOffset dateTimeOffset = new DateTimeOffset(utcDateTime);\n\nlong unixTimestamp = dateTimeOffset.ToUnixTimeSeconds();\n\nConsole.WriteLine(unixTimestamp); // 1719878400

Es críticamente importante: siempre especifique DateTimeKind.Utc al crear un DateTime que vaya a convertir. Si no lo hace, DateTimeOffset asumirá que la hora es local y obtendrá un timestamp incorrecto — con un desplazamiento según su zona horaria.

3. Trabajo con milisegundos

A veces el timestamp se transmite en milisegundos (por ejemplo, desde JavaScript). Para e