Get started with EWS Managed API 2.0 client applications

1. 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.

2. From the Installed Templates pane, choose Visual C#, and then choose Console Application.

3. Name the project HelloWorld, and then choose OK.

4. Visual Studio creates the project and opens the Program.cs code document window.

1. 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. 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.

3. 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.

4. 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.

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

2. 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.

• 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.

1. 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. 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);
   

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

4. 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.

5. 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.

1. 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.

2. Now set the To: line recipient of the email message. For this example, use your your SMTP address.

   email.ToRecipients.Add("user1@contoso.com");
   

3. 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. 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();
   

5. 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();
}