Export (0) Print
Expand All

Properties and extended properties in EWS in Exchange

Exchange

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

Last modified: February 20, 2014

Applies to: Exchange Online | Exchange Server 2013 | Office 365

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:

  • 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 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.

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

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:

<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:

<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:

<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:

Show:
© 2014 Microsoft