Thursday, September 1, 2016

EWS: Basic references

EWS Managed API

I've been working with EWS over the last few months and I've amassed a list of my favorite resources on this topic. I wanted to share this list with the hope that it would save someone time getting accustomed to the technology. One beginner tip- there is EWS and EWS Managed API. Sample code for the two are often listed next to each other and can be confusing for a new programmer. When you see EWS, think SOAP protocol (XML requests and responses), and when you see EWS Managed API, think C# code. The EWS Managed API is available as a NuGet package (Microsoft.Exchange.WebServices) for Visual Studio or by download link, here. Without further ado, I give you my favorite basic resources.

EWS Managed API, EWS, and web services in Exchange
This is a pretty excellent high-level overview of what EWS is, how you can use it, and pointing you to more information on your area of interest.

EWS Best Practices
This is a list of links as well, but it will be updated by the author, whereas this list is not guaranteed to be. It's a great place to start as a beginning and return to when you have a better grip of what EWS is.

Get started with "Hello World!"
So you want to get a summary paragraph and jump right into creating a project? This is the place to start. Although, as soon as you're done, I recommend circling back to the EWS Best Practices 

EWS Managed API reference
This is for the when you're feeling adventurous and are ready to dive a little deeper into exploring the Microsoft.Exchange.WebServices namespace.

Links of Common EWS Questions
This is also, a list of links, but the common questions are here. Watch out, this is an old reference and some articles might be out of date. Once you have an idea of what your question is, or the answer is, check for an updated reference on the web.

EWS Throttling in Exchange
Eventually you might be dealing with load, and this is a must read for learning about throttling for EWS in Exchange.

EWS: Sending a collection of e-mails using CreateItems

Exchange Web Services (EWS) is an API for getting and sending content to an Exchange server. This post will explain how to send a collection of e-mails with one call to EWS, and identify one if it's shortcomings.

First you will need a list of Item objects. In EWS, the Item class is a generic item. Classes such as Appointment, Contact, ContactGroup, EmailMessage, PostItem, and Task all inherit from the Item class. As such, the CreateItems() method can create any object that inherits from the Item class. This example, will demonstrate using EmailMessage objects to create real e-mails.

List<Item> items = new List<Item>();
EmailMessage email_1 = new EmailMessage(_service)
    ToRecipients = { new EmailAddress("") },
    Subject = "Hello",
    Body = "Hello World!"
EmailMessage email_2 = new EmailMessage(_service)
    ToRecipients = { new EmailAddress("") },
    Subject = "Hello 2",
    Body = "Hello World!"


Then, pass the list of Items to the CreateItems() method.

ServiceResponseCollection<ServiceResponse> responseCollection = _service.CreateItems(items, inboxFolder.Id, MessageDisposition.SendOnly, null);

That's it. 

There are limitations on the number of items you will be allowed to send at once due to Exchange server policies on throttling, etc. Next, consider adding an attachment to these e-mails..


Then, if we try to create these e-mails with attachments using the CreateItems call again, this time it will not work. This is because, "under the hood, the workflow for sending emails with attachments is: CreateItem, CreateAttachment, and then SendItem. CreateItems is a batch of CreateItem calls, it doesn't contain the workflow to break out items with attachments" (referencing StackOverflow post)

So, the way to send e-mails with attachments using EWS is one at a time, and the way to send a group of emails without attachments is using CreateItems.


EWS: Throttling policies on bulk operations

Exchange Web Services (EWS) Managed API is a fantastic API that lets you do a whole lot of interesting things from C# code that allows the program to interact with Exchange. EWS has bulk operations, such as CreateItems, that let's a program send up a bundle of items from C# code to be created by the Exchange server.

The downside to this is that the Exchange server has quite a few throttling policies that it imposes on groups or individual accounts. This has the effect of squandering efforts to perform large bulk operations when it exceeds a particular throttling policy. This is because the Exchange throttling policies are like a cop pulling over speeding drivers, they don't let one driver run everyone off the road, rather a connection has to stay within the limits defined by the throttling policies. A grand overview of EWS throttling policies in Exchange 2013 server are outlined here.

This blog post attempts to outline what Exchange 2013 throttling policies might be run into using EWS to perform bulk Mail operation for creating mail items (i.e., just the CreateItems call  to create emails and not dealing with Calendar, Contact, or Meeting items) and how to appropriately change them. Reading up on EWS best practices is highly encouraged so that ramping down throttling policies is not used as an improvement for faulty code. Then, when its decided that its still necessary to fiddle with the throttling polices, definitely read up on the best practices for EWS throttling. The most important point to remember might be that Exchange throttling policies effect not only EWS, but also client connection to the server for other programs like Outlook and ActiveSync. If you're not sure whether Exchange is throttling your program you can check the EWS logs on the Client Access server (CAS) to investigate whether operations are being throttled.

This MSDN article is the most helpful to get started, as it outlines the specific throttling policies that effect EWS in Exchange 2013. The policies below are pulled from that list, with the italicized description from MSDN, followed by an explanation as to why they might come into play using the batch request CreateItems:

  • EwsCutoffBalance
    • MSDN - "Defines the resource consumption limits for EWS user before that user is completely blocked from performing operations on a specific component."
    • The CreateItems call consumes resources on the Client Access server (CAS). When this limit is exceed the server may return errors like "the operation has timed out". From researching EwsCutoffBalance policy further, it seems to be defined by the total number of milliseconds an EWS connection is consuming a specific resource. In other words, if an EWS operation takes longer than the EwsCutoffBalance (in ms), then the operation will time out. 
  • EwsMaxBurst
    • MSDN - "Defines the amount of time that an EWS user can consume an elevated amount of resources before being throttled. This is measured in milliseconds. This value is set separately for each component."
    • This throttling policy is a little bit easier to understand from its name and description. EwsMaxBurst is expressed in milliseconds. This should be less than EwsRechargeRate.
  • EwsRechargeRate
    • MSDN - "Defines the rate at which an EWS user's budget is recharged (budget grows by) during the budget time."
    • This throttling policy is also expressed in milliseconds. When a resource is being throttled by say the EwsMaxBurst or EwsCutoffBalance policy, it will start to recharge at the rate defined by this policy. Presumably, the throttling policy will be "recharged" in the time defined by EwsRechargeRate, but more research and testing needs to be done to be sure.
  • EwsMaxConcurrency
    • MSDN - "
    • Defines the number of concurrent open connections that a specific user can have against an Exchange server that is using EWS at one time. The default value for Exchange 2013 and Exchange Online is 27. 
    • This policy applies to all operations except for streaming notifications.
    • "
    • This policy is worth noting because there may be concurrent connections going on while one is making a call to the CreateItems bulk operation.

The first three policies above are all measured in milliseconds, and should be ordered in this way:
EwsMaxBurst < EwsRechargeRate < EwsCutoffBalance

This has been an intermediate look at what EWS throttling policies should be considered for changing when using the bulk operation CreateItems.