Properties and extended properties in EWS in Exchange

Discover how you can define and access properties on items and folders by using EWS in Exchange.

An Exchange mailbox contains a large number of items, including email messages, appointments, meetings, and so on. Those items are made up of properties; the properties describe the items. You can use item properties to perform a search, synchronize item changes, and create custom property types. This article provides an overview of properties and how you can work with properties in your application.

Exchange item properties

Items and folders in Exchange are essentially rows in tables. The main property that identifies an item or folder is its EWS identifier. Although there are other identifier-related properties in the Exchange database, for EWS, the EWS identifier acts as the primary key for the collection of properties that describe an item. The EWS identifier property contains two parts:

• An ItemId or FolderId property that identifies the item

• A ChangeKey property that contains stateful information about whether an item or folder has changed

All items in a mailbox are stored in the same Exchange database and use the same database schema. Items are distinguished by a combination of the ItemClass property, property constraints, and the business logic layers that affect how they are managed in the Exchange store. Table 1 shows how properties are applied across different item types; in this example, email and appointment items. Both items have a value for the Subject property. But notice that the IsAllDayEvent property is not set on the email item, and the IsReadReceiptRequested property is not set on the appointment. Fortunately, you don't need to know which properties are applicable for each item class; EWS handles this for you.

Table 1. Comparison of appointment and email properties

Item type	Item class	Subject	IsAllDayEvent	IsReadReceiptRequested
Email	IPM.Note	Status report: Project X complete	NULL	true
Appointment	IPM.Appointment	Contoso company meeting	false	NULL

The EWS schema supports many of the constraints managed by the Exchange database and the business logic layers between EWS and the Exchange database. The EWS schema applies a defined a set of properties to each item type. The following are the strongly-typed Exchange database items provided by EWS:

• Email messages

• Appointments

• Contacts

• Distribution lists

• Meeting messages

• Meeting requests

• Meeting responses

• Meeting cancellations

• Tasks

• Post items

Generic items are returned by EWS as email messages. The EWS Managed API implements all these item types.

Note

Response objects are only sent by the client to the server in response to items received from other people. They do not exist in the Exchange database.

What are properties in EWS?

The EWS schema describes the data that is sent between an EWS client and Exchange. A large part of the schema describes the item and folder properties that you can access in the Exchange database. The EWS schema describes the XML representation of the Exchange database properties that are available to your application. The actual properties, in terms of which properties are available, what form they take, and the values they return, vary based on what you trying to do. For example, the Body property will only return the first 512 characters in a FindItem operation, but the GetItem operation returns the full text of the item. Although most properties are both settable and retrievable, some properties are only set by Exchange. Each property exists in the schema in an XML format that either reflects the property as it is stored in the Exchange database, or is computed from properties stored in the Exchange database. The Subject property is an example of a settable property; the UnreadCount property on a folder is an example of a computed property. A core set of properties are common to the core item types.

The following factors determine the property set that your application gets from Exchange:

• The operation that your application is calling

• The base response shape

• The item type

• The specified property paths

It is important to understand how these different factors affect the data that you can access. As with the example of the Body property mentioned earlier, some information is conditionally available depending on various factors. Understanding these factors might save you time by helping you choose the correct options to access the information you want. To discover which properties are accessible, you will need to test these factors to determine how to access the properties your application needs. This section describes how these different factors affect which properties are returned in EWS responses.

EWS response shapes

Exchange stores a lot of information about items. Sometimes, your application doesn't need all of that information, and in many cases, it is best not to get it all. EWS response shapes, also called property shapes, indicate which properties are returned from the server. The core element of the response shape is the base shape. A base shape is a default preset property bag for strongly typed items. The EWS Managed API equivalent of the base shape is the BasePropertySet. EWS includes three default response shapes.

Table 2. Default response shapes

Default response shape name	EWS Managed API equivalent	Description
IdOnly	BasePropertySet.IdOnly value	Only the EWS identifier and change key are returned. Unless the client uses all the properties returned by the AllProperties or Default shape, use the IdOnly shape and specify additional properties by using the property path set on the PropertySet class. Most applications should use the IdOnly response shape with additional properties specified. This reduces the amount of unused data that is requested by clients.
Default	N/A	A set of standard properties for the item type. Only use this response shape if your application uses all the properties.
AllProperties	BasePropertySet.FirstClassProperties value	A larger set of properties than the Default shape. Although the name implies it, this option does not return all properties on an item. This property set returns the properties that client applications use most often. If you need additional properties, you can request them by their property path. If your application doesn't use all the properties returned with this response shape, use the IdOnly response shape with additional properties specified.

Many EWS operations return items and their properties. Regardless of the response shapes that you specify, different operations can return different property sets. Different item types also return different properties, depending on the operation and the response shape specified. The following operations use response shapes to identify which properties to return.

Table 3. Operations that use response shapes

EWS operation	EWS Managed API method
GetConversationItems	ExchangeService.GetConversationItems method
GetFolder	Folder.Bind method
GetItem	Item.Bind method ExchangeService.BindToItems method
FindConversation	ExchangeService.FindConversation method
FindFolder	Folder.FindFolders method ExchangeService.FindFolders method
FindItem	Folder.FindItems method ExchangeService.FindItems method
FindPeople	Not implemented.
ResolveNames	ExchangeService.ResolveNames method
SearchMailboxes	ExchangeService.SearchMailboxes method ExchangeService.BeginSearchMailboxes method
SyncFolderHierarchy	ExchangeService.SyncFolderHierarchy method
SyncFolderItems	ExchangeService.SyncFolderItems method

Property shapes are one, rudimentary way to identify the properties that you want your application to return. Sometimes, however, your application needs a more refined set of specific properties. For this, you can use the property path.

Choose properties by their property path

An EWS property path is metadata that is used to identify properties in either a request or response.

Table 4. Property path types

Property path type	Schema type	EWS Managed API implementation	Description
FieldUri	PathToUnindexedFieldType	Types that inherit from ServiceObjectSchema.	The most common property path. FieldUri property paths are specified on a PropertySet object in the EWS Managed API. Most EWS properties can be specified by the FieldUri property path. This is described by the UnindexedFieldURIType in the EWS schema. The FieldUri property path XML looks like this: XML<FieldURI FieldURI="item:Subject"/>This property path is the equivalent of ItemSchema.Subject in the EWS Managed API.
IndexedFieldUri	PathToIndexedFieldType	Types that inherit from ItemSchema.	Identifies dictionary properties that require a property index to specify the value to return. Use this path when a property can have more than one value. This is described by the DictionaryURIType property in the EWS schema. DictionaryURIType property paths are specified on a PropertySet object in the EWS Managed API. The IndexedFieldUri property path XML looks like this: XML<IndexedFieldURI FieldURI="contacts:PhysicalAddress:Street FieldIndex="Home"/>
ExtendedFieldUri	PathToExtendedFieldType	ExtendedPropertyDefinition	Identifies an extended property definition that identifies custom or non-schematized properties on items. The ExtendedFieldUri property path XML looks like this: XML<ExtendedFieldURI> PropertyTag="0x1234" PropertyType="Integer" />
ExceptionFieldUri	ExceptionFieldURI	ServiceResponse	Specifies properties that are associated with an error in an EWS response. This is described by the ExceptionPropertyURIType type in the EWS schema. This only occurs in the MessageXml element of error responses that occur when you are working with calendar recurrence patterns.

As a best practice, when you request properties, use the IdOnly base shape (BasePropertySet.IdOnly in the EWS Managed API) and then request only the properties your application needs by specifying the property paths.

Schematized properties

Most of the properties that your EWS client needs are described by the EWS schema. The primary folder and item type definitions, which contain the property definitions, are found in the types.xsd schema. The following schema types contain the property definitions for most objects that you can use.

Table 5. Schema types that contain property definitions

EWS schema type	EWS Managed API type equivalent	Defines the…
ItemType	Item class	Base item type property set. This type can be created from a client but is never returned by Exchange. Exchange returns a MessageType object for all generic objects.
MessageType	EmailMessage class	Email message object property set and the property set for all generic objects.
CalendarItemType	Appointment class	Calendar item property set; this includes single and recurring appointments.
ContactItemType	Contact class	Contact item property set.
DistributionListType	ContactGroup class	Personal distribution list property set.
MeetingMessageType	MeetingMessage class	Meeting message type property set.
MeetingRequestMessageType	MeetingRequest class	Meeting request type property set.
MeetingResponseMessageType	MeetingResponse class	Meeting response type property set.
MeetingCancellationMessageType	MeetingCancellation class	Meeting cancellation type property set.
TaskType	Task class	Task type property set.
PostItemType	PostItem class	Postitem type property set.
FolderType	Folder class	Folder type property set.
CalendarFolderType	CalendarFolder class	SearchFolder type property set.
ContactsFolderType	ContactsFolder class	ContactsFolder type property set.
SearchFolderType	SearchFolder class	SearchFolder type property set.
TasksFolderType	TasksFolder class	TasksFolder type property set.
UserConfigurationType	UserConfiguration class	UserConfiguration type property set.

While the properties in the EWS schema are sufficient for many applications, you can't implement some scenarios by using only what is described in the schema. For those scenarios, you can extended properties.

Extended properties (aka non-schematized properties)

Extended properties enable you to create custom properties, which give you access to properties on items and folders in the Exchange store that are not defined in the EWS schema. You can use them to access the native MAPI item and folder properties in the Exchange database. You can use extended properties to access all the schematized properties, because under the covers, those schematized properties are nothing more than MAPI properties in the Exchange database.

The PathToExtendedFieldType schema type, located in the types.xsd schema, defines the XML that represents an extended property. This schema type defines the ExtendedFieldURI element in XML instances; in other words, it defines the XML that is sent between the service and client. The ExtendedPropertyType schema type defines both the ExtendedFieldURI element and the value or array of values that an extended property contains. The following table shows the approximate mapping of the extended property XML and how it is implemented on items in the EWS Managed API.

Table 6. Extended property XML as implemented in the EWS Managed API

EWS Managed API implementation	What it contains	What it maps to
Item.ExtendedProperties property	A collection of extended properties on an item.	One or more instances of extended properties on an item.
ExtendedProperty class	The extended property definition and values.	The ExtendedPropertyType schema type.
ExtendedPropertyDefinition class	An extended property definition.	The PathToExtendedFieldType schema type.

If you want to learn more about how you can use extended properties in your application, you can explore the following code samples:

• MFCMapi

• Exchange 2013: Provision custom X-headers programmatically

• Exchange 2013: Access a property by its property tag

• Exchange 2013: Access a named property by its identifier

• Exchange 2013: Access a named property by its name

• Exchange 2013: Access a property by property set GUID and name

• Exchange 2013: Create custom extended properties programmatically

In this section

• Provision x-headers by using EWS in Exchange

• EWS property-related errors

See also

• Start using web services in Exchange

• MFCMapi