| title | manager | ms.date | ms.audience | ms.assetid | description | localization_priority |
|---|---|---|---|---|---|---|
Properties and extended properties in EWS in Exchange |
sethgros |
09/17/2015 |
Developer |
68623048-060e-4602-b3fa-62617a94cf72 |
Discover how you can define and access properties on items and folders by using EWS in Exchange. |
Priority |
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.
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:
-
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.
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.
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
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.
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.
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 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: