Sharing user settings of Outlook Add-in between COM/VSTO and Office JS worlds
Scope
The following article covers an approach for developers to make a bridge between COM/VSTO Outlook Add-in and Office JS Add-ins to share user’s roaming settings and preferences.
Introduction
There are plenty of companies who deliver reach experience to their customers through COM/VSTO Outlook Add-ins for ages and Outlook 2000 to the latest version support is normal for them. With maturity of the Microsoft Office Store and technology behind Office JS Add-ins more and more companies looking to implement their existing solutions using Office JS API. Ability to write once and distribute easily the application for environments where Office works is very attractive point. But what about customers who still use old reliable Office 2010 or even older. You may say: “Let them use our old COM Add-in and don’t look back”. Well this may be valid point until this customer start to use Outlook for Web and realize you’ve created the Add-in for this environment as well. Great! Start using it … but wait a second, where are my settings and preference I set at my work place when used desktop solution for Outlook? What if I would like to change my preferences? Now I have to do that twice? A developer would say: “Move on to our new solution, forget about old COM”. But users probably have a reason why they use old Outlook version with COM Add-in at work and OWA with new Office JS Add-in remotely (during a trip, work from home, etc.). The reader probably got my point by now. As the developer, you may want to make life of those customers simpler by sharing the preferences between your brand new and shiny Office JS Add-in as well as your old, but solid and full of features COM/VSTO solution. So, let’s find out how to do that.
Office JS Add-in Roaming Settings
Right from the requirement set 1.0 Office JS API “RoamingSettings” object was introduced with four methods to manipulate with user settings. You are able to set, get and delete any custom value of the user setting/property type of {String|Number|Boolean|Object|Array}. This object keeps those settings per user mailbox and will be available to your Office JS Add-in from any location, device, etc. True roaming to keep your user’s preferences and settings, isn’t it? Please note: You should not use this object to keep sensitive information such as user credential or security tokens. The following example demonstrate usage of the object:
// Get the current value of the 'myKey' setting
var value = Office.context.roamingSettings.get('myKey');
// Update the value of the 'myKey' setting
Office.context.roamingSettings.set('myKey', 'Hello World!');
// Persist the change
Office.context.roamingSettings.saveAsync();
COM/VSTO Add-in for Desktop Outlook
Let’s return to our COM/VSTO solution. There is the single pre-request: to handle the settings which were stored in the user’s mailbox developer needs to know Office JS Add-in ID as the “RoamingSettings” are stored per add-in and per user. Well, you would know it indeed, as this is your/your company Add-in. The settings we are looking for are stored in the message property, which is stored in “Associated contents table” of the Inbox folder may be accessed using “IMAPIFolder” interface. Wow, this was the key sentence from entire post and needs to be explained in details.
First you would need to enumerate all messages in associated contents table and find the message with the class “IPM.Configuration.ClientExtension.00000000000000000000000000000000”, where zeros must be ID of your Office JS Add-in.
When message selected, you would need to get “PR_ROAMING_DICTIONARY” Property.
This property will contain serialized data we stored as roaming setting when used Office JS Add-in in our example above:
<?xml version="1.0" encoding="utf-8"?>
<UserConfiguration>
<Info version="Exchange.12" />
<Data>
<e k="18-ExtensionSettings" v="18-{"myKey":"\"Hello World!\""}" />
</Data>
</UserConfiguration>
Your COM/VSTO Add-in will be able to read and modify those settings with simple parse. You may want to expose your COM Add-in user setting as well. Usually those settings developers keep in HKCU Windows Registry, to roaming world per user mailbox. The benefit of this not only in capability between Office JS Add-in, but separated set of settings of your Add-in per user mailbox. When those settings created from Desktop Outlook use different info version, for example:
<Info version="Outlook.16"/>
Conclusion
As the final note on the topic I would like to illustrate the simple example of shared settings of an application from the same provider where COM and Office JS Add-ins share user settings.
