Использование асинхронных операций в EWSClient

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

ЗАМЕТКА: Асинхронные методы доступны в версиях, совместимых с .NET Core, .NET Framework 4.5 и выше.

Реализация IAsyncTokenProvider для получения OAuth токенов асинхронно

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

private class SomeAsyncTokenProvider : IAsyncTokenProvider
{
    public SomeAsyncTokenProvider( /*некоторые параметры*/)
    {
        ...
    }

    public async Task<OAuthToken> GetAccessTokenAsync(bool ignoreExistingToken = false,
        CancellationToken cancellationToken = default)
    {
        //Некоторый асинхронный код для получения действительного OAuthToken
        ...
    }

    public void Dispose()
    {
        ...
    }
}

Создание IAsyncEwsClientInstance

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

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

//Создание IAsyncEwsClientInstance
IAsyncTokenProvider tokenProvider = new SomeAsyncTokenProvider(/*некоторые параметры*/);
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("from@aspose.com", "to@aspose.com", "Тема", "Текст сообщения");
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));