Outlook add-in: Make an Exchange Web Service request from Outlook
Table of contents
- Key components of the sample
- Description of the code
- Build and debug
- Questions and comments
- Additional resources
This sample requires the following:
- Visual Studio 2013 with Update 5 or Visual Studio 2015.
- A computer running Exchange 2013 with at least one email account, or an Office 365 account. You can join the Office 365 Developer Program and get a free 1 year subscription to Office 365.
- Any browser that supports ECMAScript 5.1, HTML5, and CSS3, such as Internet Explorer 9, Chrome 13, Firefox 5, Safari 5.0.6, or a later version of these browsers.
Key components of the sample
The sample solution contains the following files:
- MakeEwsRequestManifest.xml: The manifest file for the Outlook add-in.
- AppRead\Home\Home.html: The HTML user interface for the mail add-in for Outlook.
The code that creates the EWS XML request includes two methods. The first method,
getSoapEnvelope(), wraps a SOAP envelope around a web service request. Because the SOAP envelope is standard for all EWS requests, this method can be reused to wrap any EWS request.
The second method,
getSubjectRequest(), returns the EWS request to get the subject field of an item. The id parameter is the Exchange item identifier for the requested item. Note the following about the request:
ItemShapeelement is used to restrict the response to the base shape
IdOnly. This limits the response to only the item identifier for the item and prevents excessive data from being sent back from the server.
AdditionalPropertieselement is used to add the Subject field to the response. By using the
IdOnlybase shape and a list of additional properties, you can limit the size of the response from the server to just the data that your add-in requires.
sendRequest() method is called when you click the Make EWS request button in the add-in UI. It gets the Exchange identifier of the current item and passes it to the
getSoapEnvelope() methods, then makes an asynchronous call to the Exchange server by using the
makeEwsRequestAsync method. The
makeEwsRequestAsync method takes two parameters: the EWS request wrapped in its SOAP envelope, and a callback method that is called when the asynchronous request to EWS is complete. You can add a third optional
userContext parameter to the
makeEwsRequestAsync method if you have to provide additional information to the callback method.
callback() method is called with a single parameter,
asyncResult object has two members:
value– The contents of the response from EWS.
userContextparameter passed to the makeEwsRequestAsync method.
callback method in the sample displays the contents of the response in a scrollable
div element in the UI, but your code can use the response in more sophisticated ways.
Build and debug
Note: The mail add-in will be activated on any email message in the user's Inbox. You can make it easier to test the add-in by sending one or more email messages to your test account before you run the sample add-in.
- Open the solution in Visual Studio. Press F5 to build and deploy the sample add-in.
- Connect to an Exchange account by providing the email address and password for an Exchange 2013 server.
- Allow the server to configure the mail account.
- Log on to the email account by entering the account name and password.
- Select a message in the Inbox.
- Wait for the add-in bar to appear over the message.
- In the add-in bar, click MakeEWSRequest.
- When the mail add-in appears, click the Make EWS Request button to request the subject of the current message from the Exchange server.
- Review the response XML returned by the request.
- The add-in bar does not appear when a message is selected. If this occurs, restart the application by selecting Debug – Stop Debugging in the Visual Studio window, then press F5 to rebuild and deploy the add-in.
- If you have any trouble running this sample, please log an issue.
- Questions about Office Add-in development in general should be posted to Stack Overflow. Make sure that your questions or comments are tagged with [office-addins].
- More Add-in samples
- Explore the EWS Managed API, EWS, and web services in Exchange
- makeEwsRequestAsync method
Copyright (c) 2015 Microsoft. All rights reserved.