Conectar ao Exchange Server usando EWS e IMAP

Para conectar aos servidores Exchange 2007, 2010 e 2013 usando Exchange Web Service, o Aspose.Email fornece o IEWSClient interface que implementa o EWSClient classe. O EWSClient.GetEWSClient método instancia e retorna um IEWSClient objeto que é posteriormente usado para executar operações relacionadas a uma caixa de correio Exchange e outras pastas. Este artigo mostra como instanciar objetos de IEWSClient.

Conectando ao Exchange Server usando EWS

O trecho de código a seguir mostra como estabelecer uma conexão usando 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;
}

Adicionar Cabeçalhos Personalizados à Inicialização do EWSClient

Em cenários onde cabeçalhos específicos são necessários durante a inicialização do cliente, como o cabeçalho X-AnchorMailbox no EWS, use os métodos sobrecarregados a seguir para adicionar cabeçalhos personalizados ao criar uma instância de IEWSClient:

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

O exemplo de código abaixo demonstra como configurar e inicializar o IEWSClient enquanto utiliza cabeçalhos HTTP personalizados:

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

Conectando ao Exchange Server usando IMAP

O Microsoft Exchange Server suporta o protocolo IMAP para acessar itens em uma caixa de correio. Use o Aspose.Email ImapClient classe para conectar ao Exchange Server usando o protocolo IMAP. Para mais informações sobre o ImapClient classe. Primeiro, certifique-se de que os serviços IMAP estejam habilitados para o seu Exchange Server:

Abra o Painel de Controle.
Vá para Ferramentas Administrativas, depois Serviços.
Verifique o status do serviço Microsoft Exchange IMAP4.
Se não estiver em execução, habilite/inicie-o.

O trecho de código a seguir mostra como conectar e listar mensagens da pasta Caixa de Entrada de um Microsoft Exchange Server usando o protocolo 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();

O trecho de código a seguir mostra como usar 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
}

Depois de conectar a um servidor Exchange usando IMAP e obter o IMapMessageInfoCollection, você pode obter o MessageInfo objeto. O trecho de código a seguir mostra como usar o número de sequência do MessageInfo objeto para salvar uma mensagem específica.

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

Definindo o Protocolo de Criptografia Preferido

O EWS usa o protocolo de transporte HTTPS para operações suportadas. A criptografia é fornecida pelos protocolos SSL/TLS. Esses protocolos são implementados pelo .NET framework e podem variar dependendo da versão atual do .NET framework.

Para definir a versão SSL/TLS, use o código a seguir:

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

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

Observe que, se o EncryptionProtocol especificado não for suportado pela versão atual do .NET framework, o SupportedEncryption propriedade rebaixa o protocolo de criptografia para um nível suportado e o SetSupportedEncryptionUnsafe método lança uma exceção.

Conectar ao Exchange Server usando Autenticação Moderna

A Autenticação Moderna agora está habilitada por padrão para todas as novas locatárias Microsoft 365/Azure porque este protocolo é mais seguro que a Autenticação Básica, que está obsoleta.

A Autenticação Moderna é baseada na Active Directory Authentication Library e OAuth 2.0. Ela usa tokens de tempo limitado, e as aplicações não armazenam credenciais de usuário.

Configurações pré-requisitos

Para usar a Autenticação Moderna, certifique-se de que ela está habilitada. Contudo, para locatárias criadas antes de 1 de agosto de 2017, a autenticação moderna está desativada por padrão. No Centro de administração Microsoft 365, vá em Configurações > Configurações da Org > Autenticação Moderna. No menu suspenso de Autenticação Moderna que aparece, você pode identificar os protocolos que não exigem mais Autenticação Básica. Para novas locatárias Microsoft365 no Azure, a Autenticação Básica está desativada por padrão para todas as aplicações. Portanto, o texto será exibido nesta seção.

Sua organização tem os padrões de segurança habilitados, o que significa que a autenticação moderna para o Exchange Online é necessária e as conexões de autenticação básica são bloqueadas. > Você deve desativar os padrões de segurança no portal Azure antes de poder alterar quaisquer configurações aqui.

Você pode habilitar o suporte a Autenticação Básica para a locatária a partir do Azure portal, vá em Azure Active Directory > Propriedades > Gerenciar padrões de segurança > Habilitar padrões de segurança > Não. Para mais informações, veja o Artigo de Documentação da Microsoft.

Registro de Aplicativo com Azure Active Directory

É necessário realizar o registro de aplicativo no Azure Active Directory. Existem dois tipos de permissões que podem ser usadas para acessar caixas de correio com seu aplicativo. Escolha um tipo específico de permissão, dependendo do aplicativo que você está criando:

Aplicativos que usam Permissões delegadas têm um usuário autenticado presente. Em outras palavras, ao conectar ao serviço, aparece uma janela de diálogo para nome de usuário e senha. O aplicativo nunca pode ter mais privilégios do que um usuário autenticado.
Aplicativos que usam Permissões de Aplicação são executados sem a presença de um usuário autenticado. Por exemplo, são aplicativos que funcionam como serviços de fundo ou daemons. Apenas um administrador pode consentir com permissões de aplicação.

Além disso, consulte o Artigo de Documentação da Microsoft para mais informações.

O procedimento de registro depende do tipo de permissão selecionada. Para registrar seu aplicativo, consulte o Artigo de Documentação da Microsoft.

Usar Autenticação Moderna com EWSClient

Após registrar o aplicativo, podemos nos concentrar em escrever o código, que consistirá nas seguintes partes:

Obter o token de autorização.
Usar o token para autenticar.

Obter Token de Autorização

Para obter o token usaremos Microsoft Authentication Library (MSAL) para .NET.

Os seguintes são os passos para obter o token de autorização.

Adicionar o pacote NuGet Microsoft.Identity.Client que contém os binários do MSAL.NET.
Criar uma classe AccessParameters para armazenar credenciais.
Criar um método que aceita parâmetros de acesso e usa MSAL.NET para obter um token de acesso.

Os exemplos de código a seguir dependerão do tipo de autenticação escolhido.

Obter um token com autenticação delegada

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

Obter um token com autenticação de aplicativo

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

Autenticando com o Token

Depois disso, quando tivermos obtido o token com sucesso, vamos iniciar o EwsClient.

Usando o token com autenticação delegada

NetworkCredential credentials = new OAuthNetworkCredential(accessToken);

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

Experimente! Execute o EWSModernAuthenticationDelegated projeto de aplicativo simples, conectar ao Microsoft 365 com autenticação delegada e ler sua caixa de entrada.

Usando o token com autenticação de aplicativo

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

Experimente! Execute o EWSModernAuthenticationApp projeto de aplicativo simples, conectar ao Microsoft 365 com autenticação de aplicativo e ler sua caixa de entrada.

Usar Autenticação Moderna com clientes IMAP, POP ou SMTP

O acesso IMAP, POP, SMTP via permissões de aplicação não é suportado. Em outras palavras, apenas a autenticação delegada é suportada.

O procedimento de registro de aplicativo com Azure Active Directory está definido acima.

Habilitar ou Desativar IMAP, POP, SMTP AUTH no Centro de Administração Microsoft 365

Abra o Centro de administração Microsoft 365 e vá em Usuários > Usuários ativos.
Selecione o usuário e, no menu que aparecer, clique em Mail.
Na seção Aplicativos de e‑mail, clique em Gerenciar aplicativos de e‑mail.
Verifique a configuração IMAP, POP, SMTP Autenticado: desmarcado = desativado, marcado = ativado.
Clique em Salvar alterações.

Recuperar Token de Autenticação do Servidor de Tokens

Certifique-se de especificar os escopos completos, incluindo URLs de recursos do Outlook.

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

Para obter o token usaremos Microsoft Authentication Library (MSAL) para .NET.

Os seguintes são os passos para obter o token de autorização.

Adicionar o pacote NuGet Microsoft.Identity.Client que contém os binários do MSAL.NET.
Criar uma classe AccessParameters para armazenar credenciais.
Criar um método que aceita parâmetros de acesso e usa MSAL.NET para obter um token de acesso.

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

Autenticar com o Token

Depois disso, quando tivermos obtido o token com sucesso, vamos iniciar o ImapClient.

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

Da mesma forma, o SmtpClient a inicialização ficará assim.

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

Experimente! Execute o EWSModernAuthenticationImapSmtp projeto de aplicativo simples, conectar ao Microsoft 365 via IMAP e SMTP, e ler sua caixa de entrada.

Retornar o ID da Solicitação do Cliente

O ReturnClientRequestId propriedade foi adicionada ao EWSClient para sua conveniência, a fim de especificar se o ID da solicitação do cliente deve ser retornado na resposta das chamadas do Exchange Web Services (EWS). O ID da solicitação do cliente é um identificador único que você pode definir para cada solicitação EWS enviada a partir de sua aplicação. Ao definir o ReturnClientRequestId propriedade para true, você indica que deseja que o ID da solicitação do cliente seja incluído na resposta do servidor EWS. Isso pode ser útil para rastrear e correlacionar solicitações e respostas em cenários onde múltiplas solicitações são feitas e processadas assíncronamente.

O trecho de código a seguir mostra como a propriedade pode ser utilizada:

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

Adicionar X-AnchorMailbox e outros cabeçalhos às solicitações EWS

A API Aspose.Email permite adicionar cabeçalhos às solicitações Exchange. Isso pode ser usado para acrescentar cabeçalhos às solicitações EWS para diferentes propósitos. Um exemplo seria adicionar o cabeçalho X-AnchorMailbox, que é usado para gerenciar problemas de limitação no servidor Exchange. O AddHeader método do IEWSClient é usado para adicionar cabeçalhos às solicitações EWS conforme mostrado no trecho de código a seguir.

Ignorar ou Contornar Certificado SSL Inválido ou Expirado

O Aspose.Email pode lidar com certificados SSL no Exchange Server usando ambos os ExchangeClient e EWSClient classes. Se o certificado SSL expirou ou ficou inválido, o Aspose.Email lança uma exceção devido ao certificado SSL inválido. Evite esses erros de certificado SSL ignorando-os usando o método mostrado no código abaixo. Registre o manipulador de retorno de chamada no seu método main() ou init() e adicione o método abaixo como membro da classe.

Conectando ao Exchange Server usando Autenticação Moderna Recuperar e Gerenciar Informações da Caixa de Correio do Exchange Server Usando EWS