EWS client design overview for Exchange
Learn about the design considerations for developing with EWS for Exchange.
Last modified: February 24, 2014
Applies to: Exchange Online | Exchange Server 2013 | Office 365
This article provides overview information about designing an Exchange Web Services (EWS) application. You can use this information to determine whether EWS is the right API for your application, and if so, what type of client implementation you should use. This article also provides best practice information for designing applications that can target Exchange Online, Exchange Online as part of Office 365, and versions of Exchange starting with Exchange 2007, in one code base, and important decision points for targeting on-premises Exchange servers versus targeting Exchange Online.
Before you begin to design your application, it is important to consider whether EWS is the right API for you. If you are developing against Exchange Server or Exchange Online, EWS is the preferred client access technology. Client access development for versions of Exchange starting with Exchange 2007 has primarily been focused on EWS. New client access functionality that is implemented in Outlook uses EWS, including the Out of Office (OOF) and Availability features introduced in Exchange 2007, and the MailTips and Get Rooms functionality introduced in Exchange 2010. This represents a committed investment in EWS for both internal and external partners who develop Exchange client applications.
EWS is the primary client access API for your Exchange client applications. However, in some cases, you might consider other Exchange APIs for client application development. For example, Exchange ActiveSync provides the following advantages over EWS:
The XML structure has been tokenized to make Exchange ActiveSync a more compact protocol.
Exchange ActiveSync contains a policy mechanism to control client access and to provide other robust enterprise mobile messaging solutions.
You need a license in order to develop Exchange ActiveSync clients. For more information, see Exchange ActiveSync Protocol. To learn about the differences between Exchange ActiveSync and EWS, see Choosing between Exchange ActiveSync and Exchange Web Services (EWS).
MAPI RPC over HTTP is another programmability option for Exchange client applications. However, MAPI RPC over HTTP does not provide an intuitive interface for communicating between clients and the server.
Several options are available for developing against Exchange by using EWS. The best option for you will depend on the development platform, tools, available implementations, and application requirements for your organization. The following are the four primary options that are available for building EWS client applications:
The EWS Managed API
The EWS Java API
The EWS autogenerated proxies
A custom EWS client API
EWS Managed API
The EWS Managed API is a custom web service client. It is the standard client access API for .NET Framework applications.
The following are some of the benefits of using the EWS Managed API:
It provides an intuitive object model.
It abstracts the complexities of the service description in the WSDL and schema files.
It includes client-side business logic.
It handles the web requests and responses and object serialization and deserialization.
It is Microsoft-supported.
Note, however, that the EWS Managed API is not a complete solution. Some functionality is not implemented in the EWS Managed API. Although the EWS Managed API doesn’t implement all EWS functionality, it might be the best choice for your client application development, for the following reasons:
You can use the .NET Framework for development.
It implements Autodiscover in addition to most parts of the EWS object model.
It implements client-side business logic for working with EWS, in the ExchangeService class.
You might choose to use the EWS web service API instead of the EWS Managed API for any of the following reasons:
Your application does not use the .NET Framework.
You don’t want to distribute the EWS Managed API assembly.
Your application uses features that aren’t implemented in the EWS Managed API.
To learn more, see Get started with EWS Managed API client applications.
EWS Java API
The EWS Java API is a Java port of the EWS Managed API. The EWS Java API is not updated at the same time that the EWS Managed API is updated. However, the source code is available so that you can extend the API. Although the EWS Java API is not supported, the XML that is sent from and received by the API is supported.
EWS autogenerated proxies
Autogenerated client APIs are generated from the EWS WSDL and XML schema definitions. Client object model generators are available for many languages. In general, the autogenerated object models manage object serialization and deserialization. They do not include business logic and the autogeneration process often creates artifacts that make the object model less intuitive to use. Exchange support covers the XML that is sent and received by the client but not the object model.
Custom EWS client API
For some applications that use a small set of EWS functionality, you might create a custom client API to communicate with Exchange. This enables you to consume fewer system resources. This is useful for clients that run on memory-constrained devices, such as clients running the .NET Micro Framework.
Regardless of the development option that you choose, you should consider how EWS features are implemented in your client. Feature availability is based on the EWS schema version that your application targets. Because EWS schemas are backward- and forward-compatible, if you create an application that targets an earlier schema version, such as Exchange Server 2007 SP1, your application will also work against a later schema version, such as the Exchange Server 2013 SP1 service, as well as Exchange Online.
Because features and feature updates are driven by the schema, we recommend that you use the earliest common code base that targets the EWS features that you want to implement in your client application. Many applications can target the Exchange2007_SP1 version, because the Exchange 2007 SP1 schema contains almost all the core Exchange functionality for working with items and folders in the Exchange store. We recommend that you maintain code forks for each EWS schema version. The following are the schema versions that are currently available.
<xs:simpleType name="ExchangeVersionType"> <xs:restriction base="xs:string"> <xs:enumeration value="Exchange2007" /> <xs:enumeration value="Exchange2007_SP1" /> <xs:enumeration value="Exchange2010" /> <xs:enumeration value="Exchange2010_SP1" /> <xs:enumeration value="Exchange2010_SP2" /> <xs:enumeration value="Exchange2013" /> </xs:restriction> </xs:simpleType>
The schema versions are maintained in the ExchangeVersionType simple type.
Include a switch in your application so that the client features that are available are based on the service version that is returned by the server. That way, your client can target all versions of Exchange that implement EWS. This design approach will enable you to target new versions of EWS to take advantage of new features that are implemented in the schema. The following example shows how your code might look.
// Where schemaVersion is the server version returned in a response. Switch schemaVersion: Case: schemaVersion is Exchange2007 Code paths to only Exchange2007 features. Case:schemaVersion is Exchange2007SP1 Code paths to include Exchange2007 and Exchange2007SP1 features. Case:schemaVersion is Exchange2010 Code paths to include Exchange2007, Exchange2007SP1, and Exchange2010 features
For information about the features that are available in each EWS schema version, see Exchange development technologies.
The virtual directory that hosts EWS contains a history of the different schema versions that are supported by the service. The schema files are named according to the service version they support. The different schema files are used to validate requests against the service version specified. The types.xsd and messages.xsd files always contain the latest versions of the schema. For example, Exchange 2013 SP1 contains the following schema files:
types.xsd – The types schema for the latest version of Exchange.
types-e15.xsd - The types schema for the Exchange2013 schema version that was released with Exchange 2013.
types-e14sp2.xsd – The types schema for the Exchange2010_SP2 schema version that was released with Exchange 2010 SP2.
types-e14sp1.xsd – The types schema for the Exchange2010_SP1 schema version that was released with Exchange 2010 SP1.
types-e14.xsd – The types schema for the Exchange2010 schema version that was released with Exchange 2010.
types-e12sp1.xsd – The types schema for the Exchange2007_SP1 schema version that was released with Exchange 2007 SP1.
types-e12.xsd – The types schema for the Exchange2007 schema version that was released with Exchange 2007.
messages.xsd – The messages schema for the latest version of Exchange Server and Exchange Online.
messages-e15.xsd – The messages schema for the Exchange2013 schema version that was released with Exchange 2013
messages-e14sp2.xsd – The messages schema for the Exchange2010_SP2 schema version that was released with Exchange 2010 SP2.
messages-e14sp1.xsd – The messages schema for the Exchange2010_SP1 schema version that was released with Exchange 2010 SP1.
messages-e14.xsd – The messages schema for the Exchange2010 schema version that was released with Exchange 2010.
messages-e12sp1.xsd – The messages schema for the Exchange2007_SP1 schema version that was released with Exchange 2007 SP1.
messages-e12.xsd – The messages schema for the Exchange2007 schema version that was released with Exchange 2007.
The WSDL file for all schema versions is always named Services.wsdl. Only one WSDL file exists for all schema versions supported by an Exchange server.