Viewing custom extended properties by using the EWS Managed API 2.0
Last modified: October 13, 2012
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.
You can use the Microsoft Exchange Web Services (EWS) Managed API to view the extended properties that have been added to items and folders. Extended properties are custom properties on items and folders in a Microsoft Exchange Server mailbox.
To view an extended property
Define a view along with a page size. The following code shows an ItemView with a page size of 10.
ItemView view = new ItemView(10);Create a GUID identifier from the GUID that was used when the extended property was created.
Guid MyPropertySetId = new Guid("{C11FF724-AA03-4555-9952-8FA248A11C3E}");Define the PropertySet to search for the defined ExtendedPropertyDefinition. Optionally, to enhance performance, limit the returned properties to Id, Subject, and ExtendedPropertyDefinition.
view.PropertySet = new PropertySet(BasePropertySet.IdOnly, ItemSchema.Subject, extendedPropertyDefinition);Retrieve a collection of items for a user. In the following example, only the results of the Inbox are retrieved.
FindItemsResults<Item> findResults = service.FindItems(WellKnownFolderName.Inbox, view);Loop through the retrieved collection and display the item's subject line. If an extended property exists, display the name and value of the extended property.
foreach (Item item in findResults.Items) { Console.WriteLine(item.Subject); if (item.ExtendedProperties.Count > 0) { // Display the name and value of the extended property. foreach (ExtendedProperty extendedProperty in item.ExtendedProperties) { Console.WriteLine(" Extended Property Name: " + extendedProperty.PropertyDefinition.Name); Console.WriteLine(" Extended Property Value: " + extendedProperty.Value); } } }
Example
The following example shows how to retrieve a collection of items from the Exchange mailbox, including the extended property that is identified by the GUID. The example searches each retrieved item and displays the subject line of each item and the extended property name and value, if it exists.
// Retrieve a collection of all the mail (limited to 10 items) in the Inbox. View the extended property.
ItemView view = new ItemView(10);
// Get the GUID for the property set.
Guid MyPropertySetId = new Guid("{C11FF724-AA03-4555-9952-8FA248A11C3E}");
// Create a definition for the extended property.
ExtendedPropertyDefinition extendedPropertyDefinition =
new ExtendedPropertyDefinition(MyPropertySetId, "Expiration Date", MapiPropertyType.String);
view.PropertySet =
new PropertySet(BasePropertySet.IdOnly, ItemSchema.Subject, extendedPropertyDefinition);
FindItemsResults<Item> findResults = service.FindItems(WellKnownFolderName.Inbox, view);
// Search the e-mail collection for the extended property.
foreach (Item item in findResults.Items)
{
Console.WriteLine(item.Subject);
if (item.ExtendedProperties.Count > 0)
{
// Display the extended name and value of the extended property.
foreach (ExtendedProperty extendedProperty in item.ExtendedProperties)
{
Console.WriteLine(" Extended Property Name: " + extendedProperty.PropertyDefinition.Name);
Console.WriteLine(" Extended Property Value: " + extendedProperty.Value);
}
}
}
' Retrieve a collection of all the mail (limited to 10 items) in the Inbox. View the extended property.
Dim view As New ItemView(10)
' Get the GUID for the property set.
Dim MyPropertySetId As New Guid("{C11FF724-AA03-4555-9952-8FA248A11C3E}")
' Create a definition for the extended property.
Dim extendedPropertyDefinition As New ExtendedPropertyDefinition(MyPropertySetId, "Expiration Date", MapiPropertyType.String)
view.PropertySet =
New PropertySet(BasePropertySet.IdOnly, New PropertyDefinitionBase() {ItemSchema.Subject, extendedPropertyDefinition})
Dim findResults As FindItemsResults(Of Item) = service.FindItems(WellKnownFolderName.Inbox, view)
' Search the e-mail collection for the extended property.
Dim item As Item
For Each item In findResults.Items
Console.WriteLine(item.Subject)
If (item.ExtendedProperties.Count > 0) Then
Dim extendedProperty As ExtendedProperty
' Display the name and value of the extended property.
For Each extendedProperty In item.ExtendedProperties
Console.WriteLine(" Extended Property Name: " & extendedProperty.PropertyDefinition.Name)
Console.WriteLine(" Extended Property Value: " & extendedProperty.Value)
Next
End If
Next
The following example shows the XML request that is sent by the client to the server.
<?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" />
</soap:Header>
<soap:Body>
<m:FindItem Traversal="Shallow">
<m:ItemShape>
<t:BaseShape>IdOnly</t:BaseShape>
<t:AdditionalProperties>
<t:FieldURI FieldURI="item:Subject" />
<t:ExtendedFieldURI PropertySetId="c11ff724-aa03-4555-9952-8fa248a11c3e"
PropertyName="Expiration Date" PropertyType="String" />
</t:AdditionalProperties>
</m:ItemShape>
<m:IndexedPageItemView MaxEntriesReturned="10" Offset="0" BasePoint="Beginning" />
<m:ParentFolderIds>
<t:DistinguishedFolderId Id="inbox" />
</m:ParentFolderIds>
</m:FindItem>
</soap:Body>
</soap:Envelope>
The following example shows the XML response that is returned by the server after it parses the request from the client. The ItemId 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="0" MajorBuildNumber="482"
MinorBuildNumber="8" Version="Exchange2010"
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 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<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="3" TotalItemsInView="3" IncludesLastItemInRange="true">
<t:Items>
<t:Message>
<t:ItemId Id="AQMkADE" ChangeKey="CQAAABYAAA" />
<t:Subject>Saved with extendedPropertyDefinition (MyFlag) value of 8</t:Subject>
<t:ExtendedProperty>
<t:ExtendedFieldURI PropertySetId="c11ff724-aa03-4555-9952-8fa248a11c3e"
PropertyName="Expiration Date" PropertyType="String" />
<t:Value>1/30/2009 10:45:13 AM</t:Value>
</t:ExtendedProperty>
</t:Message>
<t:Message>
<t:ItemId Id="AQMkADE" ChangeKey="CQAAABYAAA" />
<t:Subject>Saved with extendedPropertyDefinition (MyFlag) value of 8</t:Subject>
<t:ExtendedProperty>
<t:ExtendedFieldURI PropertySetId="c11ff724-aa03-4555-9952-8fa248a11c3e"
PropertyName="Expiration Date" PropertyType="String" />
<t:Value>1/30/2009 10:39:47 AM</t:Value>
</t:ExtendedProperty>
</t:Message>
<t:Message>
<t:ItemId Id="AQMkADE" ChangeKey="CQAAABYAAA" />
<t:Subject>Toto: Using Client API.</t:Subject>
</t:Message>
</t:Items>
</m:RootFolder>
</m:FindItemResponseMessage>
</m:ResponseMessages>
</m:FindItemResponse>
</s:Body>
</s:Envelope>
The response includes three items. Two items contain an extended property and one item does not contain an extended property.
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.