Introdução aos aplicativos clientes de API gerenciada pelo EWS

Artigo
03/29/2023

Desenvolva um aplicativo cliente de email Olá, Mundo simples para o Exchange usando a API Gerenciada do EWS.

A API Gerenciada do EWS fornece um modelo de objeto intuitivo e fácil de usar para enviar e receber mensagens de serviço Web de aplicativos cliente, aplicativos de portal e aplicativos de serviço. Você pode acessar quase todas as informações armazenadas em um Exchange Online, Exchange Online como parte do Office 365 ou uma caixa de correio do servidor Exchange usando a API Gerenciada do EWS. Você pode usar as informações neste artigo para ajudá-lo a desenvolver seu primeiro aplicativo cliente da API Gerenciada do EWS.

Observação

Removeremos a capacidade de usar a autenticação básica no Exchange Online para EWS a partir de outubro de 2022: Substituição da autenticação Básica no Exchange Online. Em vez disso, você deve usar a autenticação OAuth. Autenticar um aplicativo EWS usando o OAuth

Observação

A API Gerenciada do EWS agora está disponível como um projeto de software livre no GitHub. É possível usar a biblioteca de software livre para:

Contribui com correções de bug e melhorias à API.
Obtenha correções e melhorias antes que estejam disponíveis em uma versão oficial.
Acesse a implementação mais abrangente e atualizada da API, para usar como referência ou criar novas bibliotecas em novas plataformas.

Agradecemos suas contribuições no GitHub.

Você precisará de um servidor Exchange

Se você já tiver uma conta de caixa de correio do Exchange, ignore esta etapa. Caso contrário, você tem as opções a seguir para configurar uma caixa de correio do Exchange para o seu primeiro aplicativo cliente do EWS:

Obtenha um Site de Desenvolvedor do Office 365 (recomendado). Esta é a maneira mais rápida de obter uma caixa de correio do Exchange.
Baixe oExchange Server.

Depois de verificar que você pode enviar e receber emails do seu servidor Exchange, você estará pronto para configurar seu ambiente de desenvolvimento. Você pode usar o Outlook Web App do cliente Web do Exchange para verificar se você pode enviar emails.

Defina seu ambiente de desenvolvimento

Verifique se você tem acesso ao seguinte:

Qualquer versão do Visual Studio compatível com o .NET Framework 4. Embora, tecnicamente, você não precise do Visual Studio porque pode usar qualquer compilador C#, recomendamos usá-lo.
A API gerenciada do EWS. Você pode usar a versão de 64 bits ou de 32 bits, dependendo do sistema. Use o local de instalação padrão.

Crie seu primeiro aplicativo de API Gerenciada do EWS

Estas etapas pressupõem que você configurou um Site de Desenvolvedor do Office 365. Se você baixou e instalou o Exchange , precisará instalar um certificado válido em seu servidor Exchange ou implementar um retorno de chamada de validação de certificado para um certificado autoassinado fornecido por padrão. Observe também que essas etapas podem variar um pouco dependendo da versão do Visual Studio que você está usando.

Etapa 1: Criar um projeto no Visual Studio

No menu Arquivo, escolha Novo e, em seguida, selecione Projeto. Abre a caixa de diálogo Novo projeto.
Crie um Crie um aplicativo de console C#. No painel Modelos, escolha Visual C# e escolha Aplicativo de Console.
Nomeie o projeto como HelloWorld e, em seguida, selecione OK.

O Visual Studio cria o projeto e abre a janela do documento de código Program.cs.

Etapa 2: adicionar uma referência à API Gerenciada do EWS

Se a janelaGerenciador de Soluções já estiver aberta, ignore esta etapa e prossiga para a etapa 2. Para abrir a janela Gerenciador de Soluções, no menu Exibir, escolha Gerenciador de Soluções.
No projeto do Gerenciador de Soluções e do HelloWorld, abra o menu de atalho (clique com o botão direito do mouse) para Referências e escolha Adicionar Referência no menu de contexto. Uma caixa de diálogo para gerenciar referências de projeto será aberta.
Escolha a configuração Procurar. Navegue até o local onde você instalou a DLL da API Gerenciada do EWS. O caminho padrão definido pelo instalador é o seguinte: C:\Arquivos de Programa\Microsoft\Exchange\Web Services<versão>. O caminho pode variar de acordo com o download da versão de 32 ou 64 bits do Microsoft.Exchange.WebServices.dll. Escolha Microsoft.Exchange.WebServices.dll e selecione OK ou Adicionar. Isso adiciona a referência da API Gerenciada do EWS ao seu projeto.
Se você estiver usando a API Gerenciada do EWS 2.0, altere o projeto HelloWorld para direcionar o .NET Framework 4. Outras versões da API Gerenciada do EWS podem usar uma versão de destino diferente do .NET Framework.
Confirme se você está usando a versão de destino correta do .NET Framework. Abra o menu de atalho (clique com o botão direito do mouse) para o projeto HelloWorld noGerenciador de Soluçõese escolha Propriedades. Verifique se o .NET Framework 4 está selecionado na caixa suspensa Estrutura de destino.

Agora que você configurou seu projeto e criou uma referência à API Gerenciada do EWS, você está pronto para criar seu primeiro aplicativo. Para manter as coisas simples, adicione seu código ao arquivo Program.cs. Leia Consulte a montagem da API Gerenciada do EWS para obter mais informações sobre como fazer referência à API Gerenciada do EWS. Na próxima etapa, você desenvolverá o código básico para escrever a maioria dos aplicativos cliente da API Gerenciada do EWS.]

Etapa 3: configurar a validação de redirecionamento de URL para Descoberta Automática

Adicione o seguinte método de retorno de chamada de validação de redirecionamento após o método main(string[] args). Isso valida se as URLs redirecionadas retornadas pela Descoberta Automática representam um ponto de extremidade HTTPS.

private static bool RedirectionUrlValidationCallback(string redirectionUrl)
{
   // The default for the validation callback is to reject the URL.
   bool result = false;
   Uri redirectionUri = new Uri(redirectionUrl);
   // Validate the contents of the redirection URL. In this simple validation
   // callback, the redirection URL is considered valid if it is using HTTPS
   // to encrypt the authentication credentials. 
   if (redirectionUri.Scheme == "https")
   {
      result = true;
   }
   return result;
}

Esse retorno de chamada de validação será passado para o objetoExchangeService na etapa 4. Você precisa disso para que seu aplicativo confie e siga os redirecionamentos de Descoberta Automática. Os resultados do redirecionamento de Descoberta Automática fornecem o ponto de extremidade do EWS para nosso aplicativo.

Etapa 4: Preparar o objeto ExchangeService

Adicione uma referência de diretiva de uso à API Gerenciada do EWS. Adicione o código a seguir após a última diretiva de uso na parte superior de Program.cs.
```
 using Microsoft.Exchange.WebServices.Data;
```
No método Principal, crie uma instância do objeto ExchangeService com a versão de serviço que você pretende direcionar. Este exemplo tem como destino a versão mais antiga do esquema EWS.
```
 ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2007_SP1);
```
Se você estiver direcionando um servidor Exchange local e seu cliente estiver ingressado no domínio, prossiga para a etapa 4. Se o cliente estiver direcionando uma caixa de correio do Site do Desenvolvedor do Exchange Online ou do Office 365, você precisará passar credenciais explícitas. Adicione o código a seguir após a instanciação do objeto ExchangeService e defina as credenciais para sua conta de caixa de correio. O nome de usuário deve ser o nome principal do usuário. Prossiga para a Etapa 5.
```
 service.Credentials = new WebCredentials("user1@contoso.com", "password");
```
Clientes ingressados no domínio direcionados a um servidor Exchange local podem usar as credenciais padrão do usuário que está conectado, supondo que as credenciais estejam associadas a uma caixa de correio. Adicione o código a seguir após a instanciação do objeto ExchangeService.
```
 service.UseDefaultCredentials = true;
```
Se o cliente for direcionado a uma caixa de correio do Site de Desenvolvedor do Exchange Online ou do Office 365, verifique se UseDefaultCredentials está definido como falso, que é o valor padrão. Seu cliente está pronto para fazer a primeira chamada ao serviço de Descoberta Automática para obter a URL do serviço para chamadas para o serviço EWS.
O método AutoDiscoverUrl no objetoExchangeService executa uma série de chamadas para o serviço de Descoberta Automática para obter a URL do serviço. Se essa chamada de método for bem-sucedida, a propriedade URL no objeto ExchangeService será definida com a URL do serviço. Passe o endereço de email do usuário e o RedirectionUrlValidationCallback para o método AutodiscoverUrl. Adicione o código a seguir depois que as credenciais tiverem sido especificadas na etapa 3 ou 4. Mude user1@contoso.com para seu endereço de email para que o serviço Descoberta Automática localize o ponto de extremidade do EWS.
```
 service.AutodiscoverUrl("user1@contoso.com", RedirectionUrlValidationCallback);
```

Neste ponto, seu cliente está configurado para fazer chamadas ao EWS para acessar os dados da caixa de correio. Se você executar seu código agora, poderá verificar se a chamada de método AutoDiscoverUrl funcionou examinando o conteúdo da propriedade ExchangeService.Url. Se essa propriedade contiver uma URL, sua chamada foi um sucesso! Isso significa que seu aplicativo foi autenticado com êxito com o serviço e descobriu o ponto de extremidade do EWS para sua caixa de correio. Agora você está pronto para fazer suas primeiras chamadas para o EWS. Leia Definir a URL do serviço do EWS usando a API Gerenciada do EWS para obter mais informações sobre como definir a URL do EWS.

Etapa 6: criar sua primeira mensagem de email do Olá, Mundo

Após chamada de método AutoDiscoverUrl, crie uma instância de um novo objeto EmailMessage e passe o objeto de serviço que você criou.
```
 EmailMessage email = new EmailMessage(service);
```
Agora você tem uma mensagem de email na qual a associação de serviço está definida. Todas as chamadas iniciadas no objeto EmailMessageserão direcionadas ao serviço.
Agora defina Para: destinatário da linha da mensagem de email. Para fazer isso, altere user1@contoso.com para usar seu endereço SMTP.
```
 email.ToRecipients.Add("user1@contoso.com");
```

Defina o assunto e o corpo da mensagem de email.

 email.Subject = "HelloWorld";
 email.Body = new MessageBody("This is the first email I've sent by using the EWS Managed API.");

Agora você está pronto para enviar sua primeira mensagem de email usando a API Gerenciada do EWS. O método Enviar chamará o serviço e enviará a mensagem de email para entrega. Leia Comunicar-se com o EWS usando a API Gerenciada do EWS para saber mais sobre outros métodos que você pode usar para se comunicar com o Exchange.
```
 email.Send();
```
Você está pronto para executar seu aplicativo Olá, Mundo. No Visual Studio, selecione F5. Uma janela em branco do console será aberta. Você não verá nada na janela do console enquanto o aplicativo é autenticado, segue redirecionamentos de Descoberta Automática e, em seguida, faz sua primeira chamada para criar uma mensagem de email que você envia para si mesmo. Se você quiser ver as chamadas que estão sendo feitas, adicione as duas linhas de código a seguir antes que o método AutoDiscoverUrl seja chamado. Em seguida, pressione F5. Isso rastreará as solicitações e respostas do EWS à janela do console.
```
 service.TraceEnabled = true;
 service.TraceFlags = TraceFlags.All;
```

Agora você tem um aplicativo cliente de API Gerenciada do EWS em funcionamento. Para sua conveniência, o exemplo a seguir mostra todo o código que você adicionou ao Program.cs para criar seu aplicativo Olá, Mundo.

using System;
using Microsoft.Exchange.WebServices.Data;
namespace HelloWorld
{
  class Program
  {
    static void Main(string[] args)
    {
      ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2007_SP1);
      service.Credentials = new WebCredentials("user1@contoso.com", "password");
      service.TraceEnabled = true;
      service.TraceFlags = TraceFlags.All;
      service.AutodiscoverUrl("user1@contoso.com", RedirectionUrlValidationCallback);
      EmailMessage email = new EmailMessage(service);
      email.ToRecipients.Add("user1@contoso.com");
      email.Subject = "HelloWorld";
      email.Body = new MessageBody("This is the first email I've sent by using the EWS Managed API");
      email.Send();
    }
    private static bool RedirectionUrlValidationCallback(string redirectionUrl)
    {
      // The default for the validation callback is to reject the URL.
      bool result = false;
      Uri redirectionUri = new Uri(redirectionUrl);
      // Validate the contents of the redirection URL. In this simple validation
      // callback, the redirection URL is considered valid if it is using HTTPS
      // to encrypt the authentication credentials. 
      if (redirectionUri.Scheme == "https")
      {
        result = true;
      }
      return result;
    }
  }
}

Próximas etapas

Se você estiver pronto para fazer mais com seu primeiro aplicativo cliente da API Gerenciada do EWS, explore os seguintes recursos:

Se você tiver algum problema com o aplicativo, tente postar uma pergunta ou comentário no fórum (e não se esqueça de ler a primeira postagem).

Compartilhar via