Trabalhando com datas e horas em C#: guia completo

Introdução ao trabalho com datas e horas em C#

Trabalhar com datas e horas é uma das tarefas fundamentais no desenvolvimento de software. Seja para registro de eventos, cálculo de prazos, criação de relatórios ou trabalho com bancos de dados — saber gerenciar corretamente dados temporais é criticamente importante. Em C# (plataforma .NET), existe um conjunto poderoso e flexível de ferramentas para esses fins, incluindo as estruturas DateTime, TimeSpan e DateTimeOffset.

Neste artigo, abordaremos detalhadamente todos os aspectos-chave do trabalho com datas e horas em C#. Você aprenderá como criar, formatar, comparar e manipular dados temporais, além de conhecer as melhores práticas que ajudarão a evitar erros comuns.

Estruturas principais: DateTime, TimeSpan e DateTimeOffset

Estrutura DateTime

DateTime é a estrutura principal para representar um momento no tempo (data + hora). Ela pode representar valores de 01.01.0001 a 31.12.9999.

Criação de um objeto DateTime:

// Data e hora atuaisDateTime now = DateTime.Now;DateTime utcNow = DateTime.UtcNow;

// Data e hora específicasDateTime specificDate = new DateTime(2025, 3, 15, 14, 30, 0); // 15 de março de 2025, 14:30:00

// Análise a partir de stringDateTime parsedDate = DateTime.Parse("2025-03-15");

// Usando TryParse para análise seguraif (DateTime.TryParse("2025-03-15", out DateTime result)){    Console.WriteLine($"Analisado com sucesso: {result}");}

Propriedades e métodos principais:

• Date — retorna apenas a data (hora = 00:00:00)
• Year, Month, Day, Hour, Minute, Second — componentes individuais
• DayOfWeek — dia da semana (enum)
• AddDays(), AddMonths(), AddYears() — aritmética com datas
• AddHours(), AddMinutes(), AddSeconds() — aritmética com horas

Estrutura TimeSpan

TimeSpan representa um intervalo de tempo (período entre dois momentos). Não é uma data, mas sim uma duração.

// Criação de TimeSpanTimeSpan interval = new TimeSpan(2, 15, 30); // 2 horas, 15 minutos, 30 segundos

// Diferença entre duas datasDateTime start = new DateTime(2025, 1, 1);DateTime end = new DateTime(2025, 1, 10);TimeSpan difference = end - start; // 9 dias

// Propriedades de TimeSpanConsole.WriteLine($"Dias: {difference.Days}");          // 9Console.WriteLine($"Total de horas: {difference.TotalHours}"); // 216Console.WriteLine($"Total de minutos: {difference.TotalMinutes}"); // 12960

// Aritmética com TimeSpanTimeSpan workDay = new TimeSpan(8, 0, 0); // 8 horasTimeSpan breakTime = new TimeSpan(1, 0, 0); // 1 horaTimeSpan actualWork = workDay - breakTime; // 7 horas

Estrutura DateTimeOffset

DateTimeOffset é uma versão melhorada do DateTime, que leva em conta o deslocamento em relação ao UTC. Isso é criticamente importante para aplicações que trabalham com usuários de diferentes fusos horários.

// Hora atual considerando o fuso horárioDateTimeOffset nowOffset = DateTimeOffset.Now;

// Criação especificando o deslocamentoDateTimeOffset withOffset = new DateTimeOffset(2025, 3, 15, 14, 0, 0, TimeSpan.FromHours(3));

// Conversão entre fusos horáriosDateTimeOffset utc = withOffset.ToUniversalTime();DateTimeOffset local = withOffset.ToLocalTime();

// Obtendo o deslocamentoConsole.WriteLine($"Deslocamento: {withOffset.Offset}"); // +03:00

Quando usar DateTimeOffset em vez de DateTime? Se sua aplicação trabalha com usuários de diferentes fusos horários ou armazena dados em UTC, use DateTimeOffset. Isso prev