Асинхронные операции с электронной почтой с OAuth аутентификацией и клиентом EWS

Асинхронный метод получения OAuth токена

В отличие от синхронных методов, асинхронные методы не блокируют поток и позволяют выполнять несколько запросов одновременно. Асинхронные методы имеют суффикс Async.

ПРИМЕЧАНИЕ: Асинхронные методы доступны в версиях, нацеленных на .NET Core, .NET Framework 4.5 и новее.

Следующий пример кода определяет SomeAsyncTokenProvider класс, который реализует IAsyncTokenProvider интерфейс. Класс реализует GetAccessTokenAsync асинхронный метод, который возвращает Task типа OAuthToken. Этот метод получает действительный OAuthToken асинхронно.

private class SomeAsyncTokenProvider : IAsyncTokenProvider
{
    public SomeAsyncTokenProvider( /*some parameters*/)
    {
        ...
    }

    public async Task<OAuthToken> GetAccessTokenAsync(bool ignoreExistingToken = false,
        CancellationToken cancellationToken = default)
    {
        //Some asynchronous code to get a valid OAuthToken
        ...
    }

    public void Dispose()
    {
        ...
    }
}

Настройка асинхронного клиента EWS с OAuth-аутентификацией

Следующий пример кода получает клиент Exchange Web Services (EWS) асинхронно с использованием OAuth-аутентификации. Код выполняет следующие шаги:

1. Создаёт новый CancellationToken объект, который может использоваться для отмены асинхронных операций.
2. Создаёт экземпляр SomeAsyncTokenProvider класс, реализующий IAsyncTokenProvider интерфейс. Этот класс используется в качестве параметра для создания нового OAuthNetworkCredential объекта.
3. Устанавливает URI почтового ящика в конечную точку Exchange Web Services.
4. Вызывает GetEwsClientAsync метод EWSClient класс с mailboxUri и OAuthNetworkCredential объект в качестве параметров. Этот метод возвращает объект Task, поэтому он ожидает результат перед продолжением. Метод cancellationToken объект передаётся в качестве необязательного параметра к GetEwsClientAsync метод.

//The cancellationToken can be used
var cancellationToken = new CancellationToken();

//Create IAsyncEwsClientInstance
IAsyncTokenProvider tokenProvider = new SomeAsyncTokenProvider(/*some parameters*/);
const string mailboxUri = "https://outlook.office365.com/ews/exchange.asmx";
var ewsClient = await EWSClient.GetEwsClientAsync(mailboxUri, new OAuthNetworkCredential(tokenProvider),
    cancellationToken: cancellationToken);

Отправка электронных сообщений

Пример кода ниже пытается отправить электронное письмо асинхронно. Код выполняет следующие шаги:

1. Создаёт новый MailMessage объект с параметрами сообщения.
2. Вызывает SendAsync метод EWSClient объект, передающий MailMessage в качестве параметра. Метод ожидается, так как возвращает объект Task. cancellationToken объект передаётся в качестве необязательного параметра к SendAsync метод.

MailMessage message = new MailMessage("[e-mail]", "[e-mail]", "Some subject", "Some body");
await ewsClient.SendAsync(message, cancellationToken: cancellationToken);

Получить сообщения электронной почты

Чтобы асинхронно получить сообщение электронной почты, используйте следующий пример кода с описанными ниже шагами:

1. Вызвать FetchItemAsync метод объекта EWSclient. Метод принимает два параметра:

   • messageUri строка, представляющая URI сообщения для получения
   • cancellationToken является необязательным параметром, который может использоваться для отмены асинхронной операции. Метод возвращает объект Task, который разрешается в MapiMessage объекту, когда асинхронная операция завершена. Ключевое слово "await" используется для ожидания завершения объекта Task перед продолжением.

2. Назначьте fetched переменной присваивается результат завершённого Task, который является MapiMessage объект, содержащий полученные данные сообщения.

      var fetched = await ewsClient.FetchItemAsync(messageUri, cancellationToken: cancellationToken);
   

Добавить сообщения электронной почты

Пример кода ниже пытается добавить сообщения электронной почты асинхронно. Код выполняет следующие шаги:

1. Вызывает AppendMessagesAsync метод EWSclient объект. Метод принимает EwsAppendMessage объект, содержащий параметры: сообщения для добавления, URI целевой папки и токен отмены.

2. Создаёт EwsAppendMessage объект, используя Create метод и настраивает его с помощью следующих вызовов методов:

   • AddMessage добавляет сообщение к операции добавления.
   • SetFolder устанавливает URI целевой папки для операции добавления.
   • SetCancellationToken устанавливает токен отмены, который может быть использован для отмены асинхронной операции.

3. Этот AppendMessagesAsync Метод возвращает объект Task, который разрешается в объект IEnumerable, когда асинхронная операция завершена. Ключевое слово "await" используется для ожидания завершения объекта Task перед продолжением.

4. Этот uris переменной присваивается результат завершённого Task, который представляет собой объект IEnumerable, содержащий URI добавленных сообщений.

IEnumerable<string> uris = await ewsClient.AppendMessagesAsync(
    EwsAppendMessage.Create()
        .AddMessage(message)
        .AddMessage(fetched)
        .SetFolder(folderUri)
        .SetCancellationToken(cancellationToken));

Копировать элементы

Ниже приведён пример кода, показывающий, как копировать элементы, и выполняющий следующие шаги:

1. Вызывает CopyItemAsync метод EWSClient объект. Метод принимает три параметра:

   • messageUri строка, представляющая URI сообщения для копирования
   • destinationFolderUri строка, представляющая URI папки назначения
   • cancellationToken является необязательным параметром, который может использоваться для отмены асинхронной операции.

   Метод возвращает объект Task, который разрешается в строку, когда асинхронная операция завершена. Ключевое слово "await" используется для ожидания завершения объекта Task перед продолжением.

2. newItemUri переменной присваивается результат завершённого Task, который представляет собой строку, содержащую URI только что созданной копии сообщения.

string newItemUri = await ewsClient.CopyItemAsync(messageUri, destinationFolderUri, cancellationToken);

Удалить элементы

Следующий код пытается удалить сообщение электронной почты асинхронно.

Он вызывает DeleteItemAsync метод объекта EWSClient. Метод принимает три параметра:

• newItemUri строка, представляющая URI элемента для удаления
• DeletionOptions.DeletePermanently указывает, что элемент должен быть удалён навсегда
• cancellationToken является необязательным параметром, который может использоваться для отмены асинхронной операции.

Метод возвращает объект Task, который завершается, когда асинхронная операция завершена. Ключевое слово "await" используется для ожидания завершения объекта Task перед продолжением.

await ewsClient.DeleteItemAsync(newItemUri, DeletionOptions.DeletePermanently, cancellationToken);

Удалить папки

Следующий код пытается удалить папку асинхронно.

Он вызывает DeleteFolderAsync метод объекта EWSClient. Метод принимает три параметра:

• folderUri строка, представляющая URI папки для удаления
• deletePermanently указывает, удалять папку навсегда или перемещать её в папку "Удалённые элементы"
• cancellationToken является необязательным параметром, который может использоваться для отмены асинхронной операции.

Метод возвращает объект Task, который завершается, когда асинхронная операция завершена. Ключевое слово "await" используется для ожидания завершения объекта Task перед продолжением.

const bool deletePermanently = true;
await ewsClient.DeleteFolderAsync(folderUri, deletePermanently, cancellationToken);

Обновить элементы

Пример кода ниже пытается обновить элемент асинхронно. Он выполняет следующие шаги:

1. Создаёт EwsUpdateItem объект, используя Create метод, передающий объект элемента. EwsUpdateItem представляет параметры операции обновления. SetCancellationToken метод вызывается на EwsUpdateItem объект, передавая cancellationToken параметр, который является необязательным и может использоваться для отмены асинхронной операции.
2. Передаёт EwsUpdateItem объекта в качестве параметра для UpdateItemAsync метод EWSClient.
3. Этот UpdateItemAsync метод возвращает объект Task, который завершается, когда асинхронная операция завершена. Ключевое слово "await" используется для ожидания завершения объекта Task перед продолжением.

await ewsClient.UpdateItemAsync(
    EwsUpdateItem.Create(mapiNote)
        .SetCancellationToken(cancellationToken));