Свързване с Exchange Server чрез EWS и IMAP

За да се свържете към Exchange сървъри 2007, 2010 и 2013, използвайки Exchange Web Service, Aspose.Email предоставя IEWSClient интерфейс, който имплементира EWSClient клас. Този 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. Отворете Control Panel.
  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 Server чрез съвременно удостоверяване

Съвременното удостоверяване вече е активирано по подразбиране за всички нови Microsoft 365/Azure наематели, тъй като този протокол е по-сигурен от отмененото Basic Authentication.

Съвременното удостоверяване се базира на Active Directory Authentication Library и OAuth 2.0. То използва токени с ограничено време и приложенията не съхраняват потребителски данни.

Предварителни настройки

За да използвате съвременно удостоверяване, уверете се, че е активирано. Въпреки това, за наематели, създадени преди 1 август 2017, съвременното удостоверяване е изключено по подразбиране. В Microsoft 365 администраторски център, отидете на Settings > Org Settings > Modern Authentication. В изскачащия прозорец Modern authentication, който се появява, можете да идентифицирате протоколи, които вече не изискват Basic authentication. За нови Microsoft365 наематели в Azure, Basic Authentication е изключено по подразбиране за всички приложения. Следователно текстът ще бъде показан в този раздел.

Вашата организация има активирани настройки за сигурност по подразбиране, което означава, че е необходимо съвременно удостоверяване за Exchange Online и връзките чрез basic authentication са блокирани. > Трябва да изключите настройките за сигурност по подразбиране в 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.

Следните стъпки са за получаване на токен за упълномощаване.

  • Добавете Microsoft.Identity.Client NuGet пакет който съдържа бинарните файлове на 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.

Следните стъпки са за получаване на токен за упълномощаване.

  • Добавете Microsoft.Identity.Client NuGet пакет който съдържа бинарните файлове на 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);

Връщане на ID на клиентската заявка

Този ReturnClientRequestId то свойство беше добавено към EWSClient за ваше удобство, за да укажете дали ID на клиентската заявка трябва да бъде върнат в отговора от повикванията към Exchange Web Services (EWS) calls. Client request ID е уникален идентификатор, който можете да зададете за всяка 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 заявки

Aspose.Email API позволява добавяне на заглавки към Exchange заявки. Това може да се използва за добавяне на заглавки към EWS заявките за различни цели. Един пример е добавянето на заглавката X-AnchorMailbox, която се използва за управление на throttling проблемите на Exchange сървъра. The AddHeader метод на IEWSClient се използва за добавяне на заглавки към EWS заявките, както е показано в следния кодов откъс.

Игнориране или заобикаляне на невалиден или изтекъл SSL сертификат

Aspose.Email може да работи със SSL сертификати на Exchange Server, използвайки и двете ExchangeClient и EWSClient класове. Ако SSL сертификатът е изтекъл или се е превърнал в невалиден, Aspose.Email хвърля изключение поради невалиден SSL сертификат. Избягвайте такива грешки със SSL сертификат, като ги игнорирате с метода, използван в кода по-долу. Регистрирайте обработчика за обратен повик в вашия main() или init() метод и добавете метода по-долу като член на класа.

Извличане и управление на информация за пощенска кутия в Exchange Server чрез EWS