Comparing Exchange Online and Exchange on-premises client programming
Learn about the design considerations for creating an EWS Managed API or EWS client application that works against Exchange Online and Exchange on-premises.
For the most part, clients and the web services in Exchange they target will work the same way regardless of whether the target is an Exchange Online, Exchange Online as part of Office 365, or Exchange on-premises server. There are, however, some exceptions, and you'll want to make sure that your application can handle them. Use the information in this article to help you design your client to target both Exchange Online and Exchange on-premises.
Autodiscover client programming considerations
Autodiscover provides configuration information for Exchange clients. A client application can discover its configuration information in one of three ways, depending on whether the client is targeting Exchange Online or Exchange on-premises.
Table 1. Autodiscover service types and Exchange applicability
| Autodiscover service type | Applies to |
|---|---|
| SOAP Autodiscover |
Exchange Online and versions of Exchange on-premises starting with Exchange 2010 |
| POX Autodiscover |
Exchange Online and versions of Exchange on-premises starting with Exchange 2007 |
| Service connection point (SCP) lookup |
Versions of Exchange on-premises starting with Exchange 2007 |
In addition to the client configuration information, that SOAP and POX Autodiscover also return the Exchange service version and indicate whether the service is hosted by Exchange Online. This information is returned in different elements, depending on the type of Autodiscover you use.
Table 2. Autodiscover elements that return service version and Exchange Online hosting information
| Autodiscover service type | XML element that contains service version | XML element that indicates whether the user has an Exchange Online account |
|---|---|---|
| SOAP Autodiscover |
Setting (SOAP) element with the CasVersion text value. |
Setting (SOAP) element with the UserMSOnline text value. |
| POX Autodiscover |
ServerVersion (POX) |
MicrosoftOnline |
Ensure that your client captures this information so that it can target the feature set that is available on the Exchange server. This can be useful to determine whether your client can expect different behavior based on whether the user's mailbox is located in an Exchange Online or Exchange on-premises organization.
Testing and log files in applications that target Exchange Online
Exchange Online does not provide access to the EWS protocol log files, EWS performance counters, and EWS-related service events that are available on on-premises Exchange servers. Access to these is useful, however, in discovering how your application performs when it interacts with EWS. Make sure that you test your application against a test Exchange on-premise server so that you can optimize its performance. If possible, you can change the throttling settings on your test server to match the throttling settings for Exchange Online, so you can evaluate how your application will behave when it connects to Exchange Online.
Tip
You can use the EWSRelentless tool to perform an EWS load test. You can use this tool with a test server, the EWS protocol logs, EWS performance counters, service events, and the EWS throttling settings to better understand how EWS performs under load.
Throttling settings and Exchange Online
The default values for the EWS throttling settings are different for Exchange Online than they are for Exchange on-premises. Also, you cannot change Exchange Online throttling settings. You can use Exchange Management Shell cmdlets to discover the throttling settings for Exchange on-premises; however, those cmdlets are not enabled for Exchange Online.
Exchange Management Shell cmdlets and configuration settings
A number of cmdlets can directly or indirectly affect the web service APIs in Exchange Online and Exchange on-premises. Cmdlets are not available for the following in Exchange Online:
Throttling settings
Virtual directory settings
Authentication settings
For details about the cmdlets that are available for Exchange Online, see PowerShell cmdlets in Exchange Online. For more about cmdlets that are available for Exchange on-premises, see Exchange 2013 cmdlets.
Client affinity and network load balancers
Most EWS communication does not require that the client participate in maintaining affinity with Exchange. The subscriptions to mailbox events do require that the client provide cookies and other information to maintain affinity with the Exchange server that maintains the queue of mailbox events for a user. Exchange Server 2010 uses the exchangecookie to maintain client affinity across the network load balancers. Exchange Online and versions of Exchange on-premises starting with Exchange 2013 use the X-AnchorMailbox header, X-PreferServerAffinity header, and X-BackEndOverrideCookie cookie to maintain affinity for mailbox notifications.
Authentication
Clients can authenticate with Exchange Online by using either Basic or OAuth. Versions of Exchange on-premises starting with Exchange 2013 use NTLM by default; however, it's possible to configure Exchange on-premises to use Basic authentication as well.
Client latency diagnostics
Exchange Online collects client latency diagnostics if they are reported. This helps Microsoft support troubleshoot connectivity issues with Exchange Online. Exchange on-premises does not collect client latency diagnostics. If your client targets Exchange on-premises, the client can't report latency diagnostics to the server.
Functionality in the EWS Managed API
The EWS Managed API exposes some functionality that is specific to Exchange on-premises, such as service point connection lookup, and some functionality that is specific to Exchange Online, such as client latency reporting. Note that it's possible for some functionality to be implemented in Exchange Online before it is implemented in the EWS Managed API.
The following EWS Managed API functionality is only applicable to Exchange Online:
Client latency reporting
Basic pre-authentication
The ability to request that the RequestId be returned in responses
API features in Exchange Online plans and Exchange Server editions
Different feature sets might be available in different Office 365 and Exchange Online plans, or in the standard and enterprise versions of Exchange Server. Be aware that some API functionality might not be available to your client application depending on the Exchange Online plan or Exchange Server edition that hosts a user's mailbox.
Because feature availability can change, we recommend that you check the Exchange Online plans and Exchange Server editions to evaluate how feature availability might affect your client. You can also design your client to check feature availability by using the GetServiceConfiguration operation or by sending test requests for the operations that implement the features. If the feature isn't available, the response from the server will indicate as such.
Other considerations
You can do the following when targeting Exchange on-premises but not Exchange Online:
Create a client that is installed on the Exchange server.
Install custom transport agents that can affect the delivery and content of messages you create and send with EWS and other clients.
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for