Empezar a trabajar con aplicaciones de cliente de la API administrada de EWSGet started with EWS Managed API client applications

Desarrolle una sencilla aplicación cliente de correo electrónico Hola a todos para Exchange mediante la API administrada EWS.Develop a simple Hello World email client application for Exchange by using the EWS Managed API.

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.The EWS Managed API provides an intuitive, easy-to-use object model for sending and receiving web service messages from client applications, portal applications, and service applications. You can access almost all the information stored in an Exchange Online, Exchange Online as part of Office 365, or an Exchange server mailbox by using the EWS Managed API. You can use the information in this article to help you develop your first EWS Managed API client application.

Nota

La API administrada EWS ya está disponible como proyecto de código abierto en GitHub.The EWS Managed API is now available as an open source project on GitHub. Puede usar la biblioteca de código abierto para:You can use the open source library to:

  • Contribuir con correcciones de errores y mejoras a la API.Contribute bug fixes and enhancements to the API.
  • Obtener correcciones y mejoras antes de que estén disponibles en una versión oficial.Get fixes and enhancements before they are available in an official release.
  • 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.Access the most comprehensive and up-to-date implementation of the API, to use as a reference or to create new libraries on new platforms.

Le agradecemos las aportaciones que realice a través de GitHub.We welcome your contributions via GitHub.

Necesitará un servidor de ExchangeYou'll need an Exchange server

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:If you already have an Exchange mailbox account, you can skip this section. Otherwise, you have the following options for setting up an Exchange mailbox for your first EWS client application:

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.After you have verified that you can send and receive email from Exchange, you are ready to set up your development environment. You can use the Exchange web client Outlook Web App to verify that you can send email.

Configurar el entorno de desarrolloSet up your development environment

Asegúrese de que tiene acceso a los siguientes elementos:Make sure that you have access to the following:

  • 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.Any version of Visual Studio that supports the .NET Framework 4. Although technically, you don't need Visual Studio because you can use any C# compiler, we recommend that you use it.

  • 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.The EWS Managed API. You can use either the 64-bit or 32-bit version, depending on your system. Use the default installation location.

Crear la primera aplicación de API administrada EWSCreate your first EWS Managed API application

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.These steps assume that you set up an Office 365 Developer Site. If you downloaded and installed Exchange, you will need to install a valid certificate on your Exchange server or implement a certificate validation callback for a self-signed certificate that is provided by default. Also note that these steps might vary slightly depending on the version of Visual Studio that you are using.

Paso 1: crear un proyecto en Visual StudioStep 1: Create a project in Visual Studio

  1. En Visual Studio, en el menú Archivo, seleccione Nuevo y después elija Proyecto. Se abre el cuadro de diálogo Nuevo proyecto.In Visual Studio, on the File menu, choose New, and then choose Project. The New Project dialog box opens.

  2. Cree una aplicación de consola de C#. En el panel Plantillas, elija Visual C# y luego Aplicación de consola.Create a C# Console Application. From the Templates pane, choose Visual C#, and then choose Console Application.

  3. Indique HelloWorld como nombre del proyecto y después elija Aceptar.Name the project HelloWorld, and then choose OK.

Visual Studio crea el proyecto y abre la ventana de documento de código Program.cs.Visual Studio creates the project and opens the Program.cs code document window.

Paso 2: agregar una referencia a la API administrada EWSStep 2: Add a reference to the EWS Managed API

  1. 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.If the Solution Explorer window is already open, skip this step and proceed to step 2. To open the Solution Explorer window, on the View menu, choose Solution Explorer.

  2. 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.In the Solution Explorer and the HelloWorld project, open the shortcut menu (right-click) for References and choose Add Reference from the context menu. A dialog box for managing project references will open.

  3. Elija la opción Examinar.Choose the Browse option. Vaya a la ubicación donde instaló el archivo DLL de la API administrada EWS.Browse to the location where you installed the EWS Managed API DLL. La ruta de acceso predeterminada establecida por el instalador es la siguiente: C:\Archivos de Files\Microsoft\Exchange\Web Services<version>.The default path set by the installer is the following: C:\Program Files\Microsoft\Exchange\Web Services<version>. 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.The path can vary based on whether you download the 32 or 64 bit version of the Microsoft.Exchange.WebServices.dll. Elija Microsoft.Exchange.WebServices.dll y seleccione Aceptar o Agregar.Choose Microsoft.Exchange.WebServices.dll and select OK or Add. Esto agrega la referencia de la API administrada EWS a su proyecto.This adds the EWS Managed API reference to your project.

  4. 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.If you are using EWS Managed API 2.0, change the HelloWorld project to target the .NET Framework 4. Other versions of the EWS Managed API might use a different target version of the .NET Framework.

  5. 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.Confirm that you are using the correct target version of the .NET Framework. Open the shortcut menu (right-click) for your HelloWorld project in the Solution Explorer, and choose Properties. Verify that the .NET Framework 4 is selected in the Target framework drop-down box.

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.Now that you have your project set up and you created a reference to the EWS Managed API, you are ready to create your first application. Para simplificar las cosas, agregue el código al archivo Program.cs.To keep things simple, add your code to the Program.cs file. 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.Read Reference the EWS Managed API assembly for more information about referencing the EWS Managed API. En el paso siguiente, desarrollará el código básico para escribir la mayoría de las aplicaciones cliente de la API administrada EWS.In the next step, you will develop the basic code to write most EWS Managed API client applications.

Paso 3: configurar la validación del redireccionamiento de la dirección URL para la Detección automáticaStep 3: Set up URL redirection validation for Autodiscover

  • 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.Add the following redirection validation callback method after the Main(string[] args) method. This validates whether redirected URLs returned by Autodiscover represent an HTTPS endpoint.

    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.This validation callback will be passed to the ExchangeService object in step 4. You need this so that your application will trust and follow Autodiscover redirects - the results of the Autodiscover redirect provides the EWS endpoint for our application.

Paso 4: preparar el objeto ExchangeServiceStep 4: Prepare the ExchangeService object

  1. 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.Add a using directive reference to the EWS Managed API. Add the following code after the last using directive at the top of Program.cs.

     using Microsoft.Exchange.WebServices.Data;
    
  2. 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.In the Main method, instantiate the ExchangeService object with the service version you intend to target. This example targets the earliest version of the EWS schema.

     ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2007_SP1);
    
  3. 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.If you are targeting an on-premises Exchange server and your client is domain joined, proceed to step 4. If you client is targeting an Exchange Online or Office 365 Developer Site mailbox, you have to pass explicit credentials. Add the following code after the instantiation of the ExchangeService object and set the credentials for your mailbox account. The user name should be the user principal name. Proceed to step 5.

     service.Credentials = new WebCredentials("user1@contoso.com", "password");
    
  4. 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.Domain-joined clients that target an on-premises Exchange server can use the default credentials of the user who is logged on, assuming the credentials are associated with a mailbox. Add the following code after the instantiation of the ExchangeService object.

     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.If your client targets an Exchange Online or Office 365 Developer Site mailbox, verify that UseDefaultCredentials is set to false, which is the default value. Your client is ready to make the first call to the Autodiscover service to get the service URL for calls to the EWS service.

  5. 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 su dirección de correo electrónico de modo que el servicio Detección automática encuentre su extremo EWS.The AutodiscoverUrl method on the ExchangeService object performs a series of calls to the Autodiscover service to get the service URL. If this method call is successful, the URL property on the ExchangeService object will be set with the service URL. Pass the user's email address and the RedirectionUrlValidationCallback to the AutodiscoverUrl method. Add the following code after the credentials have been specified in step 3 or 4. Change user1@contoso.com to your email address so that the Autodiscover service finds your EWS endpoint.

     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.At this point, your client is set up to make calls to EWS to access mailbox data. Si ejecuta ahora el código, comprobará que la llamada de método AutodiscoverUrl funcionó si examina el contenido de la propiedad ExchangeService.Url.If you run your code now, you can verify that the AutodiscoverUrl method call worked by examining the contents of the ExchangeService.Url property. Si esta propiedad contiene una dirección URL, la llamada se ha realizado correctamente.If this property contains a URL, your call was a success! Esto significa que la aplicación se autenticó correctamente con el servicio y que detectó el extremo EWS de su buzón.This means that your application successfully authenticated with the service and discovered the EWS endpoint for your mailbox. Ahora ya puede realizar las primeras llamadas a EWS.Now you are ready to make your first calls to 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.Read Set the EWS service URL by using the EWS Managed API for more information about setting the EWS URL.

Paso 6: crear el primer mensaje de correo electrónico de Hola a todosStep 6: Create your first Hello World email message

  1. 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.After the AutodiscoverUrl method call, instantiate a new EmailMessage object and pass in the service object you created.

     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.You now have an email message on which the service binding is set. Any calls initiated on the EmailMessage object will be targeted at the service.

  2. Ahora establezca el destinatario de la línea Para: del mensaje de correo electrónico. Para ello, cambie user1@contoso.com y use su dirección SMTP.Now set the To: line recipient of the email message. To do this, change user1@contoso.com to use your SMTP address.

     email.ToRecipients.Add("user1@contoso.com");
    
  3. Establezca el asunto y el cuerpo del mensaje de correo electrónico.Set the subject and the body of the email message.

     email.Subject = "HelloWorld";
     email.Body = new MessageBody("This is the first email I've sent by using the EWS Managed API.");
    
  4. Ya está listo para enviar su primer mensaje de correo electrónico mediante la API administrada EWS.You are now ready to send your first email message by using the EWS Managed API. El método Send llamará al servicio y enviará el mensaje de correo electrónico para su entrega.The Send method will call the service and submit the email message for delivery. Consulte Comunicarse con EWS mediante la API administrada de EWS para obtener información sobre otros métodos para comunicarse con Exchange.Read Communicate with EWS by using the EWS Managed API to learn about other methods you can use to communicate with Exchange.

     email.Send();
    
  5. 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.You are ready to run your Hello World application. In Visual Studio, select F5. A blank console window will open. You will not see anything in the console window while your application authenticates, follows Autodiscover redirections, and then makes its first call to create an email message that you send to yourself. If you want to see the calls being made, add the following two lines of code before the AutodiscoverUrl method is called. Then press F5. This will trace out the EWS requests and responses to the console window.

     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.You now have a working EWS Managed API client application. For your convenience, the following example shows all the code that you added to Program.cs to create your Hello World application.

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

Siguientes pasosNext steps

Si quiere ir más allá con su primera aplicación cliente de la API administrada EWS, explore los siguientes recursos:If you're ready to do more with your first EWS Managed API client application, explore the following resources:

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).If you run into any issues with your application, try posting a question or comment in the forum (and don't forget to read the top post).

En esta secciónIn this section

Vea tambiénSee also