Начало работы с клиентскими приложениями, использующими управляемый API EWS

Статья
03/29/2023

Разработка простого почтового клиентского приложения Hello World для Exchange с помощью управляемого API EWS.

Управляемый API EWS предоставляет интуитивно понятную и простую в использовании объектную модель для отправки и получения сообщений веб-служб от клиентских приложений, приложений порталов и приложений-служб. Управляемый API EWS предоставляет вам доступ почти ко всем сведениям, хранящимся в Exchange Online, Exchange Online в составе Office 365 или почтовом ящике сервера Exchange. Вы можете использовать сведения из этой статьи при разработке своего первого клиентского приложения, использующего управляемый API EWS.

Примечание.

Мы удаляем возможность использования обычной проверки подлинности в Exchange Online для EWS с октября 2022 г.: Прекращение поддержки обычной проверки подлинности в Exchange Online. Вместо этого следует использовать проверку подлинности OAuth. Проверка подлинности приложения EWS с помощью OAuth

Примечание.

Управляемое API EWS теперь доступно в качестве проекта с открытым кодом на GitHub. Вы можете использовать библиотеку открытого кода, чтобы:

добавлять исправления ошибок и улучшения в API;
получать исправления ошибок и улучшения до того, как они станут доступны в официальном выпуске;
получать доступ к самой полной и актуальной реализации API, которую можно использовать для справки или для создания новых библиотек на новых платформах.

Мы будем рады вашему вкладу в GitHub.

Вам потребуется сервер Exchange Server

Если у вас уже есть учетная запись почтового ящика Exchange, вы можете пропустить этот раздел. В противном случае у вас есть следующие варианты настройки почтового ящика Exchange для вашего первого клиентского приложения EWS:

Заведите сайт разработчиков Office 365 (рекомендуется). Это самый быстрый способ настройки почтового ящика Exchange.
Скачайте Exchange Server.

Убедившись, что вы можете отправлять и получать сообщения из Exchange, вы будете готовы настроить среду разработки. Вы можете использовать веб-клиент Exchange Outlook Web App, чтобы убедиться, что вы можете отправлять сообщения.

Настройка среды разработки

Убедитесь, что у вас есть доступ к следующим ресурсам:

Любая версия Visual Studio, поддерживающая .NET Framework 4. Хотя на самом деле вам не требуется Visual Studio, ведь вы можете использовать любой компилятор C#, мы рекомендуем использовать его.
Управляемый API EWS. Вы можете использовать 64- или 32-разрядную версию в зависимости от вашей системы. Используйте для установки папку по умолчанию.

Создание первого приложения, использующего управляемый API EWS

В этом руководстве предполагается, что у вас настроен сайт разработчиков Office 365. Если вы скачали и установили Exchange, потребуется установить действительный сертификат на сервере Exchange или реализовать обратный вызов проверки сертификатов для самозаверяющего сертификата, предоставляемого по умолчанию. Обратите внимание, что эти действия могут слегка отличаться в зависимости от используемой версии Visual Studio.

Этап 1. Создание проекта в Visual Studio

В Visual Studio выберите в меню Файл пункт Создать, а затем — Проект. Откроется диалоговое окно Новый проект.
Создайте Консольное приложение C#. В панели Шаблоны выберите Visual C#, а затем — Консольное приложение.
Назовите проект HelloWorld, а затем нажмите кнопку ОК.

Visual Studio создаст проект и откроет окно документа с кодом Program.cs.

Этап 2. Добавление ссылки на управляемый API EWS

Если окно обозревателя решений уже открыто, пропустите этот этап и переходите к этапу 2. Чтобы открыть обозреватель решений, в меню Вид выберите пункт Обозреватель решений.
В обозревателе решений выберите проект HelloWorld, откройте контекстное меню (правая кнопка мыши) раздела Ссылки и выберите команду Добавить ссылку. Откроется диалоговое окно управления ссылками проекта.
Выберите команду Обзор. Перейдите в папку, где установлена DLL-библиотека управляемого API EWS. По умолчанию установщик задает следующий путь: C:\Program Files\Microsoft\Exchange\Web Services<version>. Путь может зависеть от того, скачали вы 32- или 64-разрядную версию файла Microsoft.Exchange.WebServices.dll. Выберите Microsoft.Exchange.WebServices.dll и нажмите кнопку ОК или Добавить. В проект будет добавлена ссылка на управляемый API EWS.
Если вы используете Управляемый API EWS 2.0, измените проект HelloWorld, чтобы он ссылался на .NET Framework 4. Другие версии управляемого API EWS могут использовать другую целевую версию .NET Framework.
Убедитесь, что вы используете правильную целевую версию .NET Framework. Откройте контекстное меню (правая кнопка мыши) проекта HelloWorld в обозревателе решений и выберите пункт Свойства. Убедитесь, что в раскрывающемся списке Целевая рабочая среда выбран пункт .NET Framework 4.

Теперь, когда у вас есть настройка проекта и вы создали ссылку на управляемое API EWS, то вы готовы создать свое первое приложение. Для простоты работы добавьте код в файл Program.cs. Ознакомьтесь со статьей Ссылка на сборку управляемого API EWS для получения дополнительной информации о ссылках на управляемое API EWS. На следующем этапе вы разработаете базовый код для создания большинства клиентских приложений управляемого API EWS.]

Этап 3. Настройка проверки перенаправления URL-адресов для автообнаружения

Добавьте приведенный ниже метод обратного вызова для проверки перенаправления после метода Main(string[] args). Он проверяет, представляют ли перенаправленные URL-адреса, возвращенные функцией автообнаружения, конечную точку HTTPS.

private static bool RedirectionUrlValidationCallback(string redirectionUrl)
{
   // The default for the validation callback is to reject the URL.
   bool result = false;
   Uri redirectionUri = new Uri(redirectionUrl);
   // Validate the contents of the redirection URL. In this simple validation
   // callback, the redirection URL is considered valid if it is using HTTPS
   // to encrypt the authentication credentials. 
   if (redirectionUri.Scheme == "https")
   {
      result = true;
   }
   return result;
}

Этот проверяющий метод обратного вызова будет передан объекту ExchangeService на этапе 4. Это необходимо, чтобы ваше приложение доверяло и следовало перенаправлению функции автообнаружения результат перенаправления функции автообнаружения предоставляет конечную точку EWS для вашего приложения.

Этап 4. Подготовка объекта ExchangeService

Добавьте ссылку на директиву using в управляемый API EWS. Добавьте следующий код после директивы using в начале файла Program.cs.
```
 using Microsoft.Exchange.WebServices.Data;
```
В методе Main создайте экземпляр объекта ExchangeService в нужной версией службы. В этом примере используется самая ранняя версия схемы EWS.
```
 ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2007_SP1);
```
Если вы ссылаетесь на локальный сервер Exchange и ваш клиент присоединен к домену, переходите к этапу 4. Если ваш клиент ссылается на почтовый ящик Exchange Online или сайта разработчиков Office 365, необходимо передавать учетные данные в явной форме. Добавьте следующий код после создания экземпляра объекта ExchangeService и задайте данные учетной записи почтового ящика. Имя пользователя должно быть именем участника-пользователя. Переходите к этапу 5.
```
 service.Credentials = new WebCredentials("user1@contoso.com", "password");
```
Присоединенные к доменам клиенты, которые ссылаются на локальный сервер Exchange, могут использовать заданные по умолчанию учетные данные пользователя, выполнившего вход, при условии, что учетные данные связаны с почтовым ящиком. Добавьте следующий код после создания экземпляра объекта ExchangeService.
```
 service.UseDefaultCredentials = true;
```
Если ваш клиент ссылается на почтовый ящик Exchange Online или сайта разработчиков Office 365, убедитесь, что для параметра UseDefaultCredentials задано значение false, установленное по умолчанию. Ваш клиент готов совершить первый вызов службы автообнаружения, чтобы получить URL-адрес службы для вызовов службы EWS.
Метод AutodiscoverUrl объекта ExchangeService совершает серию вызовов службы автообнаружения, чтобы получить URL-адрес службы. Если вызов этого метода совершен успешно, для свойства URL объекта ExchangeService будет задано значение URL-адреса службы. Передайте адрес электронной почты пользователя и RedirectionUrlValidationCallback методу AutodiscoverUrl. Добавьте приведенный ниже код после указания учетных данных на этапе 3 или 4. Измените user1@contoso.com адрес электронной почты, чтобы служба автообнаружения обнаружила конечную точку EWS.
```
 service.AutodiscoverUrl("user1@contoso.com", RedirectionUrlValidationCallback);
```

На этом этапе ваш клиент настроен для вызовов EWS для доступа к данным почтового ящика. Если вы сейчас запустите свой код, то сможете проверить, что метод вызова AutodiscoverUrl отработал, проверив содержимое свойства ExchangeService.Url. Если это свойство содержит URL-адрес, то ваш вызов был удачным! Это означает, что приложение успешно прошло проверку подлинности в службе и обнаружило конечную точку EWS для почтового ящика. Теперь вы готовы выполнить первый вызов EWS. Ознакомьтесь со статьей Настройка URL-адреса службы EWS с помощью управляемого API EWS для получения дополнительной информации о настройке URL-адреса EWS.

Этап 6. Создание первого сообщения электронной почты Hello World

После вызова метода AutodiscoverUrl создайте новый экземпляр объекта EmailMessage и передайте созданный ранее объект службы.
```
 EmailMessage email = new EmailMessage(service);
```
Теперь у вас есть сообщение электронной почты, в котором задана привязка к службе. Вызовы, совершенные из объекта EmailMessage, будут адресованы службе.
Теперь задайте получателя сообщения. Для этого измените user1@contoso.com значение, чтобы использовать SMTP-адрес.
```
 email.ToRecipients.Add("user1@contoso.com");
```

Задайте тему и основной текст сообщения.

 email.Subject = "HelloWorld";
 email.Body = new MessageBody("This is the first email I've sent by using the EWS Managed API.");

Теперь вы готовы отправить первое сообщение электронной почты с помощью службы управляемого API EWS. Метод Send вызовет службу и отправит сообщение электронной почты для доставки. Ознакомьтесь со статьей Взаимодействие с EWS с помощью управляемого API EWS для получения дополнительной информации о других методах, которые можно использовать для взаимодействия с Exchange.
```
 email.Send();
```
Вы готовы запустить свое приложение Hello World. В Visual Studio нажмите клавишу F5. Откроется пустое окно консоли. В окно консоли не будет появляться никакого текста, пока приложение проходит проверку подлинности, следует перенаправлению службы автообнаружения, а затем совершает первый вызов для создания сообщения электронной почты, которое вы отправляете себе. Если вы хотите увидеть совершаемые вызовы, добавьте две приведенные ниже строки кода перед вызовом метода AutodiscoverUrl. Затем нажмите клавишу F5. Запросы и ответы EWS будут трассированы в окне консоли.
```
 service.TraceEnabled = true;
 service.TraceFlags = TraceFlags.All;
```

Теперь у вас есть работоспособное приложение, использующее управляемый API EWS. Для вашего удобства в следующем примере показан весь код, добавленный в файл Program.cs для создания приложения Hello World.

using System;
using Microsoft.Exchange.WebServices.Data;
namespace HelloWorld
{
  class Program
  {
    static void Main(string[] args)
    {
      ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2007_SP1);
      service.Credentials = new WebCredentials("user1@contoso.com", "password");
      service.TraceEnabled = true;
      service.TraceFlags = TraceFlags.All;
      service.AutodiscoverUrl("user1@contoso.com", RedirectionUrlValidationCallback);
      EmailMessage email = new EmailMessage(service);
      email.ToRecipients.Add("user1@contoso.com");
      email.Subject = "HelloWorld";
      email.Body = new MessageBody("This is the first email I've sent by using the EWS Managed API");
      email.Send();
    }
    private static bool RedirectionUrlValidationCallback(string redirectionUrl)
    {
      // The default for the validation callback is to reject the URL.
      bool result = false;
      Uri redirectionUri = new Uri(redirectionUrl);
      // Validate the contents of the redirection URL. In this simple validation
      // callback, the redirection URL is considered valid if it is using HTTPS
      // to encrypt the authentication credentials. 
      if (redirectionUri.Scheme == "https")
      {
        result = true;
      }
      return result;
    }
  }
}

Дальнейшие действия

Если вы готовы усовершенствовать свое первое клиентское приложение с использованием управляемого API EWS, изучите следующие ресурсы:

Если с приложением возникли проблемы, попробуйте опубликовать вопрос или комментарий на форуме (и не забудьте прочитать первое сообщение).