Edit

EWS client design overview for Exchange

  • Article

Learn about the design considerations for developing with EWS for Exchange.

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 Office 365, Exchange Online, 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.

Is EWS the right API for your application?

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.

Note

You need a license in order to develop Exchange ActiveSync clients. 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.

For more information about Exchange development technologies, see Explore the EWS Managed API, EWS, and web services in Exchange.

Options for EWS client development

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 more, see Get started with EWS Managed API client applications.

Note

The EWS Managed API is now available as an open source project on GitHub. You can use the open source library to:

  • Contribute bug fixes and enhancements to the API.
  • Get fixes and enhancements before they are available in an official release.
  • Access the most comprehensive and up-to-date implementation of the API, to use as a reference or to create new libraries on new platforms.

We welcome your contributions via GitHub.

EWS Java API

The EWS Java API is an open source project on GitHub that can be updated and extended by the community. It is stylistically similar to the EWS Managed API and uses EWS SOAP requests and responses over the wire. Although you can't access all EWS SOAP operations by using the EWS Java API, with the recent creation of the open source project, we are looking to the community to bridge this gap. Note that Microsoft Support, with an appropriate support contract, will address any questions related to the EWS SOAP protocol but not the EWS Java API itself. The EWS Java API is available for download and community contribution on GitHub.

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.

EWS client features

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:enumeration value="Exchange2013_SP1" />
    </xs:restriction>
  </xs:simpleType>

The schema versions are maintained in the ExchangeVersionType simple type.

For information about the features that are available in each EWS schema version, see EWS schema versions in Exchange.

In this section

See also