Підключення до сервера Exchange за допомогою EWS та IMAP

Для підключення до серверів Exchange 2007, 2010 та 2013 за допомогою Exchange Web Service Aspose.Email надає IEWSClient інтерфейс, який реалізує EWSClient клас. The EWSClient.GetEWSClient метод створює та повертає IEWSClient об’єкт, який далі використовується для виконання операцій, пов’язаних з поштовою скринькою Exchange та іншими папками. У цій статті показано, як створювати екземпляри IEWSClient.

Підключення до Exchange Server за допомогою EWS

Нижче наведений фрагмент коду показує, як встановити з’єднання за допомогою Exchange Web Service (EWS):

// For complete examples and data files, please go to https://github.com/aspose-email/Aspose.Email-for-.NET
private static IEWSClient GetExchangeEWSClient()
{
    const string mailboxUri = "https://outlook.office365.com/ews/exchange.asmx";
    const string domain = @"";
    const string username = @"username@ASE305.onmicrosoft.com";
    const string password = @"password";
    NetworkCredential credentials = new NetworkCredential(username, password, domain);
    IEWSClient client = EWSClient.GetEWSClient(mailboxUri, credentials);
    return client;
}

Додати власні заголовки до ініціалізації EWSClient

У сценаріях, коли під час ініціалізації клієнта потрібні специфічні заголовки, наприклад заголовок X-AnchorMailbox в EWS, використовуйте наведені нижче перевантажені методи для додавання власних заголовків при створенні екземпляра IEWSClient:

  • IEWSClient GetEWSClient(string mailboxUri, ICredentials credentials, WebProxy proxy, Dictionary headers)

  • async Task GetEwsClientAsync(string mailboxUri, ICredentials credentials, WebProxy proxy, CancellationToken cancellationToken , Dictionary headers)

Нижче наведений приклад коду демонструє, як налаштувати та ініціалізувати IEWSClient з використанням власних HTTP-заголовків:

var headers = new Dictionary<string, string>();
headers.Add("X-AnchorMailbox", smtpExampleAddress);
IEWSClient client = EWSClient.GetEWSClient(HttpsExampleCom, new OAuthNetworkCredential("UserName", "Token"), null, headers);

Підключення до Exchange Server за допомогою IMAP

Microsoft Exchange Server підтримує протокол IMAP для доступу до елементів у поштовій скриньці. Використовуйте Aspose.Email ImapClient клас для підключення до Exchange Server за допомогою протоколу IMAP. Для отримання додаткової інформації про ImapClient клас. По-перше, переконайтеся, що служби IMAP увімкнені для вашого Exchange Server:

  1. Відкрийте Панель управління.
  2. Перейдіть у Administrator Tools, потім у Services.
  3. Перевірте стан служби Microsoft Exchange IMAP4.
  4. Якщо він ще не запущений, увімкніть/запустіть його.

У наведеному фрагменті коду показано, як підключитися та вивести список повідомлень з папки Inbox Microsoft Exchange Server за допомогою протоколу IMAP.

// For complete examples and data files, please go to https://github.com/aspose-email/Aspose.Email-for-.NET
// Connect to Exchange Server using ImapClient class
ImapClient imapClient = new ImapClient("ex07sp1", "Administrator", "Evaluation1");
imapClient.SecurityOptions = SecurityOptions.Auto;

// Select the Inbox folder
imapClient.SelectFolder(ImapFolderInfo.InBox);

// Get the list of messages
ImapMessageInfoCollection msgCollection = imapClient.ListMessages();
foreach (ImapMessageInfo msgInfo in msgCollection)
{
    Console.WriteLine(msgInfo.Subject);
}
// Disconnect from the server
imapClient.Dispose();

У наведеному фрагменті коду показано, як використовувати SSL.

// For complete examples and data files, please go to https://github.com/aspose-email/Aspose.Email-for-.NET
public static void Run()
{            
    // Connect to Exchange Server using ImapClient class
    ImapClient imapClient = new ImapClient("ex07sp1", 993, "Administrator", "Evaluation1", new RemoteCertificateValidationCallback(RemoteCertificateValidationHandler));
    imapClient.SecurityOptions = SecurityOptions.SSLExplicit;

    // Select the Inbox folder
    imapClient.SelectFolder(ImapFolderInfo.InBox);

    // Get the list of messages
    ImapMessageInfoCollection msgCollection = imapClient.ListMessages();
    foreach (ImapMessageInfo msgInfo in msgCollection)
    {
        Console.WriteLine(msgInfo.Subject);
    }
    // Disconnect from the server
    imapClient.Dispose();   
}

// Certificate verification handler
private static bool RemoteCertificateValidationHandler(object sender, X509Certificate certificate, X509Chain chain, SslPolicyErrors sslPolicyErrors)
{
    return true; // ignore the checks and go ahead
}

Після підключення до сервера Exchange за допомогою IMAP та отримання IMapMessageInfoCollection, ви можете отримати MessageInfo об’єкт. Нижче наведено фрагмент коду, який показує, як використати номер послідовності MessageInfo об’єкт для збереження певного повідомлення.

// For complete examples and data files, please go to https://github.com/aspose-email/Aspose.Email-for-.NET
// Select the Inbox folder
imapClient.SelectFolder(ImapFolderInfo.InBox);
// Get the list of messages
ImapMessageInfoCollection msgCollection = imapClient.ListMessages();
foreach (ImapMessageInfo msgInfo in msgCollection)
{
    // Fetch the message from inbox using its SequenceNumber from msgInfo
    MailMessage message = imapClient.FetchMessage(msgInfo.SequenceNumber);

    // Save the message to disc now
    message.Save(dataDir + msgInfo.SequenceNumber + "_out.msg", SaveOptions.DefaultMsgUnicode);
}

Налаштування бажаного протоколу шифрування

EWS використовує протокол передачі HTTPS для підтримуваних операцій. Шифрування забезпечується протоколами SSL/TLS. Ці протоколи реалізовані в .NET framework і можуть відрізнятися залежно від поточної версії .NET framework.

Щоб встановити версію SSL/TLS, використайте наступний код:

var client = new ImapClient("some.host");
client.SupportedEncryption = EncryptionProtocols.Tls13;

або

var client = new ImapClient("some.host");
client.SetSupportedEncryptionUnsafe(EncryptionProtocols.Tls13);

Примітка: якщо вказаний EncryptionProtocol не підтримується поточною версією .NET framework, то SupportedEncryption властивість знижує протокол шифрування до підтримуваного рівня і SetSupportedEncryptionUnsafe метод генерує виняток.

Підключення до сервера Exchange за допомогою сучасної автентифікації

Сучасна автентифікація тепер увімкнена за замовчуванням для всіх нових орендарів Microsoft 365/Azure, оскільки цей протокол безпечніший за застарілу базову автентифікацію.

Сучасна автентифікація базується на Active Directory Authentication Library та OAuth 2.0. Вона використовує токени з обмеженим часом дії, і програми не зберігають облікові дані користувачів.

Попередні налаштування

Щоб використовувати сучасну автентифікацію, переконайтеся, що вона ввімкнена. Однак для орендарів, створених до 1 серпня 2017 року, сучасна автентифікація за замовчуванням вимкнена. У Центр адміністрування Microsoft 365, перейдіть Settings > Org Settings > Modern Authentication. У спливаючому вікні Modern authentication, що з’явиться, ви можете визначити протоколи, які більше не потребують базової автентифікації. Для нових орендарів Microsoft365 в Azure базова автентифікація за замовчуванням вимкнена для всіх застосунків. Тому текст буде відображатися в цьому розділі.

У вашій організації увімкнено параметри безпеки за замовчуванням, що означає, що для Exchange Online потрібна сучасна автентифікація, а підключення за допомогою базової автентифікації блокуються. > Перш ніж змінювати будь-які налаштування, потрібно вимкнути параметри безпеки в portal Azure.

Ви можете ввімкнути підтримку Basic Auth для орендаря з Azure у порталі перейдіть Azure Active Directory > Properties > Manage Security defaults > Enable Security defaults > No. Для отримання додаткової інформації дивіться Стаття документації Microsoft.

Реєстрація додатка в Azure Active Directory

Необхідно виконати реєстрацію додатка в Azure Active Directory. Існують два типи дозволів, які можна використати для доступу до поштових скриньок вашим додатком. Виберіть конкретний тип дозволу, залежно від створюваного додатка:

  • Додатки, які використовують Делеговані дозволи, мають залогіненного користувача. Іншими словами, коли ви підключаєтеся до сервісу, з’являється діалогове вікно для введення імені користувача та пароля. Додаток ніколи не може мати більше прав, ніж залогінений користувач.
  • Додатки, які використовують Дозволи програми, працюють без залогіненого користувача. Наприклад, це додатки, які працюють як фонова служба чи демони. Тільки адміністратор може надати згоду на дозволи програми.

Додатково, посилання на Стаття документації Microsoft для отримання додаткової інформації.

Процедура реєстрації залежить від обраного типу дозволу. Щоб зареєструвати ваш додаток, зверніться до Стаття документації Microsoft.

Використовувати сучасну автентифікацію з EWSClient

Після реєстрації програми ми можемо зосередитися на написанні коду, який складатиметься з таких частин:

  • Отримайте токен авторизації.
  • Використайте токен для автентифікації.

Отримати токен авторизації

Щоб отримати токен, ми використаємо Microsoft Authentication Library (MSAL) для .NET.

Нижче наведено кроки для отримання токену авторизації.

  • Додайте пакет NuGet Microsoft.Identity.Client який містить бінарні файли MSAL.NET.
  • Створіть клас AccessParameters для зберігання облікових даних.
  • Створіть метод, який приймає параметри доступу та використовує MSAL.NET для отримання токену доступу.

Наступні приклади коду залежать від обраного типу аутентифікації.

Отримати токен з делегованою аутентифікацією

public class AccessParameters
{
    public string TenantId { get; set; }
    public string ClientId { get; set; }
    public string RedirectUri { get; set; } = "http://localhost";
    public string[] Scopes { get; set; } = { "https://outlook.office365.com/EWS.AccessAsUser.All" };
}

public static async Task<string> GetAccessToken(AccessParameters accessParameters)
{
    var pca = PublicClientApplicationBuilder
                            .Create(accessParameters.ClientId)
                            .WithTenantId(accessParameters.TenantId)
                            .WithRedirectUri(ccessParameters.RedirectUri)
                            .Build();

    var result = await pca.AcquireTokenInteractive(accessParameters.Scopes)
        .WithUseEmbeddedWebView(false)
        .ExecuteAsync();

    return result.AccessToken;
}

Отримати токен за допомогою аутентифікації програми

public class AccessParameters
{
    public string TenantId { get; set; }
    public string ClientId { get; set; }
    public string ClientSecret { get; set; }
    public string[] Scopes { get; set; } = { "https://outlook.office365.com/.default" };
}

public static async Task<string> GetAccessToken(AccessParameters accessParameters)
{
    var cca = ConfidentialClientApplicationBuilder
        .Create(accessParameters.ClientId)
        .WithClientSecret(accessParameters.ClientSecret)
        .WithTenantId(accessParameters.TenantId)
        .Build();

    var result = await cca.AcquireTokenForClient(accessParameters.Scopes).ExecuteAsync();

    return result.AccessToken;
}

Автентифікація за допомогою токену

Після цього, коли ми успішно отримали токен, ініціалізуємо EwsClient.

Використання токену з делегованою аутентифікацією

NetworkCredential credentials = new OAuthNetworkCredential(accessToken);

using var client = EWSClient.GetEWSClient("https://outlook.office365.com/EWS/Exchange.asmx", credentials);

Використання токену з автентифікацією програми

// Use Microsoft365 username and access token
NetworkCredential credentials = new OAuthNetworkCredential(username, accessToken);

using var client = EWSClient.GetEWSClient("https://outlook.office365.com/EWS/Exchange.asmx", credentials);

Використовувати сучасну автентифікацію з клієнтами IMAP, POP або SMTP

Доступ до IMAP, POP, SMTP через дозволи програми не підтримується. Іншими словами, підтримується лише делегована автентифікація.

Процедура реєстрації додатка в Azure Active Directory визначена вище.

Увімкнути або вимкнути IMAP, POP, SMTP AUTH у центрі адміністрування Microsoft 365

  • Відкрийте Центр адміністрування Microsoft 365 і перейдіть до Users > Active users.
  • Виберіть користувача, і у спливаючому вікні, що з’явиться, натисніть Mail.
  • У розділі Email apps натисніть Manage email apps.
  • Перевірте налаштування IMAP, POP, Authenticated SMTP: зняте = вимкнено, встановлене = увімкнено.
  • Натисніть Save changes.

Отримати токен автентифікації з сервера токенів

Переконайтеся, що вказали повні області, включаючи URL-адреси ресурсів Outlook.

IMAP: https://outlook.office.com/IMAP.AccessAsUser.All POP: https://outlook.office.com/POP.AccessAsUser.All SMTP: https://outlook.office.com/SMTP.Send

Щоб отримати токен, ми використаємо Microsoft Authentication Library (MSAL) для .NET.

Нижче наведено кроки для отримання токену авторизації.

  • Додайте пакет NuGet Microsoft.Identity.Client який містить бінарні файли MSAL.NET.
  • Створіть клас AccessParameters для зберігання облікових даних.
  • Створіть метод, який приймає параметри доступу та використовує MSAL.NET для отримання токену доступу.
public class AccessParameters
{
    public string TenantId { get; set; }
    public string ClientId { get; set; }
    public string RedirectUri { get; set; } = "http://localhost";
    public string[] Scopes { get; set; } = { 
        "https://outlook.office.com/IMAP.AccessAsUser.All", 
        "https://outlook.office.com/SMTP.Send" };
}

public static async Task<string> GetAccessToken(AccessParameters accessParameters)
{
    var pca = PublicClientApplicationBuilder
                            .Create(accessParameters.ClientId)
                            .WithTenantId(accessParameters.TenantId)
                            .WithRedirectUri(ccessParameters.RedirectUri)
                            .Build();

    var result = await pca.AcquireTokenInteractive(accessParameters.Scopes)
        .WithUseEmbeddedWebView(false)
        .ExecuteAsync();

    return result.AccessToken;
}

Автентифікація за допомогою токену

Після цього, коли ми успішно отримали токен, ініціалізуємо ImapClient.

var imapClient = new ImapClient(
    "outlook.office365.com", 
    993, 
    username, 
    accessToken, 
    true);

Подібно, SmtpClient ініціалізація виглядатиме наступним чином.

var smtpClient = new SmtpClient(
    "smtp.office365.com",
    587, 
    username,
    accessToken, 
    true);

Повернути ідентифікатор запиту клієнта

The ReturnClientRequestId Властивість була додана до EWSClient для вашої зручності, щоб вказати, чи слід повертати ідентифікатор запиту клієнта у відповіді від викликів Exchange Web Services (EWS). Ідентифікатор запиту клієнта — унікальний ідентифікатор, який ви можете встановити для кожного запиту EWS, що надсилається з вашого застосунку. Встановивши ReturnClientRequestId встановивши властивість у true, ви вказуєте, що бажаєте, щоб ідентифікатор запиту клієнта був включений у відповідь сервера EWS. Це може бути корисно для відстеження та кореляції запитів і відповідей у сценаріях, коли здійснюється кілька запитів, оброблюваних асинхронно.

Нижче наведений фрагмент коду показує, як можна використати цю властивість:

using (IEWSClient client = TestUtil.CreateEWSClient(user))
{
   // Client will create random id and pass it to the server.
   // The server should include this id in request-id header of all responses.
   client.ReturnClientRequestId = true;
   
   client.LogFileName = "ews.log";
   client.GetMailboxInfo();
}

Додати X-AnchorMailbox та інші заголовки до запитів EWS

API Aspose.Email дозволяє додавати заголовки до запитів Exchange. Це можна використати для додавання заголовків до запитів EWS різних типів, які можуть бути використані з різними цілями. Приклад – додавання заголовка X-AnchorMailbox, який використовується для керування проблемами обмежень швидкості на сервері Exchange. The AddHeader метод IEWSClient використовується для додавання заголовків до запитів EWS, як показано у наведеному нижче фрагменті коду.

Ігнорувати або обходити недійсний або прострочений SSL‑сертифікат

Aspose.Email може обробляти SSL‑сертифікати на Exchange Server, використовуючи обидва ExchangeClient і EWSClient класи. Якщо SSL‑сертифікат закінчив термін дії або став недійсним, Aspose.Email генерує виключення через недійсний SSL‑сертифікат. Уникайте таких помилок SSL‑сертифіката, ігноруючи їх за допомогою методу, наведеного у коді нижче. Зареєструйте обробник зворотного виклику у вашому методі main() або init() і додайте наведений нижче метод як член класу.

Отримання та керування інформацією поштових скриньок Exchange Server за допомогою EWS