Datas, horários e fusos horários

O .NET fornece tipos que representam datas, horários e fusos horários. Este artigo descreve esses tipos.

Além da estrutura de DateTime básica, o .NET fornece as seguintes classes que dão suporte ao trabalho com fusos horários:

• TimeZoneInfo

  Use essa classe para trabalhar com qualquer fuso horário predefinido em um sistema, criar novos fusos horários e converter facilmente datas e horas de um fuso horário para outro. Para um novo desenvolvimento, use a classe TimeZoneInfo em vez da classe TimeZone.

• DateTimeOffset

  Use essa estrutura para trabalhar com datas e horas cujo deslocamento (ou diferença) em relação ao horário UTC é conhecido. A estrutura DateTimeOffset combina um valor de data e hora com o deslocamento desse horário em relação ao UTC. Devido à sua relação com UTC, um valor de data e hora individual identifica de forma inequívoca um único ponto no tempo. Isso torna um valor DateTimeOffset mais portátil de um computador para outro do que um valor DateTime.

As seguintes classes são necessárias para dar suporte ao trabalho com o tempo:

• TimeSpan

  Use essa estrutura para representar um intervalo de tempo, como um período decorrido ou a diferença entre duas datas.

• TimeOnly

  Use essa estrutura para representar uma hora sem uma data. O tempo representa as horas, os minutos e os segundos de um dia não específico. TimeOnly tem um intervalo de 00:00:00.0000000 a 23:59:59.9999999. Esse tipo pode ser usado para substituir tipos de DateTime e TimeSpan em seu código quando você usou esses tipos para representar um tempo. Para obter mais informações, consulte Como usar as estruturas DateOnly e TimeOnly.

  Importante

  TimeOnly não está disponível para o .NET Framework.

• TimeProvider

  Essa é uma classe base que fornece uma abstração do tempo. Uma maneira comum de verificar a hora atual é usando DateTime.UtcNow ou DateTimeOffset.UtcNow. No entanto, esses tipos não fornecem nenhum controle sobre o que é considerado "agora". Por que você iria querer controlar isso? Testabilidade. Por exemplo, considere que você está escrevendo um aplicativo de acompanhamento de eventos que fornece lembretes um dia antes do evento. A lógica do aplicativo é verificar a hora do evento a cada hora e alertar o usuário quando ele estiver 24 horas antes do evento. Ao escrever seus testes para o aplicativo, você fornecerá seu próprio tipo que encapsula DateTimeOffset.UtcNow para testar essa lógica, mas agora o .NET fornece essa classe de abstração para você.

  Para obter mais informações, consulte O que é TimeProvider.

  O tipo TimeProvider está incluído no .NET.

  Para .NET Framework e .NET Standard, TimeProvider é fornecido pelo pacote NuGet Microsoft.Bcl.TimeProvider.

"As seguintes classes são para dar suporte ao trabalho com datas:"

• DateOnly

  Use essa estrutura ao trabalhar com um valor que representa apenas uma data. A data representa o dia inteiro, desde o início do dia até o final. DateOnly tem um intervalo de 0001-01-01 até 9999-12-31. E esse tipo representa a combinação mês, dia e ano sem uma hora específica. Se você usou anteriormente um tipo de DateTime em seu código para representar uma data que desconsiderasse a hora, use esse tipo em seu lugar. Para obter mais informações, consulte Como usar as estruturas DateOnly e TimeOnly.

  Importante

  DateOnly não está disponível para o .NET Framework.

A próxima seção fornece as informações de que você precisa trabalhar com fusos horários e criar aplicativos com reconhecimento de fuso horário que possam converter datas e horas de um fuso horário para outro.

Nesta seção

visão geral do fuso horário
Discute a terminologia, os conceitos e os problemas envolvidos na criação de aplicativos com reconhecimento de fuso horário.

Escolhendo entre DateTime, DateTimeOffset, TimeSpan e TimeZoneInfo
Discute quando usar os tipos DateTime, DateTimeOffsete TimeZoneInfo ao trabalhar com dados de data e hora.

Localizar os fusos horários definidos em um sistema local
Descreve como enumerar os fusos horários encontrados em um sistema local.

Como enumerar fusos horários presentes em um computador
Fornece exemplos que enumeram os fusos horários definidos no registro de um computador e que permitem que os usuários selecionem um fuso horário predefinido em uma lista.

Como acessar os objetos de fuso horário local e UTC predefinidos
Descreve como acessar o Tempo Universal Coordenado e o fuso horário local.

Como criar uma instância de um objeto TimeZoneInfo
Descreve como instanciar um objeto TimeZoneInfo do registro do sistema local.

instanciando um objeto DateTimeOffset
Discute as maneiras pelas quais um objeto DateTimeOffset pode ser instanciado e as maneiras pelas quais um valor DateTime pode ser convertido em um valor DateTimeOffset.

Como criar fusos horários sem regras de ajuste
Descreve como criar um fuso horário personalizado que não dá suporte à transição de e para o horário de verão.

Como criar fusos horários com regras de ajuste
Descreve como criar um fuso horário personalizado que dá suporte a uma ou mais transições de e para o horário de verão.

salvando e restaurando fusos horários
Detalha o suporte para serialização e desserialização de dados de fuso horário no TimeZoneInfo e ilustra alguns dos cenários em que esses recursos podem ser utilizados.

Como salvar fusos horários em um recurso inserido
Descreve como criar um fuso horário personalizado e salvar suas informações em um arquivo de recurso.

Como restaurar fusos horários de um recurso inserido
Descreve como instanciar fusos horários personalizados que foram salvos em um arquivo de recurso inserido.

Realizando operações aritméticas com datas e horários
Discute os problemas envolvidos na adição, subtração e comparação de valores DateTime e DateTimeOffset.

Como: Usar fusos horários nos cálculos de data e hora
Discute como executar a aritmética de data e hora que reflete as regras de ajuste de um fuso horário.

Convertendo entre DateTime e DateTimeOffset
Descreve como converter entre valores DateTime e DateTimeOffset.

Convertendo horários entre fusos horários
Descreve como converter horários de um fuso horário para outro.

Como resolver tempos ambíguos
Descreve como resolver um horário ambíguo mapeando-o para o horário padrão do fuso horário.

Como: permitir que os usuários resolvam tempos ambíguos
Descreve como permitir que um usuário determine o mapeamento entre uma hora local ambígua e o Tempo Universal Coordenado.

Referência

System.TimeZoneInfo