Connecting to EWS by using the EWS Managed API 2.0
Find information about how to use the EWS Managed API to connect to EWS in Exchange.
Last modified: May 02, 2013
Applies to: EWS Managed API | Exchange Server 2007 Service Pack 1 (SP1) | Exchange Server 2010
Note: This content applies to the EWS Managed API 2.0 and earlier versions. For the latest information about the EWS Managed API, see Web services in Exchange.
In the Exchange Web Services (EWS) Managed API, the ExchangeService class contains the methods and properties that are used to set user credentials, identify the EWS endpoint, send and receive SOAP messages, and configure the connection with EWS. To perform an operation by using the EWS Managed API, you must connect the ExchangeService class to EWS.
After you have an ExchangeService object set up with user credentials and the EWS endpoint, any mailbox object that references the ExchangeService object can use methods to connect to EWS. You connect to EWS when you use the following method types:
ExchangeService object methods — All the methods on the ExchangeService object that are not inherited from the base Object type make calls to EWS.
Exchange mailbox item and folder type methods, including the following:
Load methods — Typically call the GetItem operation to get properties for an item. For attachment items, the Load method uses the GetAttachment operation to get properties for an attachment. For user configuration objects, the Load method uses the GetUserConfiguration operation to get the user configuration object properties.
Bind methods — Used to populate a new item on the client with information from an existing item on the server.
Save methods — Save the copy of the client item on the server. For existing items and folders, the Save method uses the UpdateItem and UpdateFolder operations. For new items and folders, the Save method uses the CreateItem and CreateFolder operations.
Update methods — Update the server with the changes made on the client. For items and folders, the Update method uses the UpdateItem and UpdateFolder operations.
Delete methods — Delete an item on the server. For items and folders, the Delete method uses the DeleteItem and DeleteFolder operations.
Copy methods — Create a copy of the item or folders on the server. For items and folders, the Copy method uses the CopyItem and CopyFolder operations.
Move methods — Move items or folders on the server. For items and folders, the Move method uses the MoveItem and MoveFolder operations.
For more information about how to connect to EWS, see Get started with EWS Managed API 2.0 client applications.
To connect to EWS
Instantiate the ExchangeService class.
ExchangeService service = new ExchangeService();Note
Instantiating ExchangeService with an empty constructor will create an instance that is bound to the latest known version of Exchange. Alternatively, you can target a specific version of Exchange by specifying version as a parameter.
ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2007_SP1);
For more information about versioning in the EWS Managed API, see Versioning EWS requests by using the EWS Managed API 2.0.Set the credentials of the user who sends requests to the Exchange server. If you want to connect to EWS from a computer that is logged on to the domain, using the credentials of the authenticated user, set the UseDefaultCredentials property on the ExchangeService object to true.
// Connect by using the default credentials of the authenticated user. service.UseDefaultCredentials = true;If you do not want to connect by using the default user credentials, set the Credentials property on the ExchangeService object to explicitly specify the credentials of a different user.
// Connect by using the credentials of user1 at contoso.com. service.Credentials = new WebCredentials("user1@contoso.com", "password");You can also specify the credentials of the user by using the user's domain name and password.
// Connect by using the credentials of contoso/user1. service.Credentials = new WebCredentials("user1", "password", "contoso");Note
If the UseDefaultCredentials property is set to true, the value of the Credentials property is ignored.
Set the URL of the EWS endpoint. This URL locates the exchange.asmx file on the Exchange server that has the Client Access server role installed.
// Use Autodiscover to set the URL endpoint. service.AutodiscoverUrl("user1@contoso.com");Note
Although you can explicitly set the Url property of the ExchangeService to a hardcoded value, we recommend using the Autodiscover service instead, for the following reasons:
-
Autodiscover determines the best endpoint for a given user (the endpoint that is closest to the user's Mailbox server).
-
The EWS URL might change if new Client Access servers are deployed. In this scenario, using Autodiscover means no code changes are necessary.
You should either set the URL explicitly or call AutodiscoverUrl, but you should not do both. For more information about Autodiscover, see Working with the Autodiscover service by using the EWS Managed API 2.0.
-
Robust programming
Write appropriate error handling code for common search errors.
Review the client request XML that is sent to the Exchange server.
Review the server response XML that is sent from the Exchange server.
Set the service binding as shown in Setting the Exchange service URL by using the EWS Managed API 2.0. Do not hard code URLs because if mailboxes move, they might be serviced by a different Client Access server. If the client cannot connect to the service, retry setting the binding by using the AutodiscoverUrl method.
Security
Use HTTP with SSL for all communication between client and server.
Always validate the server certificate that is used for establishing the SSL connections. For more information, see Validating X509 certificates by using the EWS Managed API 2.0.
Do not include user names and passwords in trace files.
Ensure that Autodiscover lookups that use HTTP GET to find an endpoint always prompt for user confirmation; otherwise, they should be blocked.
See also