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  
  3.   
  4. ## Load Managed API dll  
  5. Add-Type -Path "C:\Program Files\Microsoft\Exchange\Web Services\1.1\Microsoft.Exchange.WebServices.dll"  
  6.   
  7. ## Set Exchange Version  
  8. $ExchangeVersion = [Microsoft.Exchange.WebServices.Data.ExchangeVersion]::Exchange2010_SP1  
  9.   
  10. ## Create Exchange Service Object 
  11. $service = New-Object Microsoft.Exchange.WebServices.Data.ExchangeService($ExchangeVersion)  
  12.   
  13. ## Set Credentials to use two options are availible Option1 to use explict credentials or Option 2 use the Default (logged On) credentials  
  14.   
  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      
  18.   
  19. #Credentials Option 2  
  20. #service.UseDefaultCredentials = $true  
  21.   
  22. ## Choose to ignore any SSL Warning issues caused by Self Signed Certificates  
  23.   
  24. ## Code From http://poshcode.org/624
    ## Create a compilation environment
    $Provider=New-Object Microsoft.CSharp.CSharpCodeProvider
    $Compiler=$Provider.CreateCompiler()
    $Params=New-Object System.CodeDom.Compiler.CompilerParameters
    $Params.GenerateExecutable=$False
    $Params.GenerateInMemory=$True
    $Params.IncludeDebugInformation=$False
    $Params.ReferencedAssemblies.Add("System.DLL") | Out-Null

    $TASource=@'
      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;
          }
        }
      }
    '@
    $TAResults=$Provider.CompileAssemblyFromSource($Params,$TASource)
    $TAAssembly=$TAResults.CompiledAssembly

    ## We now create an instance of the TrustAll and attach it to the ServicePointManager
    $TrustAll=$TAAssembly.CreateInstance("Local.ToolkitExtensions.Net.CertificatePolicy.TrustAll")
    [System.Net.ServicePointManager]::CertificatePolicy=$TrustAll

    ## end code from http://poshcode.org/624
  25.   
  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  
  27.   
  28. #CAS URL Option 1 Autodiscover  
  29. $service.AutodiscoverUrl("email@domain.com",{$true})  
  30. "Using CAS Server : " + $Service.url   
  31.    
  32. #CAS URL Option 2 Hardcoded  
  33.   
  34. #$uri=[system.URI] "https://casservername/ews/exchange.asmx"  
  35. #$service.Url = $uri    
  36.   
  37. ## Optional section for Exchange Impersonation  
  38.   
  39. #$service.ImpersonatedUserId = new-object Microsoft.Exchange.WebServices.Data.ImpersonatedUserId([Microsoft.Exchange.WebServices.Data.ConnectingIdType]::SmtpAddress, "email@domain.com")  

5 comments:

Tom Phillips said...

Glen,
Thanks for the great info!

I am using Exchange 2007 SP3 and the EWS DLL ver 1.2 on a machine with Poiwershell v2 and the Exchange tools installed on. I was starting with the basics just trying to get things moving with the connection and a basic test. When I execute:

$Calendar = [Microsoft.Exchange.WebServices.Data.Folder]::Bind($service,$folderid)

I get the following error:

Exception calling "Bind" with "2" argument(s): "The request failed. The underlying connection was closed: An unexp
ected error occurred on a send."
At line:1 char:63
+ $Calendar = [Microsoft.Exchange.WebServices.Data.Folder]::Bind <<<< ($service,$folderid)
+ CategoryInfo : NotSpecified: (:) [], MethodInvocationException
+ FullyQualifiedErrorId : DotNetMethodException


I assume I have to be missing something obvious :-)

Please let me know your thoughs...
here is the code I am trying to get functioning, of course with valid user data:

Add-Type -Path "C:\Program Files\Microsoft\Exchange\Web Services\1.2\Microsoft.Exchange.WebServices.dll"
$ExchangeVersion = [Microsoft.Exchange.WebServices.Data.ExchangeVersion]::Exchange2007_SP3
$service = New-Object Microsoft.Exchange.WebServices.Data.ExchangeService($ExchangeVersion)
$creds = New-Object System.Net.NetworkCredential("user@domain.com","password")
$service.Credentials = $creds
[System.Net.ServicePointManager]::ServerCertificateValidationCallback = {$true} #Ignore SSL warning for selfsigned certs
$uri=[system.URI] "https://owa.xxxx.com/ews/exchange.asmx"
$service.Url = $uri
$service.ImpersonatedUserId = new-object Microsoft.Exchange.WebServices.Data.ImpersonatedUserId([Microsoft.Exchange.WebServices.Data.ConnectingIdType]::SmtpAddress, "user@domain.com")

$folderid= new-object Microsoft.Exchange.WebServices.Data.FolderId([Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::Calendar,$MailboxName)
$Calendar = [Microsoft.Exchange.WebServices.Data.Folder]::Bind($service,$folderid)


Glen Scales said...

Hi Tom

There is a bug with Delegates in the Managed API 1.2 so

Remove the line

System.Net.ServicePointManager]::ServerCertificateValidationCallback = {$true}

Add this block in its place

## Code From http://poshcode.org/624
## Create a compilation environment
$Provider=New-Object Microsoft.CSharp.CSharpCodeProvider
$Compiler=$Provider.CreateCompiler()
$Params=New-Object System.CodeDom.Compiler.CompilerParameters
$Params.GenerateExecutable=$False
$Params.GenerateInMemory=$True
$Params.IncludeDebugInformation=$False
$Params.ReferencedAssemblies.Add("System.DLL") | Out-Null

$TASource=@'
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;
}
}
}
'@
$TAResults=$Provider.CompileAssemblyFromSource($Params,$TASource)
$TAAssembly=$TAResults.CompiledAssembly

## We now create an instance of the TrustAll and attach it to the ServicePointManager
$TrustAll=$TAAssembly.CreateInstance("Local.ToolkitExtensions.Net.CertificatePolicy.TrustAll")
[System.Net.ServicePointManager]::CertificatePolicy=$TrustAll

## end code from http://poshcode.org/624

And that should fix it (Make sure you close any existing power shell sessions before testing it)

Tom Phillips said...

thanks, that got me further... now I get
Exception calling "Bind" with "2" argument(s): "The request failed. The remote server returned an error:
(401) Unauthorized."
At line:1 char:63
+ $Calendar = [Microsoft.Exchange.WebServices.Data.Folder]::Bind <<<< ($service,$folderid)
+ CategoryInfo : NotSpecified: (:) [], MethodInvocationException
+ FullyQualifiedErrorId : DotNetMethodException

Glen Scales said...

If you using Impersonation you don't need to specify the Mailbox Name (else it will use delegation)

eg use

$Calendar = [Microsoft.Exchange.WebServices.Data.Folder]::Bind($service,[Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::Calendar)

Cheers
Glen

Sharmistha Sarkar said...

Hi Glen, Will you also help me in using Get-Message Trace or Get-UrlTrace using EWS API