عمليات البريد الإلكتروني غير المتزامنة مع مصادقة OAuth وعميل EWS

طريقة Async لجلب رمز 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

مثال الكود التالي يحصل على عميل خدمات الويب لتبادل الرسائل (EWS) بشكل غير متزامن باستخدام مصادقة OAuth. يقوم الكود بتنفيذ الخطوات التالية:

  1. ينشئ جديدًا CancellationToken كائن يمكن استخدامه لإلغاء العمليات غير المتزامنة.
  2. يقوم بإنشاء SomeAsyncTokenProvider فئة تنفذ الـ IAsyncTokenProvider الواجهة. تُستخدم هذه الفئة كمعامل لإنشاء OAuthNetworkCredential الكائن.
  3. يحدد URI صندوق البريد إلى نقطة النهاية لخدمات الويب لتبادل الرسائل (Exchange Web Services).
  4. تستدعي الـ GetEwsClientAsync طريقة الـ EWSClient class مع الـ 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("from@aspose.com", "to@aspose.com", "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));
استرجاع رسائل البريد الإلكتروني من صندوق بريد مشترك باستخدام C# وEWS API تمكين تسجيل النشاط لعميل EWS في تطبيقات .NET