Tuesday, January 10, 2012

EWS Managed API and Powershell How-To series Part 1

I thought I'd start the year with a series of posts that goes back over the basics of using the EWS Managed API from Powershell and provides a modular remarked example that you can easily cut and paste to build your own scripts. Along the way in this series I'll show a whole bunch of examples around specific things.

As a starting point for versions this will be Powershell Version 2.0  and the EWS Managed API 1.1 (which will soon change to 1.2 once released) http://www.microsoft.com/download/en/details.aspx?id=13480.

The starting point for any EWS script your going to write is connecting to Exchange for which there are three important pieces of information you will need. Firstly you need to know the version of Exchange your running in this script its going to be held in the following variable

$ExchangeVersion = [Microsoft.Exchange.WebServices.Data.ExchangeVersion]::Exchange2010_SP1

Other valid values for Exchange 2007 would be

$ExchangeVersion = [Microsoft.Exchange.WebServices.Data.ExchangeVersion]::Exchange2007_SP1

The next thing you need to know is what security credentials your going to use to connect to the Mailbox you want to access. There are two options available for this you can specify the credentials in your code (or prompt for them using Get-Credential). Or the other option is to use the default logged on user credentials (or from a scheduled task etc).

The last thing piece of information you need is the URL to the CAS (Client Access Server) you are going to send the EWS requests through which you can find using Autodiscover if this is setup or you can hard code the URL of a CAS server to use. One word of note with Auto-discover and the Managed API is by default it will first perform a SCP look-up of Active Directory to find the Autodiscover EndPoint and if that fails it will then perform a DNS lookup. If you want more control over this process have a look at another script I've posted http://gsexdev.blogspot.com/2011/07/using-autodiscover-in-powershell-with.html.

The last optional section in the connectivity script is an option to use EWS Impersonation this allows you to access another users mailbox with the effective security credentials of the owner of that mailbox. EWS Impersonation is configured via RBAC on 2010 see http://msdn.microsoft.com/en-us/library/bb204095%28v=exchg.140%29.aspx. For more information on impersonation see http://blogs.msdn.com/b/exchangedev/archive/2009/06/15/exchange-impersonation-vs-delegate-access.aspx

Thats about it from a connectivity and security perspective in the next post I'll go over folders inside and out. I've posted a copy of the connectivity script here the script itself looks like.

  1. ## EWS Managed API Connect Script
  2. ## Requires the EWS Managed API and Powershell V2.0 or greator  
  4. ## Load Managed API dll  
  5. Add-Type -Path "C:\Program Files\Microsoft\Exchange\Web Services\1.1\Microsoft.Exchange.WebServices.dll"  
  7. ## Set Exchange Version  
  8. $ExchangeVersion = [Microsoft.Exchange.WebServices.Data.ExchangeVersion]::Exchange2010_SP1  
  10. ## Create Exchange Service Object 
  11. $service = New-Object Microsoft.Exchange.WebServices.Data.ExchangeService($ExchangeVersion)  
  13. ## Set Credentials to use two options are availible Option1 to use explict credentials or Option 2 use the Default (logged On) credentials  
  15. #Credentials Option 1 using UPN for the windows Account  
  16. $creds = New-Object System.Net.NetworkCredential("user@domain.com","password")   
  17. $service.Credentials = $creds      
  19. #Credentials Option 2  
  20. #service.UseDefaultCredentials = $true  
  22. ## Choose to ignore any SSL Warning issues caused by Self Signed Certificates  
  24. ## Code From http://poshcode.org/624
    ## Create a compilation environment
    $Provider=New-Object Microsoft.CSharp.CSharpCodeProvider
    $Params=New-Object System.CodeDom.Compiler.CompilerParameters
    $Params.ReferencedAssemblies.Add("System.DLL") | Out-Null

      namespace Local.ToolkitExtensions.Net.CertificatePolicy{
        public class TrustAll : System.Net.ICertificatePolicy {
          public TrustAll() {
          public bool CheckValidationResult(System.Net.ServicePoint sp,
            System.Security.Cryptography.X509Certificates.X509Certificate cert,
            System.Net.WebRequest req, int problem) {
            return true;

    ## We now create an instance of the TrustAll and attach it to the ServicePointManager

    ## end code from http://poshcode.org/624
  26. ## Set the URL of the CAS (Client Access Server) to use two options are availbe to use Autodiscover to find the CAS URL or Hardcode the CAS to use  
  28. #CAS URL Option 1 Autodiscover  
  29. $service.AutodiscoverUrl("email@domain.com",{$true})  
  30. "Using CAS Server : " + $Service.url   
  32. #CAS URL Option 2 Hardcoded  
  34. #$uri=[system.URI] "https://casservername/ews/exchange.asmx"  
  35. #$service.Url = $uri    
  37. ## Optional section for Exchange Impersonation  
  39. #$service.ImpersonatedUserId = new-object Microsoft.Exchange.WebServices.Data.ImpersonatedUserId([Microsoft.Exchange.WebServices.Data.ConnectingIdType]::SmtpAddress, "email@domain.com")