Empezar a trabajar con aplicaciones de cliente de la API administrada de EWS

Artículo
03/29/2023

Desarrolle una sencilla aplicación cliente de correo electrónico Hola a todos para Exchange mediante la API administrada EWS.

La API administrada EWS proporciona un modelo de objetos intuitivo y fácil de usar para enviar y recibir mensajes de servicios web desde aplicaciones cliente, aplicaciones de portal y aplicaciones de servicio. Puede tener acceso a casi toda la información almacenada en un buzón de correo de Exchange Online, Exchange Online como parte de Office 365 o Exchange Server mediante la API administrada EWS. Puede usar la información de este artículo como ayuda para desarrollar su primera aplicación cliente de la API administrada EWS.

Nota:

Vamos a eliminar la posibilidad de utilizar la autenticación básica en Exchange Online para EWS, a partir de octubre de 2022 Deprecación de la autenticación básica en Exchange Online. En su lugar, debería utilizar la autenticación OAuth. Autenticar una aplicación EWS mediante OAuth

Nota:

La API administrada EWS ya está disponible como proyecto de código abierto en GitHub. Puede usar la biblioteca de código abierto para:

Contribuir con correcciones de errores y mejoras a la API.
Obtener correcciones y mejoras antes de que estén disponibles en una versión oficial.
Tener acceso a una implementación más completa y actualizada de la API, para usarla como referencia o para crear nuevas bibliotecas en nuevas plataformas.

Agradecemos sus contribuciones en GitHub.

Necesitará un servidor de Exchange

Si ya tiene una cuenta de buzón de Exchange, puede omitir esta sección. En caso contrario, dispone de las opciones siguientes para configurar un buzón de Exchange para su primera aplicación cliente EWS:

Obtener un sitio para desarrolladores de Office 365 (recomendado). Esta es la forma más rápida de configurar un buzón de Exchange.
Descargar Exchange Server.

Una vez que haya comprobado que puede enviar y recibir correo electrónico desde Exchange, estará listo para configurar el entorno de desarrollo. Puede usar Outlook Web App del cliente web de Exchange para comprobar que puede enviar correo electrónico.

Configurar el entorno de desarrollo

Asegúrese de que tiene acceso a los siguientes elementos:

Cualquier versión de Visual Studio que sea compatible con .NET Framework 4. Aunque técnicamente no se necesita Visual Studio porque se puede usar cualquier compilador de C#, recomendamos que lo use.
La API administrada EWS. Puede usar la versión de 64 o 32 bits, en función de su sistema. Use la ubicación de instalación predeterminada.

Crear la primera aplicación de API administrada EWS

En estos pasos se da por supuesto que ha configurado un sitio para desarrolladores de Office 365. Si ha descargado e instalado Exchange, deberá instalar un certificado válido en el servidor de Exchange o implementar una devolución de llamada de validación de certificado para un certificado autofirmado proporcionado de forma predeterminada. Tenga en cuenta también que estos pasos pueden variar ligeramente según la versión de Visual Studio que use.

Paso 1: crear un proyecto en Visual Studio

En Visual Studio, en el menú Archivo, seleccione Nuevo y después elija Proyecto. Se abre el cuadro de diálogo Nuevo proyecto.
Cree una aplicación de consola de C#. En el panel Plantillas, elija Visual C# y luego Aplicación de consola.
Indique HelloWorld como nombre del proyecto y después elija Aceptar.

Visual Studio crea el proyecto y abre la ventana de documento de código Program.cs.

Paso 2: agregar una referencia a la API administrada EWS

Si la ventana Explorador de soluciones ya está abierta, omita este paso y vaya al paso 2. Para abrir la ventana Explorador de soluciones, en el menú Vista, elija Explorador de soluciones.
En el Explorador de soluciones y en el proyecto HelloWorld, abra el menú contextual (botón derecho) de Referencias y elija Agregar referencia en el menú contextual. Se abrirá un cuadro de diálogo para administrar las referencias del proyecto.
Elija la opción Examinar. Vaya a la ubicación donde instaló el archivo DLL de la API administrada EWS. La ruta de acceso predeterminada establecida por el instalador es la siguiente: C:\Archivos de programa\Microsoft\Exchange\Web Services<.> La ruta de acceso puede variar en función de si descarga la versión de 32 o de 64 bits del archivo Microsoft.Exchange.WebServices.dll. Elija Microsoft.Exchange.WebServices.dll y seleccione Aceptar o Agregar. Esto agrega la referencia de la API administrada EWS a su proyecto.
Si usa la API administrada 2.0 EWS, cambie el destino del proyecto HelloWorld a .NET Framework 4. Otras versiones de la API administrada EWS podrían usar una versión de destino diferente de .NET Framework.
Confirme que usa la versión de destino correcta de .NET Framework. Abra el menú contextual (botón derecho) del proyecto HelloWorld en el Explorador de soluciones y elija Propiedades. Compruebe que está seleccionado .NET Framework 4 en el cuadro desplegable Versión de .NET Framework de destino.

Ahora que ha configurado el proyecto y que ha creado una referencia a la API administrada EWS, está listo para crear su primera aplicación. Para simplificar las cosas, agregue el código al archivo Program.cs. Consulte Hacer referencia al ensamblado de la API administrada de EWS para obtener más información sobre cómo hacer referencia a la API administrada EWS. En el paso siguiente, desarrollará el código básico para escribir la mayoría de las aplicaciones cliente de la API administrada de EWS.]

Paso 3: configurar la validación del redireccionamiento de la dirección URL para la Detección automática

Agregue el siguiente método de devolución de llamada para la validación del redireccionamiento después del método Main(string[] args). Esto valida si las direcciones URL redirigidas que devuelve la Detección automática representan un extremo 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;
}

Esta devolución de llamada de validación se pasará al objeto ExchangeService en el paso 4. Esto es necesario para que la aplicación confíe y siga los redireccionamientos de la Detección automática, ya que los resultados del redireccionamiento de la Detección automática proporcionan el extremo EWS para nuestra aplicación.

Paso 4: preparar el objeto ExchangeService

Agregue una referencia de directiva using a la API administrada EWS. Agregue el código siguiente después de la última directiva using en la parte superior de Program.cs.
```
 using Microsoft.Exchange.WebServices.Data;
```
En el método Main, cree una instancia del objeto ExchangeService con la versión del servicio que quiere tener como destino. En este ejemplo el destino es la versión más antigua del esquema EWS.
```
 ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2007_SP1);
```
Si tiene como destino un servidor de Exchange local y el cliente está unido al dominio, vaya al paso 4. Si el cliente tiene como destino un buzón del sitio para desarrolladores de Exchange Online u Office 365, deberá pasar credenciales explícitas. Agregue el código siguiente después de crear instancias del objeto ExchangeService y establezca las credenciales de su cuenta de buzón. El nombre de usuario debe ser el nombre principal del usuario. Vaya al paso 5.
```
 service.Credentials = new WebCredentials("user1@contoso.com", "password");
```
Los clientes unidos al dominio que tengan como destino un servidor de Exchange local pueden usar las credenciales predeterminadas del usuario que haya iniciado sesión, siempre y cuando dichas credenciales estén asociadas con un buzón. Agregue el código siguiente después de crear instancias del objeto ExchangeService.
```
 service.UseDefaultCredentials = true;
```
Si el cliente tiene como destino un buzón del sitio para desarrolladores de Exchange Online u Office 365, compruebe que UseDefaultCredentials esté establecido en false, que es el valor predeterminado. El cliente está listo para realizar la primera llamada al servicio Detección automática para obtener la dirección URL del servicio para realizar llamadas al servicio EWS.
El método AutodiscoverUrl del objeto ExchangeService realiza una serie de llamadas al servicio Detección automática para obtener la dirección URL del servicio. Si esta llamada de método se realiza correctamente, la propiedad URL del objeto ExchangeService se establecerá con la dirección URL del servicio. Pase la dirección de correo electrónico del usuario y el objeto RedirectionUrlValidationCallback al método AutodiscoverUrl. Agregue el código siguiente después de especificar las credenciales en el paso 3 o 4. Cambie user1@contoso.com a la dirección de correo electrónico para que el servicio Detección automática encuentre el punto de conexión de EWS.
```
 service.AutodiscoverUrl("user1@contoso.com", RedirectionUrlValidationCallback);
```

En este momento, el cliente está configurado para hacer llamadas a EWS para tener acceso a los datos del buzón. Si ejecuta ahora el código, comprobará que la llamada de método AutodiscoverUrl funcionó si examina el contenido de la propiedad ExchangeService.Url. Si esta propiedad contiene una dirección URL, la llamada se ha realizado correctamente. Esto significa que la aplicación se autenticó correctamente con el servicio y que detectó el extremo EWS de su buzón. Ahora ya puede realizar las primeras llamadas a EWS. Consulte Establecer la dirección URL del servicio EWS usando la API administrada de EWS para obtener más información sobre cómo configurar la dirección URL de EWS.

Paso 6: crear el primer mensaje de correo electrónico de Hola a todos

Después de la llamada de método AutodiscoverUrl, cree una instancia de un nuevo objeto EmailMessage y pase el objeto de servicio que ha creado.
```
 EmailMessage email = new EmailMessage(service);
```
Ahora tiene un mensaje de correo electrónico en el que se ha establecido el enlace al servicio. Todas las llamadas iniciadas en el objeto EmailMessage tendrán el servicio como destino.
Ahora establezca el destinatario de la línea Para: del mensaje de correo electrónico. Para ello, cambie user1@contoso.com para usar la dirección SMTP.
```
 email.ToRecipients.Add("user1@contoso.com");
```

Establezca el asunto y el cuerpo del mensaje de correo electrónico.

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

Ya está listo para enviar su primer mensaje de correo electrónico mediante la API administrada EWS. El método Send llamará al servicio y enviará el mensaje de correo electrónico para su entrega. Consulte Comunicarse con EWS mediante la API administrada de EWS para obtener información sobre otros métodos para comunicarse con Exchange.
```
 email.Send();
```
Ya puede ejecutar la aplicación Hola a todos. En Visual Studio, seleccione F5. Se abrirá una ventana de consola en blanco. No verá nada en la ventana de consola mientras la aplicación se autentique, siga los redireccionamientos de Detección automática y realice su primera llamada para crear un mensaje de correo electrónico que usted se enviará a sí mismo. Si quiere ver las llamadas que se realizan, agregue las dos líneas de código siguientes antes de llamar al método AutodiscoverUrl. Después, presione F5. De este modo, se realizará un seguimiento de las solicitudes y respuestas de EWS en la ventana de consola.
```
 service.TraceEnabled = true;
 service.TraceFlags = TraceFlags.All;
```

Ahora ya tiene una aplicación cliente activa de la API administrada EWS. Para su comodidad, en el ejemplo siguiente se muestra todo el código que agregó en Program.cs para crear la aplicación Hola a todos.

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

Pasos siguientes

Si quiere ir más allá con su primera aplicación cliente de la API administrada EWS, explore los siguientes recursos:

Si surge algún problema con la aplicación envíe una pregunta o un comentario al foro (y no olvide leer la publicación de más arriba).

Compartir a través de