Partager via

  • Article

Getting started with the EWS Managed API 2.0

Last modified: October 13, 2012

Applies to: EWS Managed API | Exchange Server 2007 Service Pack 1 (SP1) | Exchange Server 2010

Note: This content applies to the EWS Managed API 2.0 and earlier versions. For the latest information about the EWS Managed API, see Web services in Exchange.

In this article
Prerequisites
Enable Access to Exchange Web Services
Referencing the EWS Managed API Assembly
Validating X509 Certificates for SSL over HTTP
Connecting to Exchange Web Services
EWS Client Application Example

The EWS Managed API provides user-friendly abstractions of XML messages, XML serialization, and the formation of the HTTP requests and responses that are sent between the client and server. To start programming with the EWS Managed API, you must complete the following tasks:

  1. Enable access to Exchange Web Services for mailbox owners and/or EWS Managed API client applications.

  2. Reference the EWS Managed API assembly.

  3. Validate X509 certificates for SSL over HTTP.

  4. Connect to Exchange Web Services by using the ExchangeService class.

Prerequisites

The following are the prerequisites for programming with the EWS Managed API:

  • A computer that is running Microsoft Exchange Server 2007 Service Pack 1 (SP1) or later versions of Microsoft Exchange Server.

  • The Microsoft .NET Framework version 3.5.

  • The EWS Managed API assembly file, Microsoft.Exchange.WebServices.dll.

  • Visual Studio 2008 with the Visual Web Developer and C# components and an open Visual Studio 2008 solution.

    Or

    A text editor to create and edit source code files and a Command Prompt window to run a .NET Framework command line compiler.

Enable Access to Exchange Web Services

You can control access to Exchange Web Services by configuring access based on the mailbox user who is connecting to the Web service, or by the User-Agent string that is sent by the EWS Managed API application. Before you can use EWS, you must configure access, otherwise the Web service will respond with HTTP 403: Forbidden.

For information about configuring EWS access control, see Managing access for EWS Managed API 2.0 applications.

Referencing the EWS Managed API Assembly

To reference the EWS Managed API assembly by using Visual Studio 2008

  1. Put the Microsoft.Exchange.WebServices.dll file and the Microsoft.Exchange.WebServices.xml file into a folder of your choice.

  2. In the Solution Explorer pane in Visual Studio 2008, right-click References, and then click Add Reference. This opens the Add Reference window.

  3. In the Add Reference window, navigate to the Browse tab, browse to the location of the Microsoft.Exchange.WebServices.dll file, select that file, and then click OK.

  4. To use the EWS Managed API in a Visual Studio 2008 program, add a using statement for the Microsoft.Exchange.WebServices.Data namespace.

    using Microsoft.Exchange.WebServices.Data;

To reference the EWS Managed API assembly by using a source code editor other than Visual Studio 2008 and build the application by using the .NET Framework command-line compiler

  1. Put the Microsoft.Exchange.WebServices.dll file into a folder of your choice. This folder will be the output folder for the compiler.

  2. In the source code editor, add a using statement to the source code for the Microsoft.Exchange.WebServices.Data namespace.

    using Microsoft.Exchange.WebServices.Data;

  3. Run the command-line compiler to build the application. The following command uses the .NET Framework C# compiler to build the Windows application defined in the source code file "program.cs". It assumes that the compiler is located in the default installation directory and that the Microsoft.Exchange.WebServices.dll file is in a subdirectory of the current directory named "build".

    c:\Windows\Microsoft.NET\Framework\3.5\csc /target: winexe /out: build\testApplication /reference: build\Microsoft.Exchange.WebServices.dll program.cs

Validating X509 Certificates for SSL over HTTP

By validating the X509 certificate provided by the computer that is running Exchange 2007 SP1 or Exchange 2010 for SSL over HTTP, you help provide a layer of security for the client application. You must validate certificates before you can start programming with the EWS Managed API. If the callback is not set up, the first call will fail with a certificate error. For information about how to validate certificates, see Validating X509 certificates by using the EWS Managed API 2.0.

Connecting to Exchange Web Services

In the EWS Managed API, the ExchangeService class contains the methods and properties that are used to set user credentials, identify the Exchange Web Services endpoint, send and receive SOAP messages, and configure the connection with Exchange Web Services. To perform an operation by using the EWS Managed API, you must set up the ExchangeService class.

For instructions for setting up the ExchangeService class, see Connecting to EWS by using the EWS Managed API 2.0.

EWS Client Application Example

The following code example shows an EWS client that creates and sends an e-mail message, and saves a copy to the Sent Items (default) folder. This example assumes that you have added a reference to the EWS Managed API assembly by using Visual Studio 2008, as described earlier in this topic.

using System;
using Microsoft.Exchange.WebServices.Data;
using System.Net.Security;
using System.Security.Cryptography.X509Certificates; 

namespace testnamespace
{
    class Program
    {
        static void Main(string[] args)
        {
            // Validate the server certificate.
            // For a certificate validation code example, see the Validating X509 Certificates topic in the Core Tasks section.

            try 
            {
               // Connect to Exchange Web Services as user1 at contoso.com.
               ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2007_SP1);
               service.Credentials = new WebCredentials("user1@contoso.com", "password ");
               service.AutodiscoverUrl("user1@contoso.com");

               // Create the e-mail message, set its properties, and send it to user2@contoso.com, saving a copy to the Sent Items folder. 
               EmailMessage message = new EmailMessage(service);
               message.Subject = "Interesting";
               message.Body = "The proposition has been considered."; 
               message.ToRecipients.Add("user2@contoso.com");
               message.SendAndSaveCopy();

               // Write confirmation message to console window.
               Console.WriteLine("Message sent!");
               Console.ReadLine();
            }
            catch (Exception ex)
            {
               Console.WriteLine("Error: " + ex.Message);
               Console.ReadLine();
            }
        }
    }
}