Часовые пояса и EWS в Exchange
Узнайте, как часовые пояса работают с управляемым API EWS и EWS в Exchange.
Часовые пояса — это не то, о чем большинство людей задумываются. Однако они важны при указании даты и времени с помощью управляемого API EWS или EWS. Неправильная обработка часовых поясов в управляемом API EWS или приложении EWS может привести к неожиданным результатам. Правильно управлять часовыми поясами легко, если вы знаете, как это сделать.
Обработка часовых поясов в управляемом API EWS
Если вы используете управляемый API EWS, часовые пояса по большей части обрабатываются автоматически. Без каких-либо явных действий с вашей стороны API использует локальный часовой пояс клиентского компьютера и выполняет все необходимые преобразования за кадром. Это отлично, когда это то, что вам нужно, но у вас есть другие варианты.
Одним из вариантов является настройка свойства ExchangeService.TimeZone. Это свойство управляет часовым поясом для всех запросов, выполняемых управляемым API EWS. Это свойство доступно только для чтения; единственный способ установить его — с помощью конструктора класса. Если вы используете конструктор ExchangeService(System.TimeZoneInfo) или конструктор ExchangeService(ExchangeVersion, System.TimeZoneInfo), можно указать определенный часовой пояс в качестве объекта System.TimeZoneInfo. Если вы используете один из других конструкторов, которые не принимают объект TimeZoneInfo в качестве параметра, класс ExchangeService задает для свойства TimeZoneтекущий часовой пояс клиентского компьютера.
Независимо от того, задаете ли вы конкретный часовой пояс или оставляете его в качестве часового пояса клиентского компьютера, все даты и время выражаются в часовом поясе, представленном свойством TimeZone. Управляемый API EWS предоставляет все свойства даты и времени в виде структур System.DateTime. Поэтому, если вы задаете какие-либо свойства даты и времени, имейте в виду, что указанное вами время интерпретируется в соответствии со значением свойства DateTime.Kind объекта DateTime. Если для свойства Kind установлено значение Unspecified, значение DateTime интерпретируется как находящееся в часовом поясе, указанном свойством TimeZone. Если вы читаете свойства даты и времени, все свойства DateTime выражены в этом часовом поясе.
Если вы создаете новые встречи или собрания или обновляете существующие встречи или собрания, у вас есть возможность переопределить часовой пояс, указанный в свойстве TimeZone для новых объектов Appointment. Однако точное переопределение зависит от целевой версии схемы EWS. Для всех значений свойства ExchangeService.RequestedServerVersion можно задать Appointment.StartTimeZone для использования определенного часового пояса для этой встречи или собрания. Если вы используете значение свойства ExchangeService.RequestedServerVersion больше, чем Exchange2007_SP1, вы также можете задать свойство Appointment.EndTimeZone, что позволит указать часовой пояс для свойства Appointment.End. Однако имейте в виду, что эти свойства влияют только на интерпретацию даты и времени запроса на создание. Если вы извлекаете встречу, время начала и окончания по-прежнему будет выражаться в часовом поясе, указанном свойством TimeZone.
Если вы обновляете существующие встречи или собрания, вы можете изменить часовой пояс для объекта Appointment, задав свойство StartTimeZone и/или свойствоEndTimeZone. Это приведет к соответствующему сдвигу применимого времени. Если вы установили для ExchangeService.RequestedServerVersion значение Exchange2007_SP1, вы не можете задать свойство EndTimeZone; вместо него будет использоваться значение свойства StartTimeZone.
Таблица 1. Свойства часового пояса в управляемом API EWS
| Свойство часового пояса | Минимальная версия запроса сервера | Описание |
|---|---|---|
| TimeZone |
Exchange2007_SP1 |
Если это свойство не задано с помощью конструктора для класса ExchangeService, для этого свойства устанавливается часовой пояс клиентского компьютера. Все свойства DateTime при создании элементов и при извлечении существующих элементов выражаются в этом часовом поясе. Этот часовой пояс может быть переопределен при создании запросов на встречи и собрания, задав свойство Appointment.StartTimeZone и/или свойство Appointment.EndTimeZone. Если он не переопределен свойством Appointment.StartTimeZone, этот часовой пояс считается часовым поясом создания для встреч и собраний. |
| StartTimeZone |
Exchange2007_SP1 |
Если он задан для новых объектов Appointment, этот часовой пояс используется для интерпретации свойств Appointment.Start и Appointment.ReminderDueBy. Этот часовой пояс также считается часовым поясом создания объекта Appointment. При извлечении существующих элементов это свойство носит только информационный характер. Значения свойств DateTime для существующей встречи всегда выражаются в часовом поясе, указанном свойством ExchangeService.TimeZone. |
| EndTimeZone |
Exchange2010 |
Если он установлен для новых объектов Appointment, этот часовой пояс используется для интерпретации свойства Appointment.End. При извлечении существующих элементов это свойство носит только информационный характер. Значения свойств DateTime для существующей встречи всегда выражаются в часовом поясе, указанном свойством ExchangeService.TimeZone. |
Обработка часовых поясов в EWS
Если вы используете EWS, часовые пояса не обрабатываются автоматически. Все немного сложнее. Влияние часовых поясов на запросы и ответы EWS зависит от ряда факторов.
Версия Exchange, указанная в элементе RequestServerVersion
Часовой пояс, указанный в элементе TimeZoneContext (если он присутствует)
Часовой пояс, указанный в элементах MeetingTimeZone, StartTimeZone или EndTimeZone (если присутствует на встречах или собраниях).
Часовой пояс, указанный в элементах XML dateTime (если присутствует)
Часовой пояс, указанный в значении элементов dateTime, может принимать три формы. Все сведения можно прочитать в статье Схема XML, часть 2: типы данных, второе издание, но перефразировав:
Всемирное координированное время (время в формате UTC): указывается буквой «Z». Пример:
2014-06-06T19:00:00.000ZКонкретный часовой пояс: указывается знаком «+» или «-», за которым следуют часы и минуты. Пример:
2014-06-06T19:00:00.000-08:00Без часового пояса: указывается отсутствием какого-либо часового пояса. Пример:
2014-06-06T19:00:00.000
Если часовой пояс присутствует в значении dateTime (либо в формате UTC, либо в определенном часовом поясе), это значение всегда интерпретируется как этот часовой пояс. Если часовой пояс отсутствует, то интерпретация значения зависит от конкретной комбинации других элементов, связанных с часовым поясом.
Табл. 2. Элементы часовых поясов в EWS и их эффекты
| RequestServerVersion | TimeZoneContext присутствует? | Присутствуют ли MeetingTimeZone, StartTimeZone или EndTimeZone (только CalendarItem и MeetingRequest)? | Дата и время в формате UTC | Дата и время в определенном часовом поясе | Дата и время без часовой пояса | Часовой пояс назначения и создания собраний |
|---|---|---|---|---|---|---|
| Exchange2007_SP1 |
Да |
Да ( MeetingTimeZone ) |
Интерпретируется как время в формате UTC |
Интерпретируется как часовой пояс, указанный в значении |
Элементы внутри элемента CalendarItem или MeetingRequest, содержащие элемент MeetingTimeZone, интерпретируются как часовой пояс в элементе MeetingTimeZone, а все остальные интерпретируются как время в формате UTC |
Часовой пояс в элементе MeetingTimeZone |
| Exchange2007_SP1 |
Да |
Нет |
Интерпретируется как время в формате UTC |
Интерпретируется как часовой пояс, указанный в значении |
Интерпретируется как время в формате UTC |
UTC |
| Exchange2007_SP1 |
Нет |
Да ( MeetingTimeZone ) |
Интерпретируется как время в формате UTC |
Интерпретируется как часовой пояс, указанный в значении |
Элементы внутри элемента CalendarItem или MeetingRequest, содержащие элемент MeetingTimeZone, интерпретируются как часовой пояс в элементе MeetingTimeZone, а все остальные интерпретируются как время в формате UTC |
Часовой пояс в элементе MeetingTimeZone |
| Exchange2007_SP1 |
Нет |
Нет |
Интерпретируется как время в формате UTC |
Интерпретируется как часовой пояс, указанный в значении |
Интерпретируется как время в формате UTC |
UTC |
| Exchange2010 и более поздняя версия |
Да |
Да ( StartTimeZone и/или EndTimeZone ) |
Интерпретируется как время в формате UTC |
Интерпретируется как часовой пояс, указанный в значении |
Если присутствует элемент StartTimeZone, значение элементов Start и ReminderDueBy интерпретируется как часовой пояс в элементе StartTimeZone. В противном случае значение этих элементов интерпретируется как часовой пояс в элементе TimeZoneContext. Если присутствует элемент EndTimeZone, значение элемента Start интерпретируется как часовой пояс в элементе EndTimeZone. В противном случае значение элемента End интерпретируется как часовой пояс в элементе TimeZoneContext. Элементы за пределами CalendarItem или MeetingRequest интерпретируются как часовой пояс в элементе TimeZoneContext. |
Часовой пояс в элементе StartTimeZoneесли он присутствует, часовой пояс в элементе TimeZoneContext, если нет |
| Exchange2010 и более поздняя версия |
Да |
Нет |
Интерпретируется как время в формате UTC |
Интерпретируется как часовой пояс, указанный в значении |
Интерпретируется как часовой пояс в элементе TimeZoneContext |
Часовой пояс в элементе TimeZoneContext |
| Exchange2010 и более поздняя версия |
Нет |
Да ( StartTimeZone и/или EndTimeZone ) |
Интерпретируется как время в формате UTC |
Интерпретируется как часовой пояс, указанный в значении |
Если присутствует элемент StartTimeZone, значение элементов Start и ReminderDueBy интерпретируется как часовой пояс в элементе StartTimeZone. В противном случае значение этих элементов интерпретируется как время в формате UTC. Если присутствует элемент EndTimeZone, значение элемента Start интерпретируется как часовой пояс в элементе EndTimeZone. В противном случае значение элемента End интерпретируется как время в формате UTC. Элементы за пределами CalendarItem или MeetingRequest интерпретируются как время в формате UTC. |
Часовой пояс в элементе StartTimeZone, если он присутствует, время в формате UTC, если нет |
| Exchange2010 и более поздняя версия |
Нет |
Нет |
Интерпретируется как время в формате UTC |
Интерпретируется как часовой пояс, указанный в значении |
Интерпретируется как время в формате UTC |
UTC |
При интерпретации ответов сервера всегда необходимо проверять значение каждого элемента и соответствующим образом интерпретировать значение. Exchange всегда будет включать часовой пояс (либо время в формате UTC, либо определенный часовой пояс) в значение.
Дополнительные сведения о часовом поясе при создании встреч и собраний
При создании встречи или собрания часовой пояс, который применяется ко времени начала, считается часовым поясом создания встречи. Помимо управления интерпретацией даты и времени при создании встречи или собрания, часовой пояс создания оказывает на элемент следующие эффекты:
Если элемент является событием на весь день, он может отображаться неожиданным образом при просмотре с клиента, использующего часовой пояс, отличный от часового пояса создания. Это связано с тем, что при создании события на весь день время начала и окончания события на весь день корректируется до полуночи часового пояса создания. Это время будет отображаться как время, отличное от полуночи, в другом часовом поясе, поэтому может показаться, что элемент охватывает дополнительные дни. По этой причине рекомендуется использовать часовой пояс, настроенный для основного клиента календаря пользователя, чтобы по возможности создавать события на весь день.
Если элементом является собрание, часовой пояс создания будет отображаться на информационной панели Outlook в приглашениях на собрание, полученных участниками, если этот часовой пояс отличается от часового пояса их клиента.