Artikkeli
09/29/2014

Get started with EWS Managed API 2.0 client applications

Develop a simple Hello World email client application by using the EWS Managed API.

Last modified: December 05, 2013

Applies to: EWS Managed API | 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
Set up your EWS Managed API development environment
What can you do with the EWS Managed API?
Beyond the basics: Learn more about the EWS Managed API
Additional resources

You can use the EWS Managed API to create client applications that target Exchange Web Services (EWS). The EWS Managed API provides an intuitive, easy-to-use object model for sending and receiving web service messages. You can access nearly all the information stored in an Exchange mailbox by using the EWS Managed API.

Note

The EWS Managed API is now available as an open source project on GitHub. You can use the open source library to:

Contribute bug fixes and enhancements to the API.
Get fixes and enhancements before they are available in an official release.
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.

We welcome your contributions via GitHub.

Set up your EWS Managed API development environment

To create an EWS Managed API client application, make sure that you have the following:

A version of the EWS Managed API. This example will work with all versions of the EWS Managed API. Note that we are using the Exchange_2007SP1 schema version as that is the earliest shared service version.
A mailbox on an Exchange server that is running a version of Exchange starting with Exchange Server 2007, including Exchange Online. You must have the user name and credentials of the account. By default, direct EWS access is enabled for all Exchange Online plans except for the Kiosk plan.
A version of Visual Studio starting with Visual Studio 2005. In this example, we use Visual Studio 2010. If you don’t have Visual Studio installed, you can download Visual C# 2010 Express.
A version of the .NET Framework starting with the .NET Framework 3.5.
Familiarity with C#.

What can you do with the EWS Managed API?

You can use the EWS Managed API to perform many tasks related to the information that is stored in an Exchange mailbox. We'll start by showing you how to use the EWS Managed API to create a simple Hello World email application.

The following table summarizes the basic tasks that you have to complete to create an EWS Managed API client application.

Table 1: Basic tasks for creating an EWS Managed API client

Task	Description
Validate X509 certificates	Your Exchange server might use self-signed certificates. To make sure that your application trusts the server, you have to validate the server certificate. For more information, see Validating X509 certificates by using the EWS Managed API 2.0.
Version your EWS requests	The request version is used to identify the service version that your application targets. For more information, see Versioning EWS requests by using the EWS Managed API 2.0.
Set the Exchange service URL	You need to get the EWS service endpoint. For more information, see Setting the Exchange service URL by using the EWS Managed API 2.0.
Set the ExchangeService object	The ExchangeService object contains the core functionality for communicating with the Exchange server. It handles all the XML serialization/deserialization into objects, cookies, headers, logging, and other core communication tasks.

Step 1: Create a project for your first EWS Managed API client application

Start Visual Studio. On the File menu, choose New Project. The New Project dialog box opens.

Note

These steps might vary slightly if you are using a version of Visual Studio other than Visual Studio 2010.
From the Installed Templates pane, choose Visual C#, and then choose Console Application.
Name the project HelloWorld, and then choose OK.
Visual Studio creates the project and opens the Program.cs code document window.

Step 2: Add a reference to the EWS Managed API

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.
In the Solution Explorer and the HelloWorld project, right-click References and choose Add Reference from the context menu. The Add Reference dialog box opens.
Choose the Browse tab. Browse to the location where you installed the EWS Managed API dll. For this example, the path is the following: C:\Program Files\Microsoft\Exchange\Web Services\1.2\. The path will vary based on whether you download the 32 or 64 bit version of the Microsoft.Exchange.WebServices.dll. Choose Microsoft.Exchange.WebServices.dll and select OK. This adds the EWS Managed API reference to your project.
If you are using the EWS Managed API 1.2.1 or EWS Managed API 2.0, change the HelloWorld project to target the .NET Framework 4.

Now that you have your project set up and a reference to the EWS Managed API, you are ready to create your first application. To keep things simple, we will add our code to the Program.cs file. In the next step, we will develop the basic code to write most EWS Managed API client applications.

Step 3: Set up certificate validation

Versions of Exchange starting with Exchange 2007 Service Pack 1 (SP1), including Exchange Online, use self-signed X509 certificates to authenticate calls to the EWS client. You have to set up a certificate validation callback method in order for calls to your Exchange server to succeed.

Include references to the .NET Framework namespaces. Add the following references to the top of Program.cs.

using System.Net;
using System.Net.Security;
using System.Security.Cryptography.X509Certificates;

Create a certificate validation callback method. Add the following code in Program.cs after the Main(string[] args) method.

private static bool CertificateValidationCallBack(
object sender,
System.Security.Cryptography.X509Certificates.X509Certificate certificate,
System.Security.Cryptography.X509Certificates.X509Chain chain,
System.Net.Security.SslPolicyErrors sslPolicyErrors)
{
   // If the certificate is a valid, signed certificate, return true.
   if (sslPolicyErrors == System.Net.Security.SslPolicyErrors.None)
   {
      return true;
   }

   // If there are errors in the certificate chain, look at each error to determine the cause.
   if ((sslPolicyErrors & System.Net.Security.SslPolicyErrors.RemoteCertificateChainErrors) != 0)
   {
      if (chain != null && chain.ChainStatus != null)
      {
         foreach (System.Security.Cryptography.X509Certificates.X509ChainStatus status in chain.ChainStatus)
         {
            if ((certificate.Subject == certificate.Issuer) &&
               (status.Status == System.Security.Cryptography.X509Certificates.X509ChainStatusFlags.UntrustedRoot))
            {
               // Self-signed certificates with an untrusted root are valid. 
               continue;
            }
            else
            {
               if (status.Status != System.Security.Cryptography.X509Certificates.X509ChainStatusFlags.NoError)
               {
                  // If there are any other errors in the certificate chain, the certificate is invalid,
                  // so the method returns false.
                  return false;
               }
            }
         }
      }

      // When processing reaches this line, the only errors in the certificate chain are 
      // untrusted root errors for self-signed certificates. These certificates are valid
      // for default Exchange server installations, so return true.
      return true;
   }
   else
   {
      // In all other cases, return false.
      return false;
   }
}

Add your certificate validation callback method to the ServicePointManager by adding the following code to the beginning of the Main(string[] args) method. This callback has to be available before you make any calls to the EWS end point.
```
ServicePointManager.ServerCertificateValidationCallback = CertificateValidationCallBack;
```

You now have a client that can trust an Exchange server that has self-signed certificate.

Step 4: Set up URL redirection validation

Add the following redirection validation callback method after the Main(string[] args) method. This validates whether the redirected URL is using Transport Layer Security.

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

This validation callback will be passed to the ExchangeService object in the step 5.

Step 5: Prepare the ExchangeService object

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;
```
In the Main method, after the CertificateValidationCallback is added to the ServicePointManager, instantiate the ExchangeService object with the service version you intend to target. In this example, we target the earliest version of the EWS schema.
```
ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2007_SP1);
```
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 service, 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.
```
service.Credentials = new WebCredentials("user1@contoso.com", "password");
```
Domain-joined clients that target an on-premise 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;
```
Your client is ready to make the first call to the Autodiscover service to get the service URL for calls to the EWS service.
The AutodiscoverUrl method on the ExchangeService object performs a call to the Autodiscover service to get the service URL. If this call is successful, the URL property on the ExchangeService object will be set with the service URL. Pass the user principal name and the RedirectionUrlValidationCallback to the AutodiscoverUrl method. Add the following code after the credentials have been specified in step 4 or 5.
```
service.AutodiscoverUrl("user1@contoso.com", RedirectionUrlValidationCallback);
```

At this point, your client is set up to make calls to EWS to access mailbox data.

Step 6: Create your first Hello World email message

After the AutodiscoverUrl method call, instantiate a new EmailMessage object and pass in the service object you created.
```
EmailMessage email = new EmailMessage(service);
```
You now have an email message instantiated on the client on which the service binding is set. Any calls initiated on the EmailMessage object will be targeted at the service.
Now set the To: line recipient of the email message. For this example, use your your SMTP address.
```
email.ToRecipients.Add("user1@contoso.com");
```

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

You are now ready to send your first email message by using the EWS Managed API. The Send method will call the service and submit the email message for delivery.
```
email.Send();
```
You are ready to run your Hello World application. 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. If you want to see the actual calls being made, add the following two lines of code before the AutodiscoverUrl method is called.
```
service.TraceEnabled = true;
service.TraceFlags = TraceFlags.All;
```
For information about how to capture the calls into a file, see Tracing EWS requests by using the EWS Managed API 2.0.

You now have a working EWS Managed API client application. For your convenience, the following example shows all the code that you added to create your Hello World application.

static void Main(string[] args)
{
   ServicePointManager.ServerCertificateValidationCallback = CertificateValidationCallBack;
   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();
}

Beyond the basics: Learn more about the EWS Managed API

This article shows you how to create your first EWS Managed API client application. You can now start using EWS to access your mailbox data. You can continue to expand your client application and perform specific tasks by using the EWS Managed API. To learn more, see the resources listed in the following table.

Table 3: Advanced concepts for working with the EWS Managed API

Article	Description
EWS Managed API 2.0 application debugging	Provides information about how to capture the XML traces produced by the client.
ExchangeService	Describes the core class for sending and receiving information from the EWS Managed API and Exchange.
EWS Managed API 2.0 security	Describes basic security considerations for your client application.

Jaa