Retrieve Contacts from the Contacts Folder by using the EWS Managed API 2.0
Use the EWS Managed API to retrieve contact items from the Contacts folder.
Last modified: July 24, 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.
The Contacts folder can contain items of more than one type. You can use the EWS Managed API to retrieve items of a particular type from the Contacts folder.
To retrieve contacts from the Contacts folder
Identify items in the folder that are of type Contact. The Contacts folder can also contain distribution lists.
Because the Contacts folder can contain a large number of items, as a best practice, limit the number of items to retrieve to 50.
The following code example shows how to retrieve the number of items in the default Contacts folder.
// Get the number of items in the contacts folder. To limit the size of the response, request only the TotalCount property. ContactsFolder contactsfolder = ContactsFolder.Bind(service, WellKnownFolderName.Contacts, new PropertySet(BasePropertySet.IdOnly, FolderSchema.TotalCount)); // Set the number of items to the number of items in the Contacts folder or 50, whichever is smaller. int numItems = contactsfolder.TotalCount < 50 ? contactsfolder.TotalCount : 50;Instantiate the ItemView object by using the number of items in the Contacts folder. Limit the contact item properties to be retrieved to only the display name.
// Instantiate the item view with the number of items to retrieve from the Contacts folder. ItemView view = new ItemView(numItems); // To keep the response smaller, request only the display name. view.PropertySet = new PropertySet(BasePropertySet.IdOnly, ContactSchema.DisplayName);Request the items in the Contacts folder that have the properties that you selected by using the FindItems method of the ExchangeService object. Cast the returned collection of Contact folder items as type Contact so that their properties can be accessed and displayed. Note that not all items in the Contacts folder will be Contact objects.
// Request the items in the Contacts folder that have the properties that you selected. FindItemsResults<Item> contactItems = service.FindItems(WellKnownFolderName.Contacts, view); // Display the list of contacts. (Note that there can be a large number of contacts in the Contacts folder.) foreach (Item item in contactItems) { if (item is Contact) { Contact contact = item as Contact; Console.WriteLine(contact.DisplayName); } }
Example
The following example shows how to retrieve the contacts in the default Contacts folder. This example assumes that service is a valid ExchangeService binding.
// Get the number of items in the Contacts folder.
ContactsFolder contactsfolder = ContactsFolder.Bind(service, WellKnownFolderName.Contacts);
// Set the number of items to the number of items in the Contacts folder or 50, whichever is smaller.
int numItems = contactsfolder.TotalCount < 50 ? contactsfolder.TotalCount : 50;
// Instantiate the item view with the number of items to retrieve from the Contacts folder.
ItemView view = new ItemView(numItems);
// To keep the request smaller, request only the display name property.
view.PropertySet = new PropertySet(BasePropertySet.IdOnly, ContactSchema.DisplayName);
// Retrieve the items in the Contacts folder that have the properties that you selected.
FindItemsResults<Item> contactItems = service.FindItems(WellKnownFolderName.Contacts, view);
// Display the list of contacts.
foreach (Item item in contactItems)
{
if (item is Contact)
{
Contact contact = item as Contact;
Console.WriteLine(contact.DisplayName);
}
}
The following example shows the XML that is sent by using the ContactsFolderBind method.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2010_SP1" />
</soap:Header>
<soap:Body>
<m:GetFolder>
<m:FolderShape>
<t:BaseShape>IdOnly</t:BaseShape>
<t:AdditionalProperties>
<t:FieldURI FieldURI="folder:TotalCount" />
</t:AdditionalProperties>
</m:FolderShape>
<m:FolderIds>
<t:DistinguishedFolderId Id="contacts" />
</m:FolderIds>
</m:GetFolder>
</soap:Body>
</soap:Envelope>
The following example shows the XML that is returned by using the ContactsFolderBind method. The FolderId and ChangeKey attributes have been shortened to preserve readability.
<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
<h:ServerVersionInfo MajorVersion="14" MinorVersion="16" MajorBuildNumber="123" MinorBuildNumber="1" Version="Exchange2010_SP2"
xmlns:h="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
</s:Header>
<s:Body>
<m:GetFolderResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages" xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
<m:ResponseMessages>
<m:GetFolderResponseMessage ResponseClass="Success">
<m:ResponseCode>NoError</m:ResponseCode>
<m:Folders>
<t:ContactsFolder>
<t:FolderId Id="AAMkA =" ChangeKey="AwAAA" />
<t:TotalCount>2</t:TotalCount>
</t:ContactsFolder>
</m:Folders>
</m:GetFolderResponseMessage>
</m:ResponseMessages>
</m:GetFolderResponse>
</s:Body>
</s:Envelope>
The following example shows the XML that is sent by using the ExchangeServiceFindItems method.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2010_SP1" />
</soap:Header>
<soap:Body>
<m:FindItem Traversal="Shallow">
<m:ItemShape>
<t:BaseShape>IdOnly</t:BaseShape>
<t:AdditionalProperties>
<t:FieldURI FieldURI="contacts:DisplayName" />
</t:AdditionalProperties>
</m:ItemShape>
<m:IndexedPageItemView MaxEntriesReturned="2" Offset="0" BasePoint="Beginning" />
<m:ParentFolderIds>
<t:DistinguishedFolderId Id="contacts" />
</m:ParentFolderIds>
</m:FindItem>
</soap:Body>
</soap:Envelope>
The following example shows the XML that is returned by using the ExchangeServiceFindItems method. The FolderId and ChangeKey attributes have been shortened to preserve readability.
<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
<h:ServerVersionInfo MajorVersion="14" MinorVersion="16" MajorBuildNumber="123" MinorBuildNumber="1" Version="Exchange2010_SP2"
xmlns:h="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
</s:Header>
<s:Body>
<m:FindItemResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages" xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
<m:ResponseMessages>
<m:FindItemResponseMessage ResponseClass="Success">
<m:ResponseCode>NoError</m:ResponseCode>
<m:RootFolder IndexedPagingOffset="2" TotalItemsInView="2" IncludesLastItemInRange="false">
<t:Items>
<t:Contact>
<t:ItemId Id="AAMkA =" ChangeKey="EQABQ==" />
<t:DisplayName>Brian David Johnson</t:DisplayName>
</t:Contact>
<t:Contact>
<t:ItemId Id="AAMkA=" ChangeKey="EQABY" />
<t:DisplayName>Kim Truelsen</t:DisplayName>
</t:Contact>
</t:Items>
</m:RootFolder>
</m:FindItemResponseMessage>
</m:ResponseMessages>
</m:FindItemResponse>
</s:Body>
</s:Envelope>
Compiling the code
For information about compiling this code, see Getting started with 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(String) method.
Set the target Exchange Web Services schema version by setting the requestedServerVersion parameter of the ExchangeService constructor. For more information, see Versioning EWS requests by using the EWS Managed API 2.0.
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.
Verify that Autodiscover lookups that use HTTP GET to find an endpoint always prompt for user confirmation; otherwise, they should be blocked.