Analisando Unix Timestamp em C#: de timestamp para DateTime e vice-versa

Introdução: Por que Unix Timestamp não é apenas um número

Todo desenvolvedor que trabalha com APIs, bancos de dados ou logs, mais cedo ou mais tarde, encontra o Unix timestamp. É um número inteiro (ou número de ponto flutuante) que representa a quantidade de segundos decorridos desde 1º de janeiro de 1970, 00:00:00 UTC — a chamada época Unix (Unix epoch).

Mas quando você vê o número 1719878400 na resposta de um servidor, seu cérebro não consegue dizer imediatamente: "Ah, isso é 2 de julho de 2024". Precisamos convertê-lo para um DateTime familiar. E vice-versa — salvar uma data como timestamp para transmissão.

No Stack Overflow, a pergunta "How can I convert a Unix timestamp to DateTime and vice versa?" acumulou centenas de milhares de visualizações. Isso significa que mesmo desenvolvedores C# experientes às vezes se confundem com as nuances. Neste artigo, não vamos apenas fornecer receitas prontas, mas também vamos nos aprofundar: entender como funcionam DateTime, DateTimeOffset, ticks e fusos horários.

O que é realmente um Unix Timestamp?

Antes de escrever código, vamos definir os termos. Unix timestamp é a quantidade de segundos (às vezes milissegundos) desde a meia-noite de 1º de janeiro de 1970 UTC. Importante: é um momento absoluto no tempo, independente do fuso horário. É por isso que é tão conveniente usá-lo em sistemas distribuídos.

Em C#, trabalhamos com dois tipos principais:

\n
• DateTime — o tipo clássico, que pode estar em UTC ou no horário local (propriedade Kind).
\n
• DateTimeOffset — um tipo mais moderno, que armazena explicitamente o deslocamento do UTC. Recomendado para novos projetos.
\n

Internamente, DateTime armazena a quantidade de ticks (intervalos de 100 nanossegundos) desde 1º de janeiro do ano 1. E o Unix timestamp é simplesmente a quantidade de segundos desde 1970. Para passar de um para o outro, precisamos calcular a diferença entre essas duas épocas.

Convertendo Unix Timestamp para DateTime (e vice-versa) — métodos básicos

A partir do .NET Framework 4.6 e .NET Core, o C# possui métodos integrados que facilitam a vida. Vamos vê-los.

1. De Unix timestamp (segundos) para DateTime

A maneira mais simples é usar DateTimeOffset.FromUnixTimeSeconds(). Ele retorna um DateTimeOffset, que pode ser convertido para DateTime.

long unixTimestamp = 1719878400; // 2 de julho de 2024, 00:00:00 UTC\n\n// Obtém o DateTimeOffset\nDateTimeOffset dateTimeOffset = DateTimeOffset.FromUnixTimeSeconds(unixTimestamp);\n\n// Converte para DateTime (UTC)\nDateTime utcDateTime = dateTimeOffset.UtcDateTime;\n\nConsole.WriteLine(utcDateTime); // 02.07.2024 0:00:00

Se você precisar do horário local (por exemplo, para exibir ao usuário), use dateTimeOffset.LocalDateTime. Mas tenha cuidado: o horário local depende das configurações do servidor ou computador.

2. De DateTime para Unix timestamp

A conversão inversa é feita através do método ToUnixTimeSeconds() do DateTimeOffset.

DateTime utcDateTime = new DateTime(2024, 7, 2, 0, 0, 0, DateTimeKind.Utc);\n\n// Cria um DateTimeOffset com indicação explícita de UTC\nDateTimeOffset dateTimeOffset = new DateTimeOffset(utcDateTime);\n\nlong unixTimestamp = dateTimeOffset.ToUnixTimeSeconds();\n\nConsole.WriteLine(unixTimestamp); // 1719878400

É fundamental: sempre especifique DateTimeKind.Utc ao criar um DateTime que você pretende converter. Se não fizer isso, o DateTimeOffset assumirá que o horário é local e você obterá um timestamp incorreto — com um deslocamento do seu fuso horário.

3. Trabalhando com milissegundos

Às vezes, o timestamp é fornecido em milissegundos (por exemplo, do JavaScript). Para isso, ex