Terhubung ke Exchange Server Menggunakan EWS dan IMAP

Untuk terhubung ke server Exchange 2007, 2010, dan 2013 menggunakan Exchange Web Service, Aspose.Email menyediakan IEWSClient antarmuka yang mengimplementasikan EWSClient kelas. The EWSClient.GetEWSClient metode menginstansiasi dan mengembalikan sebuah IEWSClient objek yang selanjutnya digunakan untuk melakukan operasi terkait kotak surat Exchange dan folder lain. Artikel ini menunjukkan cara menginstansiasi objek dari IEWSClient.

Menghubungkan ke Server Exchange menggunakan EWS

Potongan kode berikut menunjukkan cara membuat koneksi menggunakan 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;
}

Tambahkan Header Kustom ke Inisialisasi EWSClient

Dalam skenario di mana header khusus diperlukan selama inisialisasi klien, seperti header X-AnchorMailbox di EWS, gunakan metode overload berikut untuk menambahkan header khusus saat membuat instance dari IEWSClient:

IEWSClient GetEWSClient(string mailboxUri, ICredentials credentials, WebProxy proxy, Dictionary headers)
async Task GetEwsClientAsync(string mailboxUri, ICredentials credentials, WebProxy proxy, CancellationToken cancellationToken , Dictionary headers)

Contoh kode di bawah ini menunjukkan cara mengonfigurasi dan menginisialisasi IEWSClient sambil menggunakan header HTTP khusus:

var headers = new Dictionary<string, string>();
headers.Add("X-AnchorMailbox", smtpExampleAddress);
IEWSClient client = EWSClient.GetEWSClient(HttpsExampleCom, new OAuthNetworkCredential("UserName", "Token"), null, headers);

Menghubungkan ke Server Exchange menggunakan IMAP

Microsoft Exchange Server mendukung protokol IMAP untuk mengakses item dalam kotak surat. Gunakan Aspose.Email ImapClient kelas untuk terhubung ke Exchange Server menggunakan protokol IMAP. Untuk informasi lebih lanjut tentang ImapClient kelas. Pertama, pastikan layanan IMAP diaktifkan untuk Server Exchange Anda:

Buka Panel Kontrol.
Buka Alat Administrator, lalu Layanan.
Periksa status layanan Microsoft Exchange IMAP4.
Jika belum berjalan, aktifkan/nyalakan.

Potongan kode berikut menunjukkan cara terhubung dan mencantumkan pesan dari folder Kotak Masuk server Microsoft Exchange menggunakan protokol 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();

Potongan kode berikut menunjukkan cara menggunakan 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
}

Setelah terhubung ke server Exchange menggunakan IMAP dan mendapatkan IMapMessageInfoCollection, Anda dapat mendapatkan MessageInfo objek. Potongan kode berikut menunjukkan cara menggunakan nomor urut dari MessageInfo objek untuk menyimpan pesan tertentu.

// 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);
}

Mengatur Protokol Enkripsi yang Diutamakan

EWS menggunakan protokol transport HTTPS untuk operasi yang didukung. Enkripsi disediakan oleh protokol SSL/TLS. Protokol ini diimplementasikan oleh .NET framework dan dapat berbeda tergantung pada versi .NET framework yang sedang digunakan.

Untuk mengatur versi SSL/TLS gunakan kode berikut:

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

atau

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

Catatan, jika EncryptionProtocol yang ditentukan tidak didukung oleh versi .NET framework saat ini, maka SupportedEncryption properti menurunkan protokol enkripsi ke tingkat yang didukung dan SetSupportedEncryptionUnsafe metode melemparkan pengecualian.

Terhubung ke Exchange Server menggunakan Modern Authentication

Modern Authentication kini diaktifkan secara default untuk semua tenant Microsoft 365/Azure baru karena protokol ini lebih aman dibandingkan Basic Authentication yang sudah tidak digunakan.

Modern Authentication didasarkan pada Active Directory Authentication Library dan OAuth 2.0. Itu menggunakan token dengan batas waktu, dan aplikasi tidak menyimpan kredensial pengguna.

Pengaturan Prasyarat

Untuk menggunakan Modern Authentication, pastikan itu diaktifkan. Namun, untuk tenant yang dibuat sebelum 1 Agustus 2017, modern authentication dimatikan secara default. Di Pusat admin Microsoft 365, buka Settings > Org Settings > Modern Authentication. Pada Modern authentication flyout yang muncul, Anda dapat mengidentifikasi protokol yang tidak lagi memerlukan Basic authentication. Untuk tenant Microsoft365 baru di Azure, Basic Authentication dinonaktifkan secara default untuk semua aplikasi. Oleh karena itu, teks akan ditampilkan di bagian ini.

Organisasi Anda mengaktifkan security defaults, yang berarti otentikasi modern ke Exchange Online diperlukan, dan koneksi otentikasi dasar diblokir. > Anda harus mematikan security defaults di portal Azure sebelum dapat mengubah pengaturan apa pun di sini.

Anda dapat mengaktifkan dukungan Basic Auth untuk tenant dari Azure portal, buka Azure Active Directory > Properties > Manage Security defaults > Enable Security defaults > No. Untuk informasi lebih lanjut, lihat Artikel Dokumentasi Microsoft.

Pendaftaran Aplikasi dengan Azure Active Directory

Perlu melakukan pendaftaran aplikasi dengan Azure Active Directory. Ada dua jenis izin yang dapat digunakan untuk mengakses kotak surat dengan aplikasi Anda. Pilih jenis izin tertentu, tergantung pada aplikasi yang Anda buat:

Aplikasi yang menggunakan Delegated permissions memiliki pengguna yang masuk. Dengan kata lain, ketika Anda terhubung ke layanan, jendela dialog muncul untuk memasukkan nama pengguna dan kata sandi. Aplikasi tidak pernah dapat memiliki hak lebih daripada pengguna yang masuk.
Aplikasi yang menggunakan Application permissions berjalan tanpa pengguna yang masuk. Misalnya, ini adalah aplikasi yang berjalan sebagai layanan latar belakang atau daemon. Hanya administrator yang dapat menyetujui izin aplikasi.

Selain itu, lihat Artikel Dokumentasi Microsoft untuk informasi lebih lanjut.

Prosedur pendaftaran tergantung pada jenis izin yang dipilih. Untuk mendaftarkan aplikasi Anda, lihat Artikel Dokumentasi Microsoft.

Gunakan Modern Authentication dengan EWSClient

Setelah mendaftarkan aplikasi, kita dapat fokus menulis kode, yang akan terdiri dari bagian-bagian berikut:

Dapatkan token otorisasi.
Gunakan token untuk mengautentikasi.

Dapatkan Token Otorisasi

Untuk mendapatkan token kami akan menggunakan Microsoft Authentication Library (MSAL) untuk .NET.

Berikut adalah langkah-langkah untuk mendapatkan token otorisasi.

Tambahkan paket nuget Microsoft.Identity.Client yang berisi berkas biner MSAL.NET.
Buat kelas AccessParameters untuk menyimpan kredensial.
Buat metode yang menerima parameter akses dan menggunakan MSAL.NET untuk mendapatkan token akses.

Contoh kode berikut akan bergantung pada jenis otorisasi yang dipilih.

Dapatkan token dengan otorisasi delegasi

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;
}

Dapatkan token dengan otorisasi aplikasi

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;
}

Mengautentikasi dengan Token

Setelah itu, ketika kita berhasil memperoleh token, mari inisialisasi EwsClient.

Menggunakan token dengan otorisasi delegasi

NetworkCredential credentials = new OAuthNetworkCredential(accessToken);

using var client = EWSClient.GetEWSClient("https://outlook.office365.com/EWS/Exchange.asmx", credentials);

Coba sekarang! Jalankan EWSModernAuthenticationDelegated proyek aplikasi sederhana, Terhubung ke Microsoft 365 dengan otorisasi delegasi, dan baca Kotak Masuk Anda.

Menggunakan token dengan otorisasi aplikasi

// 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);

Coba sekarang! Jalankan EWSModernAuthenticationApp proyek aplikasi sederhana, terhubung ke Microsoft 365 dengan otorisasi aplikasi, dan baca Kotak Masuk Anda.

Gunakan Modern Authentication dengan Klien IMAP, POP, atau SMTP

Akses IMAP, POP, SMTP melalui izin aplikasi tidak didukung. Dengan kata lain, hanya otentikasi delegasi yang didukung.

Prosedur pendaftaran Aplikasi dengan Azure Active Directory didefinisikan di atas.

Aktifkan atau Nonaktifkan IMAP, POP, SMTP AUTH di Microsoft 365 Admin Center

Buka Pusat admin Microsoft 365 dan buka Users > Active users.
Pilih pengguna, dan pada panel yang muncul, klik Mail.
Di bagian Email apps, klik Manage email apps.
Verifikasi pengaturan IMAP, POP, Authenticated SMTP: tidak dicentang = dinonaktifkan, dicentang = diaktifkan.
Klik Simpan perubahan.

Ambil Token Autentikasi dari Server Token

Pastikan untuk menentukan ruang lingkup lengkap, termasuk URL sumber daya Outlook.

IMAP: https://outlook.office.com/IMAP.AccessAsUser.All POP: https://outlook.office.com/POP.AccessAsUser.All SMTP: https://outlook.office.com/SMTP.Send

Untuk mendapatkan token kami akan menggunakan Microsoft Authentication Library (MSAL) untuk .NET.

Berikut adalah langkah-langkah untuk mendapatkan token otorisasi.

Tambahkan paket nuget Microsoft.Identity.Client yang berisi berkas biner MSAL.NET.
Buat kelas AccessParameters untuk menyimpan kredensial.
Buat metode yang menerima parameter akses dan menggunakan MSAL.NET untuk mendapatkan token akses.

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;
}

Autentikasi dengan Token

Setelah itu, ketika kita berhasil memperoleh token, mari inisialisasi ImapClient.

var imapClient = new ImapClient(
    "outlook.office365.com", 
    993, 
    username, 
    accessToken, 
    true);

Demikian pula, SmtpClient inisialisasi akan terlihat seperti berikut.

var smtpClient = new SmtpClient(
    "smtp.office365.com",
    587, 
    username,
    accessToken, 
    true);

Coba sekarang! Jalankan EWSModernAuthenticationImapSmtp proyek aplikasi sederhana, terhubung ke Microsoft 365 via IMAP dan SMTP, dan baca Kotak Masuk Anda.

Kembalikan ID Permintaan Klien

The ReturnClientRequestId properti ditambahkan ke EWSClient untuk kenyamanan Anda guna menentukan apakah ID permintaan klien harus dikembalikan dalam respons dari panggilan Exchange Web Services (EWS). ID permintaan klien adalah pengidentifikasi unik yang dapat Anda tetapkan untuk setiap permintaan EWS yang dikirim dari aplikasi Anda. Dengan mengatur ReturnClientRequestId properti ke true, Anda menunjukkan bahwa Anda menginginkan ID permintaan klien disertakan dalam respons dari server EWS. Ini dapat berguna untuk melacak dan mengkorelasikan permintaan serta respons dalam skenario di mana banyak permintaan dibuat dan diproses secara asynchronous.

Potongan kode berikut menunjukkan cara properti dapat digunakan:

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();
}

Tambahkan X-AnchorMailbox dan Header Lain ke Permintaan EWS

API Aspose.Email memungkinkan penambahan header ke permintaan Exchange. Ini dapat digunakan untuk menambahkan header ke permintaan EWS untuk berbagai header yang dapat dipakai untuk tujuan berbeda. Salah satu contohnya adalah menambahkan header X-AnchorMailbox yang digunakan untuk mengelola masalah throttling pada server Exchange. The AddHeader metode dari IEWSClient digunakan untuk menambahkan header ke permintaan EWS seperti yang ditunjukkan dalam potongan kode berikut.

Abaikan atau Lewati Sertifikat SSL yang Tidak Valid atau Kedaluwarsa

Aspose.Email dapat menangani sertifikat SSL pada Exchange Server menggunakan kedua ExchangeClient dan EWSClient kelas. Jika sertifikat SSL telah kedaluwarsa atau tidak valid, Aspose.Email melemparkan pengecualian karena sertifikat SSL tidak valid. Hindari kesalahan sertifikat SSL tersebut dengan mengabaikannya menggunakan metode yang digunakan pada kode di bawah ini. Daftarkan handler callback di metode main() atau init() Anda dan tambahkan metode di bawah ini sebagai anggota kelas.

Mengambil dan Mengelola Informasi Kotak Surat Exchange Server Menggunakan EWS