اتصال به Exchange Server با استفاده از 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 Server از پروتکل IMAP برای دسترسی به موارد موجود در یک صندوق پستی پشتیبانی میکند. از Aspose.Email استفاده کنید ImapClient کلاس برای اتصال به سرور Exchange با استفاده از پروتکل IMAP. برای اطلاعات بیشتر دربارهٔ ImapClient کلاس. ابتدا اطمینان حاصل کنید که سرویسهای IMAP برای سرور Exchange شما فعال هستند:
- پنل کنترل را باز کنید.
- به ابزارهای مدیر (Administrator Tools) رفته، سپس Services.
- وضعیت سرویس Microsoft Exchange IMAP4 را بررسی کنید.
- اگر قبلاً در حال اجرا نیست، آن را فعال/شروع کنید.
قطعه کد زیر نشان میدهد چگونه با استفاده از پروتکل IMAP به سرور Microsoft Exchange متصل شوید و پیامهای پوشه Inbox را فهرست کنید.
// 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 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 الزامی است و اتصالات احراز هویت پایه مسدود شدهاند. > شما باید پیشفرضهای امنیتی را در پرتال Azure خاموش کنید پیش از این که هر تنظیمی را اینجا تغییر دهید.
میتوانید پشتیبانی Basic Auth را برای مستأجر از آژور پرتال، به Azure Active Directory > Properties > Manage Security defaults > Enable Security defaults > No بروید. برای اطلاعات بیشتر، به مقاله مستندات مایکروسافت.
ثبت برنامه با Azure Active Directory
آزمون ثبت برنامه با Azure Active Directory ضروری است. دو نوع مجوز وجود دارد که میتوان با برنامه خود به صندوقهای ایمیل دسترسی پیدا کرد. بر اساس برنامهای که میسازید، نوع خاصی از مجوز را انتخاب کنید:
- برنامههایی که از مجوزهای واگذار شده استفاده میکنند، کاربر وارد شدهای دارند. به عبارت دیگر، زمانی که به سرویس متصل میشوید، یک پنجره گفتوگو برای نام کاربری و رمز عبور ظاهر میشود. برنامه هرگز نمیتواند از امتیازات کاربر وارد شده بیشتر داشته باشد.
- برنامههایی که از مجوزهای برنامه استفاده میکنند بدون حضور کاربر وارد شده اجرا میشوند. برای مثال، این برنامهها به عنوان سرویسهای پسزمینه یا دیمونها اجرا میشوند. فقط یک مدیر میتواند به مجوزهای برنامه رضایت دهد.
علاوه بر این، به مقاله مستندات مایکروسافت برای اطلاعات بیشتر.
فرآیند ثبت بستگی به نوع مجوز انتخابشده دارد. برای ثبت برنامه خود، به مقاله مستندات مایکروسافت.
استفاده از احراز هویت مدرن با EWSClient
پس از ثبت برنامه، میتوانیم بر نوشتن کد تمرکز کنیم که از بخشهای زیر تشکیل خواهد شد:
- دریافت توکن مجوز.
- از توکن برای احراز هویت استفاده کنید.
دریافت توکن مجوز
برای دریافت توکن از کتابخانه احراز هویت مایکروسافت (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 Admin Center
- باز کنید مرکز مدیریت Microsoft 365 و به Users > Active users بروید.
- کاربر را انتخاب کنید و در پنجرهای که ظاهر میشود، روی Mail کلیک کنید.
- در بخش Email apps، روی Manage email apps کلیک کنید.
- تنظیم IMAP، POP، 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 که شامل باینریهای 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 (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 جلوگیری کنید. هندلر callback را در متد main() یا init() خود ثبت کنید و متد زیر را به عنوان عضو کلاس اضافه کنید.