Antes de começarmos

Para trabalhar com datas e horas em C#, utilizamos a estrutura DateTime, uma ferramenta extremamente útil, leve e de uso simplificado. Neste artigo, exploraremos como aplicá-la em situações reais no mercado de trabalho, demonstrando sua aplicação nos mais diversos cenários.

Precisamos ter em mente que DateTime é uma estrutura. Por ser uma estrutura (struct), ela é composta por outros tipos e métodos, permitindo assim a criação, manipulação, comparação e exibição de datas e horas em diferentes formatos, conforme necessário em seu projeto. Estruturas são uma das formas de armazenar dados, sendo alocadas diretamente onde a variável é declarada, o que é conhecido como um elemento do tipo valor, diferente de classes, por exemplo, que são do tipo de referência.

Em analogia, quando trabalhamos com DateTime, é como se fizéssemos uma cópia dele, nunca modificando o original. Essa característica torna o DateTime extremamente útil, por ser projetado para uso recorrente nos projetos, ao mesmo tempo em que tem acesso rápido às informações de data e hora, com baixo consumo de memória.

Criando um DateTime

Para criar um DateTime, fazemos da seguinte maneira:

var data = new DateTime();

Como é um elemento do tipo valor, ele possui um valor inicial, não podendo ser nulo. O valor padrão, nesse caso, é:

// 1/1/0001 12:00:00 AM  (Formato: MM/DD/YYYY HH:MM:SS)

O formato de saída dos dados dependerá da cultura do sistema da sua máquina. Nos próximos tópicos discutiremos sobre como adequar essa saída para diferentes culturas.

Armazenando data e hora atual

Se deseja que a variável que criamos receba data e hora atual, basta atribuir essa informação, assim:

var data = DateTime.Now;
System.Console.WriteLine(data);

//Saída esperada: 2/20/2024 8:00:00 AM

Note que esse horário do exemplo é referente a um dos fusos horários brasileiro, UTC -3 (Horário de Brasília).

Caso deseje trabalhar com um horário global, poderá fazer uso do:

data = DateTime.UtcNow;
System.Console.WriteLine(data);

//Saída esperada: 2/20/2024 11:00:00 AM

Isso é especialmente útil quando se trabalha em projetos de escopo internacional, evitando que informações erradas sejam armazenadas no sistema devido ao fuso horário e configurações de cultura do usuário.

Fusos horários e culturas no DateTime

O C# possui recursos para trabalharmos tanto com as diferenças de fusos horários (TimeZoneInfo) como também com as diferentes maneiras – aqui chamadas culturas –, como datas são exibidas ao longo do mundo (CultureInfo).

Contornar essas diferenças é bem simples, basta usarmos o namespace Globalization, da seguinte maneira:

using System;
using System.Globalization;

var cultura = CultureInfo.CreateSpecificCulture("pt-BR");
var data = DateTime.UtcNow;
var dataFormatada = data.ToString(cultura);

Console.WriteLine(data.ToString(cultura));

//Saída esperada: Data (DD/MM/YYYY) e hora (24H) no formato brasileiro

O que fizemos foi: armazenamos as configurações de cultura que desejamos ("pt-BR" no caso) em uma variável, para então passarmos essas informações como parâmetro do método ToString, formatando nossa data e hora da maneira desejada. Pode conferir a lista com todas as culturas existentes no C# na documentação oficial, aqui.

Outros recursos no DateTime

Abordamos, até então, como trabalhar com a data e hora atual do sistema, mas há muitos outros recursos à nossa disposição. Para explorarmos alguns deles, vamos antes atribuir valores ao nosso DateTime, usando seu construtor:

var data = new DateTime(2024, 12, 24, 20, 00, 00);

//Saída esperada: 12/24/2024 8:00:00 PM

E então, caso deseje saber em qual dia da semana essa data cairá, basta usar o:

var dia = data.DayOfWeek;
Console.WriteLine(dia);

//Saída esperada: Tuesday

Ou caso tenha dúvidas sobre quantos dias terão em um mês específico, usamos o:

var fevereiro2024 = DaysInMonth(2024, 2);

Console.WriteLine(fevereiro2024);

//Saída esperada: 29

Agora que já sabemos que a véspera de Natal cairá em uma Terça-feira e fomos lembrados que 2024 é um ano bissexto, saiba também que há diversos métodos adicionais para selecionar quaisquer detalhes sobre a data e hora em questão. Para ter acesso à lista completa com 42 métodos, confira aqui na documentação.

Operações com datas

Vimos a quantidade extensiva de recursos que o DateTime oferece para acessar as mais variadas informações sobre datas e horas, mas em projetos reais muitas das vezes temos não só que acessar essas informações, como também realizar cálculos com elas. No C# é bem simples, veja:

var data = new DateTime(2024, 01, 01, 08, 00, 00);
data.AddDays(51);

Console.WriteLine(data);

//Saída esperada: 2/20/2024 08:00:00 AM

E agora trazendo algo muito recorrente em aplicações reais, há diversos cenários onde devemos comparar datas distintas, e pequenos erros são fáceis de acontecer. Imagine o seguinte cenário: a sua tarefa, como desenvolvedor em um sistema de streaming, é implementar uma funcionalidade que mostra ao usuário quanto tempo restante de assinatura ele tem. Com o DateTime, isso não será nenhum problema:

var dataInicio = new DateTime(2024, 02, 01, 08, 00, 00)
var dataTermino = dataInicio.AddMonths(1);

var tempoRestante = dataTermino.Subtract(DateTime.Now);

Console.WriteLine($"O tempo restante da sua assinatura, iniciada em {dataInicio.ToString("dd/MM")}, é de {tempoRestante.Days} dias.");

//Saída esperada: O tempo restante da sua assinatura, iniciada em 01/02, é de 8 dias.

O método Subtract permite que essa subtração de datas aconteça de forma muito simplificada, basta passar a data que deseja subtrair como parâmetro. Para evitar qualquer tipo de imprecisão, o DateTime é sempre a melhor escolha.

Formatando datas

Por fim, como vimos no exemplo anterior, ao exibirmos datas para o usuário, é sempre de bom tom formatá-la para que fique adequado à situação. Para isso, conseguimos utilizar da interpolação de strings para tornar essa saída mais agradável e compreensiva, veja:

var data = new DateTime(2024, 02, 20, 08, 00, 00);

Console.WriteLine(data);

//Saída esperada: 2/20/2024 08:00:00 AM

var dataFormatada = String.Format("{0:dd/MM/yyyy}", data);

//Saída esperada: 20/02/2024

Basta então formatá-la para ficar ideal à sua necessidade, sempre pensando na experiência do usuário recebendo essa informação. Alguns exemplos:

var data = new DateTime(2024, 02, 20, 08, 00, 00);
var dataFormatada = new DateTime();

dataFormatada = String.Format("{0:dd/MM}", data);                                            // Formato: 24/02
dataFormatada = String.Format("{0:dd/MM/yyyy HH:mm}", data);                                 // Formato: 24/02/2024 08:00
dataFormatada = String.Format("{0:yyyy}-{1}", data, (data.Month <= 6) ? "1" : "2")           // Formato: 2024-1 (semestre)
dataFormatada = String.Format("{0:D}", data);                                                // Formato: Wednesday, February 20, 2024

Esses são alguns exemplos de formatação de data e hora padrão, onde utilizamos os caracteres padrões para ajustar conforme desejarmos. Para consultar todos os padrões de caracteres e formatação, deixo aqui a referência da documentação, mas em linhas gerais, trabalhamos com:

/*

"d", para dia
"M", para mês
"y", para ano
"H", para hora
"m", para minuto
"s", para segundo
"f", para fração de segundo
"z", para fuso horário

*/

Considerações Finais

Espero que esse artigo tenha o auxiliado a entender o DateTime, uma estrutura simples e tremendamente útil nos mais diversos tipos de aplicações no mundo real. O fator temporal existe e é ponto-chave em praticamente todas as regras de negócio que vemos no mercado de tecnologia, então é imprescindível a um desenvolvedor saber manusear datas e horários de forma prática, funcional e segura. Obrigado por chegar até aqui, e fico confiante de que isso acrescente algo em sua jornada, agora o encorajo a praticar e aplicar tudo isso em seus projetos, consolidando esse conhecimento como seu.

Até o próximo artigo!

Referências Bibliográficas

Estrutura DateTime – DateTime Struct (documentação oficial).

Estruturas – Structs (documentação oficial).

Tipos de valor x Tipos de referência – Types (documentação oficial).

Culturas – CultureInfo class (documentação oficial).

Formatação de Strings – String.Format Method (documentação oficial)