編輯

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:

In this section

See also