الاتصال بخادم Exchange باستخدام EWS و IMAP

للاتصال بخوادم Exchange 2007 و2010 و2013 باستخدام Exchange Web Service، يقدم Aspose.Email الـ IEWSClient واجهة تُنفّذ EWSClient الفئة. الـ EWSClient.GetEWSClient تُنشئ الطريقة وتعيد IEWSClient كائن يُستخدم لاحقًا لأداء عمليات متعلقة بصندوق بريد Exchange ومجلدات أخرى. تُظهر هذه المقالة كيفية إنشاء كائنات من IEWSClient.

الاتصال بخادم Exchange باستخدام 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 باستخدام IMAP

يدعم خادم Microsoft Exchange بروتوكول IMAP للوصول إلى العناصر في صندوق البريد. استخدم Aspose.Email ImapClient فئة للاتصال بخادم Exchange باستخدام بروتوكول IMAP. لمزيد من المعلومات حول ImapClient فئة. أولاً، تأكد من تمكين خدمات IMAP لخادم Exchange الخاص بك:

  1. افتح لوحة التحكم.
  2. انتقل إلى أدوات المسؤول، ثم الخدمات.
  3. تحقق من حالة خدمة Microsoft Exchange IMAP4.
  4. إذا لم يكن قيد التشغيل بالفعل، فمكنه/ابدأ تشغيله.

يعرض مقطع الشيفرة التالي كيفية الاتصال وقائمة الرسائل من مجلد الوارد في خادم Microsoft Exchange باستخدام بروتوكول 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 وقد تختلف بناءً على نسخة .NET الحالية.

لتعيين إصدار SSL/TLS استخدم الشيفرة التالية:

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

أو

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

ملاحظة، إذا كان EncryptionProtocol المحدد غير مدعوم من قبل نسخة .NET الحالية، فإن 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 مطلوبة، ويتم حظر اتصالات المصادقة الأساسية. > يجب إيقاف تشغيل إعدادات الأمان الافتراضية في بوابة Azure قبل أن تتمكن من تعديل أي إعدادات هنا.

يمكنك تمكين دعم المصادقة الأساسية للمستأجر من Azure البوابة، انتقل إلى Azure Active Directory > Properties > Manage Security defaults > Enable Security defaults > No. لمزيد من المعلومات، راجع مقال توثيقي من مايكروسوفت.

تسجيل التطبيق مع Azure Active Directory

من الضروري إجراء تسجيل التطبيق مع Azure Active Directory. هناك نوعان من الأذونات يمكن استخدامها للوصول إلى صناديق البريد باستخدام تطبيقك. اختر نوع الإذن المناسب وفقاً للتطبيق الذي تنشئه:

  • التطبيقات التي تستخدم الأذونات المفوضة لديها مستخدم مسجل الدخول. بمعنى آخر، عند اتصالك بالخدمة، تظهر نافذة حوار لاسم المستخدم وكلمة المرور. لا يمكن للتطبيق أن يمتلك صلاحيات أكثر من المستخدم المسجل.
  • التطبيقات التي تستخدم أذونات التطبيق تعمل دون وجود مستخدم مسجل الدخول. على سبيل المثال، هذه تطبيقات تعمل كخدمات خلفية أو daemons. يمكن للمسؤول فقط الموافقة على أذونات التطبيق.

بالإضافة إلى ذلك، راجع مقال توثيقي من مايكروسوفت لمزيد من المعلومات.

تعتمد إجراءات التسجيل على نوع الإذن المختار. لتسجيل تطبيقك، راجع مقال توثيقي من مايكروسوفت.

استخدام المصادقة الحديثة مع EWSClient

بعد تسجيل التطبيق، يمكننا التركيز على كتابة الشيفرة، والتي ستتكون من الأجزاء التالية:

  • احصل على رمز التفويض.
  • استخدام الرمز المميز للمصادقة.

الحصول على رمز التفويض

للحصول على الرمز المميز سنستخدم مكتبة المصادقة من مايكروسوفت (MSAL) لــ .NET.

الخطوات التالية للحصول على رمز التفويض.

  • أضف الـ حزمة NuGet Microsoft.Identity.Client التي تحتوي على ملفات الـ binaries الخاصة بـ 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

للحصول على الرمز المميز سنستخدم مكتبة المصادقة من مايكروسوفت (MSAL) لــ .NET.

الخطوات التالية للحصول على رمز التفويض.

  • أضف الـ حزمة NuGet Microsoft.Identity.Client التي تحتوي على ملفات الـ binaries الخاصة بـ 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);

إرجاع معرف طلب العميل

الـ 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

تتيح واجهة برمجة تطبيقات Aspose.Email إضافة رؤوس إلى طلبات Exchange. يمكن استخدام ذلك لإضافة رؤوس إلى طلبات EWS لأغراض مختلفة. مثال على ذلك هو إضافة رأس X-AnchorMailbox الذي يُستخدم لإدارة مشكلات التقييد على خادم Exchange. الـ AddHeader طريقة الـ IEWSClient يُستخدم لإضافة رؤوس إلى طلبات EWS كما هو موضح في مقتطف الشيفرة التالي.

تجاهل أو تجاوز شهادة SSL غير صالحة أو منتهية الصلاحية

يمكن لـ Aspose.Email التعامل مع شهادات SSL على خادم Exchange باستخدام كلا الـ ExchangeClient و EWSClient الفئات. إذا انتهت صلاحية شهادة SSL أو أصبحت غير صالحة، تقوم Aspose.Email بإلقاء استثناء بسبب شهادة SSL غير صالحة. تجنّب مثل هذه الأخطاء في شهادة SSL بتجاهلها باستخدام الطريقة المستخدمة في الشيفرة أدناه. سجّل معالج الاستدعاء الرجعي في دالة main() أو init() الخاصة بك وأضف الطريقة أدناه كعضو في الفئة.

استرجاع وإدارة معلومات صندوق بريد خادم Exchange باستخدام EWS