Fuso horário e EWS no Exchange

  • Artigo

Descubra como os fusos horários funcionam com a API Gerenciada do EWS e o EWS no Exchange.

Os fusos horários não são algo que a maioria das pessoas param para pensar. No entanto, eles são um conceito importante ao especificar datas e horas usando a API Gerenciada do EWS ou o EWS. O uso incorreto de fusos horários em uma API Gerenciada do EWS ou no aplicativo EWS pode gerar resultados inesperados. É fácil manusear corretamente fusos horários, desde que você saiba como.

Manuseio de fusos horários na API Gerenciada do EWS

Se você estiver usando a API Gerenciada do EWS, os fusos horários serão, na maioria das vezes, manuseados automaticamente para você. Sem qualquer ação explícita de sua parte, a API usa o fuso horário local do computador cliente e lida com todas as conversões necessárias nos bastidores. Isso é ótimo quando esse é o efeito desejado, mas há outras opções.

Uma opção é definir a propriedade ExchangeService.TimeZone. Essa propriedade controla o fuso horário de todas as solicitações executadas pela API Gerenciada do EWS. Essa propriedade é somente leitura; a única maneira de defini-la é por meio do construtor de classe. Se você usar o construtor ExchangeService(System.TimeZoneInfo) ou o ExchangeService(ExchangeVersion, System.TimeZoneInfo), poderá especificar um fuso horário específico como um objeto System.TimeZoneInfo. Se você usar um dos outros construtores que não usam um objeto TimeZoneInfo como parâmetro, a classe ExchangeService define a propriedade TimeZone como o fuso horário atual do computador cliente.

Se você definir um fuso horário específico ou deixá-lo como o fuso horário do computador cliente, todas as datas e horas serão expressas no fuso horário representado pela propriedade TimeZone. A API Gerenciada do EWS expõe todas as propriedades de data/hora como estruturas System.DateTime. Portanto, se você definir qualquer propriedade de data/hora, não se esqueça de que a hora especificada é interpretada de acordo com o valor da propriedade DateTime.Kind no objeto DateTime. Se o valor da propriedade Kind for definido como Não especificado, o valor de DateTime será interpretado como sendo no fuso horário especificado pela propriedade TimeZone. Se você estiver lendo propriedades de data/hora, todas as propriedades DateTime serão expressas nesse fuso horário.

Se você estiver criando novos compromissos ou reuniões ou atualizando compromissos ou reuniões existentes, você pode substituir o fuso horário especificado no TimeZone para novos objetos Appointment. No entanto, exatamente o que você pode substituir depende da versão do esquema EWS que você está direcionando. Para todos os valores da propriedade ExchangeService.RequestedServerVersion, você pode definir Appointment.StartTimeZone para usar um fuso horário específico para esse compromisso ou reunião. Se você estiver usando um valor para a propriedade ExchangeService.RequestedServerVersion maior que Exchange2007_SP1, também poderá definir a propriedade Appointment.EndTimeZone, permitindo que você especifique um fuso horário para a propriedade Appointment.End. No entanto, tenha em mente que essas propriedades afetam apenas a interpretação da data/hora da solicitação de criação. Se você recuperar o compromisso, os horários de início e término ainda serão expressos no fuso horário especificado pela propriedade TimeZone.

Se você estiver atualizando compromissos ou reuniões existentes, poderá alterar o fuso horário de um objeto Appointment definindo a propriedade StartTimeZone e/ou a propriedade EndTimeZone. Isso fará com que os horários aplicáveis mudem de acordo. Se você definiu o ExchangeService.RequestedServerVersion como Exchange2007_SP1, não será possível definir a propriedade EndTimeZone; o valor da propriedade StartTimeZone será usado em seu lugar.

Tabela 1. Propriedades de fuso horário na API Gerenciada do EWS

Propriedade de fuso horário Versão mínima da solicitação de servidor Descrição
TimeZone
Exchange2007_SP1
Se não for definida por meio do construtor da classe ExchangeService, essa propriedade será definida como o fuso horário do computador cliente. Todas as propriedades DateTime ao criar itens e ao recuperar itens existentes são expressas neste fuso horário. Esse fuso horário pode ser substituído na criação de solicitações para compromissos e reuniões definindo a propriedade Appointment.StartTimeZone e/ou a Appointment.EndTimeZone. Se não for substituído pela propriedade Appointment.StartTimeZone, esse fuso horário será considerado o fuso horário de criação para compromissos e reuniões.
StartTimeZone
Exchange2007_SP1
Se definido em novos objetos Appointment, esse fuso horário será usado para interpretar as propriedades Appointment.Start e Appointment.ReminderDueBy. Esse fuso horário também é considerado o fuso horário de criação do objeto Appointment.
Ao recuperar itens existentes, essa propriedade é apenas informacional. Os valores das propriedades DateTime no compromisso existente são sempre expressos no fuso horário especificado pela propriedade ExchangeService.TimeZone.
EndTimeZone
Exchange2010
Se definido em novos objetos Appointment, esse fuso horário será usado para interpretar a propriedade Appointment.End.
Ao recuperar itens existentes, essa propriedade é apenas informacional. Os valores das propriedades DateTime no compromisso existente são sempre expressos no fuso horário especificado pela propriedade ExchangeService.TimeZone.

Manipulação de fusos horário no EWS

Se você estiver usando o EWS, os fusos horários não serão tratados automaticamente e as coisas serão um pouco mais complicadas. Como os fusos horário impactam as solicitações e respostas do EWS dependem de vários fatores:

O fuso horário especificado no valor dos elementos dateTime pode ter três formulários. Você pode ler todos os detalhes na Parte 2 do Esquema XML: Datatypes Second Edition, mas para parafrasear:

  • Horário Coordenado Universal (UTC): especificado por “Z”. Por exemplo, 2014-06-06T19:00:00.000Z

  • Fuso horário específico: especificado por “+” ou “-” seguido por horas e minutos. Por exemplo, 2014-06-06T19:00:00.000-08:00

  • Sem fuso horário: especificado pela ausência de qualquer fuso horário. Por exemplo, 2014-06-06T19:00:00.000

Se um fuso horário estiver presente em um valor dateTime (UTC ou um fuso horário específico), esse valor será sempre interpretado como esse fuso horário. Se nenhum fuso horário estiver presente, a interpretação do valor dependerá da combinação específica dos outros elementos relacionados ao fuso horário.

Tabela 2. Elementos de fuso horário no EWS e seus efeitos

RequestServerVersion TimeZoneContext presente? MeetingTimeZone, StartTimeZone ou EndTimeZone presentes (somente CalendarItem e MeetingRequest)? dateTime em UTC dateTime em fuso horário específico dateTime sem fuso horário Fuso horário de criação de compromissos e reuniões
Exchange2007_SP1
Sim
 Sim ( MeetingTimeZone )
 Interpretado como UTC
 Interpretado como o fuso horário indicado no valor
 Os elementos dentro do elemento CalendarItem ou MeetingRequest que contém o elemento MeetingTimeZone são interpretados como o fuso horário no elemento MeetingTimeZone, todos os outros interpretados como UTC
 Fuso horário no elemento MeetingTimeZone
Exchange2007_SP1
Sim
 Não
 Interpretado como UTC
 Interpretado como o fuso horário indicado no valor
 Interpretado como UTC
 UTC
Exchange2007_SP1
Não
 Sim ( MeetingTimeZone )
 Interpretado como UTC
 Interpretado como o fuso horário indicado no valor
 Os elementos dentro do elemento CalendarItem ou MeetingRequest que contém o elemento MeetingTimeZone são interpretados como o fuso horário no elemento MeetingTimeZone, todos os outros interpretados como UTC
 Fuso horário no elemento MeetingTimeZone
Exchange2007_SP1
Não
 Não
 Interpretado como UTC
 Interpretado como o fuso horário indicado no valor
 Interpretado como UTC
 UTC
Exchange2010 e posterior
 Sim
 Sim (StartTimeZone e/ou EndTimeZone)
 Interpretado como UTC
 Interpretado como o fuso horário indicado no valor
 Se o elemento StartTimeZone estiver presente, o valor dos elementos Start e ReminderDueBy será interpretado como o fuso horário no elemento StartTimeZone. Caso contrário, o valor desses elementos será interpretado como o fuso horário no elemento TimeZoneContext.
Se o elemento EndTimeZone estiver presente, o valor do elemento Start será interpretado como o fuso horário no elemento EndTimeZone. Caso contrário, o valor do elemento End será interpretado como o fuso horário no elemento TimeZoneContext.
Elementos fora do CalendarItem ou MeetingRequest são interpretados como o fuso horário no elemento TimeZoneContext.
Fuso horário no elemento StartTimeZone, se presente, fuso horário no elemento TimeZoneContext, se não estiver
Exchange2010 e posterior
 Sim
 Não
 Interpretado como UTC
 Interpretado como o fuso horário indicado no valor
 Interpretado como o fuso horário no elemento TimeZoneContext
 Fuso horário no elemento TimeZoneContext
Exchange2010 e posterior
 Não
 Sim (StartTimeZone e/ou EndTimeZone)
 Interpretado como UTC
 Interpretado como o fuso horário indicado no valor
 Se o elemento StartTimeZone estiver presente, o valor dos elementos Start e ReminderDueBy será interpretado como o fuso horário no elemento StartTimeZone. Caso contrário, o valor desses elementos será interpretado como UTC.
Se o elemento EndTimeZone estiver presente, o valor do elemento Start será interpretado como o fuso horário no elemento EndTimeZone. Caso contrário, o valor do elemento End será interpretado como UTC.
Elementos fora do CalendarItem ou MeetingRequest são interpretados como UTC.
Fuso horário no elemento StartTimeZone, se presente, se não, UTC
Exchange2010 e posterior
 Não
 Não
 Interpretado como UTC
 Interpretado como o fuso horário indicado no valor
 Interpretado como UTC
 UTC

Ao interpretar respostas do servidor, você sempre deve verificar o valor de cada elemento e interpretar o valor de acordo. O Exchange sempre incluirá um fuso horário (UTC ou um fuso horário específico) no valor.

Considerações adicionais sobre fuso horário ao criar compromissos e reuniões

Quando você cria um compromisso ou uma reunião, o fuso horário que se aplica ao horário de início é considerado o fuso horário de criação do compromisso. Além de controlar como a data/hora é interpretada quando um compromisso ou reunião é criado, o fuso horário de criação tem os seguintes efeitos no item:

  • Se o item for um evento de dia inteiro, ele poderá ser exibido de forma inesperada se for exibido de um cliente que está usando um fuso horário diferente do fuso horário de criação. Isso ocorre porque, quando um evento de dia inteiro é criado, a hora de início e término de eventos de todos os dias é ajustada à meia-noite do fuso horário de criação. Esse tempo será exibido como uma hora diferente da meia-noite em um fuso horário diferente, portanto, o item pode parecer abranger dias extras. Por isso, recomendamos que você use o fuso horário configurado para o cliente de calendário principal do usuário para criar eventos de todo o dia quando possível.

  • Se o item for uma reunião, o fuso horário de criação será exibido na barra de informações Outlook sobre as solicitações de reunião recebidas pelos participantes, se esse fuso horário for diferente do fuso horário do cliente.

Nesta seção

Confira também