Dates

Escopo: C#. Idiomas específicos deste ecossistema.

O DateTime do C# guarda, além da data e da hora, um campo Kind que diz se aquele instante é local, é UTC (Coordinated Universal Time · Tempo Universal Coordenado) ou é indefinido. O problema é que a maior parte das formas de criar um DateTime deixa esse campo como indefinido, e o valor passa a depender de quem o lê. Use DateTimeOffset, que carrega o deslocamento em relação ao UTC dentro do próprio valor. Guarde tudo em UTC, que é a referência comum entre servidores, e converta para o timezone (fuso horário) do usuário só na hora de exibir.

DateTime.Now devolve a hora do relógio da máquina onde o código roda. Dois servidores em regiões diferentes, ou dois containers com fuso diferente, gravam horas diferentes para o mesmo acontecimento, e comparar esses valores depois produz respostas erradas. DateTimeOffset.UtcNow devolve sempre o mesmo instante, com o deslocamento explícito no valor.

var createdAt = DateTime.Now;
// Kind: Local (depende do timezone do servidor)
// Comparações entre servidores em timezones diferentes produzem resultados errados

var createdAt = DateTimeOffset.UtcNow;
// Offset: +00:00 (inequívoco, portável)
// Serializa como "2026-04-19T14:00:00+00:00"

Um DateTime com Kind indefinido no contrato da API entrega ao cliente um "2026-04-19T14:00:00" que não diz de que fuso aquilo veio. Cada lado interpreta com a própria convenção, e a diferença aparece como um pedido criado três horas no futuro. DateTimeOffset serializa "2026-04-19T14:00:00+00:00", e o +00:00 responde a pergunta sem depender de combinação prévia.

public record OrderResponse
{
    public required Guid Id { get; init; }
    public required DateTime CreatedAt { get; init; }
    // Kind: Unspecified: impossível saber se é UTC ou local sem convenção externa
}

public record OrderResponse
{
    public required Guid Id { get; init; }
    public required DateTimeOffset CreatedAt { get; init; }
    // "2026-04-19T14:00:00+00:00" (timezone embutida no valor)
}

Uma data de nascimento não tem hora. Guardá-la num DateTime acrescenta um 00:00:00 que ninguém pediu, e esse zero vira problema quando o valor é convertido de fuso: a meia-noite de 21 de agosto em São Paulo é o dia 20 em UTC, e a data de nascimento anda um dia para trás. DateOnly e TimeOnly (.NET 6+) guardam só o que interessa e não têm o que deslocar.

public record CustomerRequest
{
    public required string Name { get; init; }
    public required DateTime BirthDate { get; init; }
    // "1990-08-21T00:00:00": hora zero sem sentido, sujeita a deslocamento de timezone
}

public record CustomerRequest
{
    public required string Name { get; init; }
    public required DateOnly BirthDate { get; init; }
    // "1990-08-21" (só data, sem componente de hora)
}

public record ScheduleRequest
{
    public required DateOnly Date { get; init; }
    public required TimeOnly StartTime { get; init; }
    // "09:30:00" (só hora, sem data acoplada)
}

O EF Core grava o DateTime conforme o Kind que ele encontrar. Quando o Kind é indefinido, o valor vai para o banco sem conversão e volta indefinido na leitura: a informação de fuso não estava lá para se perder. Declarar a propriedade como DateTimeOffset resolve na origem. O EF mapeia para datetimeoffset no SQL Server e timestamptz no PostgreSQL, e o deslocamento sobrevive à ida e à volta sem configuração extra.

public class Order
{
    public Guid Id { get; set; }
    public DateTime CreatedAt { get; set; } // Kind: Unspecified após leitura do banco
}

public class Order
{
    public Guid Id { get; set; }
    public DateTimeOffset CreatedAt { get; set; }
    // SQL Server: datetimeoffset, PostgreSQL: timestamptz
    // Offset preservado no round-trip, sem configuração extra
}

DoDocs v3.7.0 · Desenvolvido por @thiagocajadev · Baseado no trabalho de pmndrs/docs · Poimandres.