Persistent application settings in EWS in Exchange
Learn about the different options that your EWS Managed API or EWS application can use to create persistent custom application settings in Exchange.
The easiest way to keep custom client configurations in sync for a mailbox, or folders and items in a mailbox, is to store application settings on an Exchange server. You can ensure that those settings persist for a mailbox by using one of the following:
User configuration objects
Extended properties
Custom items
What are my options for creating persistent application settings?
User configuration objects are your best option for storing configuration settings for your EWS client applications. You can also use extend properties or custom items, or a combination of all three. Choose your option based on the scope of your settings and whether your settings need to be available to other applications.
Table 1. Recommended options for creating persistent application settings based on scope
| Setting scope | Use… | Accessed by |
|---|---|---|
| Item |
An extended property on an existing item. |
Any EWS application. Only EWS clients that know the property identifier can access an extended property. |
| Folder |
A user configuration object on the target folder. This is a good way to save view settings for a folder. |
Any EWS application. |
| Mailbox |
A user configuration object on the default msgrootfolder folder. |
Any EWS application. |
User configuration objects
User configuration objects are special items that are associated with folders in a mailbox. User configuration objects, also known as folder associated items, are typically the best option for persisting application settings, especially if the configuration information is associated with a folder or a mailbox. They typically are not surfaced to end users. Because they can natively store data streams and data dictionaries, they are ideal for storing configuration information. The best way to use user configuration objects is to store a set of configurations in an XML document and then save that information in one of the user configuration stream properties.
User configuration objects are accessed differently than the other item types stored in a mailbox. You can use the Folder.FindItems EWS Managed API method or the FindItem EWS operation to find all items, but you must use the Associated search traversal option to find user configuration objects. The Associated search traversal indicates that the search results should contain only user configuration objects. EWS includes a set of operations that are specific to user configuration objects.
Table 1. EWS operations and EWS Managed API methods for working with user configuration objects
| In order to… | Use this EWS operation | Use this EWS Managed API method |
|---|---|---|
| Create a user configuration object |
CreateUserConfiguration operation |
UserConfiguration.Save |
| Get a user configuration object |
GetUserConfiguration operation |
UserConfiguration.Bind UserConfiguration.Load |
| Update a user configuration object |
UpdateUserConfiguration operation |
UserConfiguration.Update |
| Delete a user configuration object |
DeleteUserConfiguration operation |
UserConfiguration.Delete |
Note
User configuration objects created by using EWS have an ItemClass prefix that starts with "IPM.Configuration.". The ItemClass of a user configuration object is the user configuration object prefix and your user configuration object name. You can use the Item.ItemClass EWS Managed API property or the ItemClass EWS element to search for user configuration objects that you've defined.
Extended properties
Use Extended properties if you want to store configuration information on items. EWS, unlike MAPI, does not return a property bag for items. This means that an EWS client must know the extended property identifier in order to find and access the extended property. If you need to store configuration information on items other than user configuration objects, using extended properties to create custom properties might be the solution for you. Extended properties enable you to access and store information on properties that are not part of the standard property set for an item.
Important
The Exchange database schema has a finite number of properties. The maximum number of property identifiers for an Exchange database is 32,767. If you are using extended properties to store many settings, we suggest that you use a single extended property to store those settings so that you don't exceed this maximum.
You can use the Item.Update EWS Managed API method or the UpdateItem EWS operation to set extended properties on user configuration objects.
Custom items
Custom items can also be used to store information. The existing item properties can be repurposed to contain configuration information. Or, you can use extended properties to define your own properties for you application. Using custom items to store configuration provides the following benefits:
They work for all versions of Exchange that support EWS.
If you don't use extended properties on the item, the budget of Exchange properties is not charged.
Where should I store my application settings?
Mailbox folders and the items within them are located in the root message folder. This folder is identified by the WellKnownFolderName.msgfolderroot value in the EWS Managed API. In MAPI terms, this is the equivalent of the IPM subtree of a mailbox. User configuration objects are often used to create UI-based settings, so that an application can render view settings based on the folder that a user is accessing. Folder-based view settings are usually set on a user configuration object that is associated with the folder. But sometimes, you might want to make your settings global to your application. In this case, you can store your settings in the root message folder.
Most users are not aware of and typically don't access the root mailbox folder. This folder is identified by the WellKnownFolderName.root value in the EWS Managed API. In MAPI terms, this is the equivalent of the non-IPM subtree of a mailbox. Information that end users don't access directly is stored in the root mailbox folder. You might want to store your application setting in this folder because client applications do not typically access it.
Version differences
User configuration objects are available on Exchange Online, Exchange Online as part of Office 365, and versions of Exchange starting with Exchange 2010.