Trabalhando com datas e horas em C#: DateTime, TimeSpan e formatação

Introdução: Por que trabalhar com datas em C# é importante

No desenvolvimento de software moderno, trabalhar com datas e horas é uma das tarefas mais frequentes e criticamente importantes. Seja para registro de eventos, cálculo de prazos, exibição de notícias ou criação de relatórios — em todos os lugares é necessário um gerenciamento preciso e flexível de dados temporais. C# e a plataforma .NET fornecem ao desenvolvedor um conjunto poderoso e intuitivo de ferramentas para esse fim.

Neste artigo, vamos detalhar os principais tipos para trabalhar com datas e horas em C#: DateTime, TimeSpan e DateTimeOffset. Você aprenderá como criar, modificar, formatar e comparar datas, bem como trabalhar corretamente com fusos horários. O material será útil tanto para iniciantes quanto para desenvolvedores experientes que desejam sistematizar seus conhecimentos.

Tipos de dados principais: DateTime, TimeSpan e DateTimeOffset

1. Estrutura DateTime

DateTime é o tipo principal para representar um momento no tempo (data + hora). Ele armazena informações de 1º de janeiro do ano 0001 a 31 de dezembro do ano 9999 com precisão de 100 nanossegundos (ticks).

Criação de um objeto DateTime:

// Data e hora atuaisDateTime now = DateTime.Now;// Data e hora atuais em UTCDateTime utcNow = DateTime.UtcNow;// Data específicaDateTime specificDate = new DateTime(2025, 3, 15);// Data e hora com precisão de segundosDateTime specificDateTime = new DateTime(2025, 3, 15, 14, 30, 0);// Data de hoje (hora = 00:00:00)DateTime today = DateTime.Today;

2. Estrutura TimeSpan

TimeSpan representa um intervalo de tempo (período). Ele não está vinculado a uma data específica, mas armazena a diferença no tempo: dias, horas, minutos, segundos e frações de segundos.

Criação e uso de TimeSpan:

// Criando um intervalo: 2 dias, 5 horas, 30 minutosTimeSpan interval = new TimeSpan(2, 5, 30, 0);// Intervalo a partir de horasTimeSpan fromHours = TimeSpan.FromHours(48.5);// Diferença entre duas datasDateTime start = new DateTime(2025, 1, 1);DateTime end = new DateTime(2025, 3, 15);TimeSpan difference = end - start;Console.WriteLine(difference.Days); // 73

3. Estrutura DateTimeOffset

DateTimeOffset é uma alternativa mais moderna ao DateTime, que além da data e hora, armazena o deslocamento em relação ao UTC (por exemplo, +03:00). Isso ajuda a evitar confusões com fusos horários ao transferir dados entre sistemas.

// Hora atual com deslocamentoDateTimeOffset localOffset = DateTimeOffset.Now;// Hora em UTC com deslocamento +00:00DateTimeOffset utcOffset = DateTimeOffset.UtcNow;// Criação especificando o deslocamentoDateTimeOffset specific = new DateTimeOffset(2025, 3, 15, 12, 0, 0, TimeSpan.FromHours(3));

Operações principais: adição, subtração e comparação

Aritmética com DateTime e TimeSpan

Uma das principais vantagens do C# é a aritmética conveniente de datas. Você pode facilmente adicionar ou subtrair dias, meses, anos, bem como trabalhar com horas e minutos.

DateTime today = DateTime.Today;// Adicionar 10 diasDateTime futureDate = today.AddDays(10);// Adicionar 2 mesesDateTime futureMonth = today.AddMonths(2);// Subtrair 1 anoDateTime pastYear = today.AddYears(-1);// Adicionar 5 horas e 30 minutosDateTime precise = today.AddHours(5).AddMinutes(30);

Trabalhando com TimeSpan:

TimeSpan workDay = new TimeSpan(8, 0, 0); // 8 horasTimeSpan breakTime = new TimeSpan(0, 45, 0); // 45 minutosTimeSpan totalWork = workDay + breakTime; // 8 horas e 45 minutosTimeSpan remaining = workDay - breakTime; // 7 horas e 15 minutos

Comparação de datas

Para comparar dois momentos no tempo, são usados os operadores de comparação padrão:

Da