عملیات ایمیل ناهمزمان با احراز هویت OAuth و کلاینت EWS

متد ناهمزمان برای دریافت توکن OAuth

برخلاف متدهای همزمان، متدهای ناهمزمان غیرمسدودکننده هستند و امکان اجرای چندین درخواست به‌صورت همزمان را فراهم می‌کنند. متدهای ناهمزمان با پسوند Async نامگذاری می‌شوند.

توجه: متدهای 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

مثال کد بعدی یک کلاینت Exchange Web Services (EWS) را به‌صورت ناهمزمان با استفاده از احراز هویت OAuth دریافت می‌کند. این کد مراحل زیر را انجام می‌دهد:

  1. یک مورد جدید ایجاد می‌کند CancellationToken شیئی که می‌تواند برای لغو عملیات‌های ناهمزمان استفاده شود.
  2. نمونه‌سازی می‌کند SomeAsyncTokenProvider کلاسی که پیاده‌سازی می‌کند IAsyncTokenProvider رابط. این کلاس به‌عنوان پارامتری برای ساخت یک جدید استفاده می‌شود. OAuthNetworkCredential شیء.
  3. آدرس URI صندوق پستی را به نقطهٔ انتهایی Exchange Web Services تنظیم می‌کند.
  4. فراخوانی می‌کند GetEwsClientAsync متد از EWSClient کلاس با mailboxUri و OAuthNetworkCredential object به‌عنوان پارامترها. این متد یک شیء 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# و API EWS فعالسازی ثبت فعالیت برای مشتری EWS در برنامه‌های .NET