Migrating an Office Task Pane App to a Toolbar Add In

If you’re one of those less-informed people, like myself apparently, you may have recently received an email or otherwise found out that the Office task pane app you published in the Office Store a while ago is no longer in compliance.  It is now a requirement that any task pane apps that were previously submitted – back when that was the only app form factor available – need to be refactored to support the Add In toolbar model.  This announcement was easy to miss since it only appeared rather randomly once on some Office team blog.  Rather ironic given that this comes from the team that provides so many office communications tools.

But I digress…once you find out you need to update your app to support the new model (as well as the old model, since not every single customer is on Office 365 and/or Office 2016), how do you do it?  Unfortunately the fine folks that made this policy change neglected to provide a guide on how to do so.  They merely provide links to very general and fairly vague documentation, so since I just went through this process I thought I would capture it for others who may need to do the same thing.

Here are the steps I went through to move my Outlook task pane app to the Add In toolbar model.

Step 1 – Get the latest version of the Office Tools for Visual Studio

The actual location to get this may vary depending on your locale and version of Visual Studio, so I’ll just leave it at “go get it and install it”.

Step 2 – Start Working with Your Application’s Manifest File

Interestingly enough, once the latest tools are installed, it’s actually gone a step backwards from a tooling perspective.  When I double-click on my app manifest in Visual Studio 2015 now, it no longer opens the visual designer that lets you set attributes in your manifest.  Instead it just opens the underlying Xml file and you get to edit Xml by hand.  I could swear I’ve seen this before…oh wait – I did – like 15 years ago.  Visual Studio does at least provide some editing advantages over Notepad, so there is a certain amount of forward progress.

Step 3 – Update the top-level OfficeApp Element

The main change needed to the manifest file is going to be to add a VersionOverrides node and populate it with the correct data.  Note that you can keep all of your existing content in your Xml file, which you’ll actually want to do to ensure that it is supported on clients that do not have Office 2016.  In order to add the VersionOverrides node though, you first need to update the top-level OfficeApp element.  This is to add some namespaces that are needed to support the content in VersionOverrides.  Here’s an example of my new OfficeApp element:

xml0

One important point to note:  my element includes the “mailappor” namespace and is of type “MailApp”.  If your app is not an Outlook add-in, then the values you will need to add will be different.  While I could try and point you to some documentation, I actually recommend doing this to make sure you have it exactly right (I found the documentation to be a bit painful):  just create a new project in Visual Studio for an Office Add In that is the same type as the one you are updating.  Then you can grab the correct namespaces and types from the Xml file for the manifest it creates.  Much quicker and easier than searching for and through sketchy documentation.

Step 4 – Add the VersionOverrides Node at the END of Your Existing Content

Here’s something that isn’t at all obvious – you can’t just add the VersionOverrides node anywhere in your app’s manifest.  You need to add it at the end – after any Rules you may have (like in a Rule node), which is after your Permissions node.  Your VersionOverrides node may be perfectly formed, but if you place it any higher in the manifest, you will get an Xml validation error and your life will suck.

Step 5 – Add Your VersionOverrides Node and Start Editing

For this step, I’m just going to paste in a big bunch of Xml and then start talking through what it is and how it’s all linked together.  So to begin, here’s the Xml – both some stuff from my original manifest file and the new VersionOverrides node:

  xml1

Okay, let’s start breaking some of this down.

Step 5.1 – The VersionOverrides Node

My VersionOverrides node looks like this:

xml3

The main thing I want to point out here is the namespace.  Again, my app is an Add In for Outlook, so it uses that namespace.  If your app is not for Outlook, it will be different.  Again, look at the content in your sample application you created above to get the correct value.

Step 5.2 – Set All of the Common Property Values

Within the VersionOverrides node, there’s a chunk of properties that will likely be used in different form factors – for example reading a message, composing a message, reading an appointment, etc.   So let’s look at this chunk of Xml:

 xml2

As you can see, these are the resources for your app – icons, icon titles, tool tips, that sort of thing.  You’ll notice that you need icons that are 16×16, 32×32 and 80×80.  Add those to your Add In’s web site and then plug in the Url.

For the functionFile I cheated…just meaning I don’t have any UI-less triggers, so I just plugged in the home page for my Add In’s site.  If you have a javascript file for this, then you would put the Url here.

The ShortStrings and LongStrings section are where you put the strings that will be used for the icon titles and tool tips.  Plug in whatever is appropriate for your app.

Now, here’s an important one – look at the item with the id “messageReadTaskPaneUrl” – THIS is where you plug in the Url that you used before in your original task pane app.  For example, I’m going to paste in side by side here a couple of chunks of Xml from above.  The first one is for my original task pane definition, and the second one is my messageReadTaskPaneUrl node:

xml6

Hey look – the Urls are the same!  Finally, starting to make some sense.

Here’s the big thing that is not clearly called out in the documentation – look at the id’s all of the elements in the resources section.  You’re going to plug these same id’s in when you declare the various form factors your application supports – such as message read, message compose, etc.  Let’s see how that works next.

Step 5.3 – Add Your Form Factor Implementations

This step is what ties it all together.  You create a definition for each form factor you want to support, like Message Read, Message Compose, etc.  I’m going to paste in the Xml for one of my form factors below and then talk through it:

xml7

Let’s look at some of these individual elements now:

  • ExtensionPoint xsi:type – this is what defines the form factor, in this case Message Read
  • Label resid=”groupLabel” – this corresponds to the ShortString I have in the resources section with the id “groupLabel”
  • Label resid=”paneReadButtonLabel” – this corresponds to the ShortString I have in the resources section with the id “paneReadButtonLabel”
  • Title resid=”paneReadSuperTipTitle” – you probably get this by now – corresponds to the id in ShortStrings
  • Description resid=”paneReadSuperTipDescription” – again, guessing you understand here. What you’ll see is the icons you’ve defined show up in the toolbar (in the Outlook 2016 client) or in the Outlook Web Access UI.  In the toolbar the icon will have the title I put in the “paneReadSuperTipTitle”, and when you hover over it you will get a tooltip that contains the paneReadSuperTipDescription.
  • Icon node – you’ll see the three different icons, with each one pointing to the different id’s that were added in the resource section.
  • Action – this is the money node – the SourceLocation has a resid value that points to the id in our Resources section with the Url that we used in our task pane app; in my example that’s https://weatheroutlook.azurewebsites.net/AppRead/Home/HomeRead.html.

That’s really it – once you understand how all the pieces relate to each other in the manifest file, then it’s really pretty simple to add other form factors (or ExtensionPoint nodes as they’re called in the Xml).  After that, you just need to click the Publish item on the shortcut menu for your App project and click the Package the add-in button.  It’s a little silly because all it does is open a window with your manifest’s Xml file.  Then you can click the button at the bottom of the page to Visit the Seller Dashboard, update your manifest, and you’re done!  Just wait for it to get through the validation process successfully and your Office Store application will be updated.

That’s it – hopefully you can use this guide to walk through the process of updating your own applications.  I’ve uploaded my own manifest file so you can see the entire thing and hopefully it will help you see how it all plugs in together – you can get it from https://1drv.ms/u/s!AEFcZajG99GWlIYw.  In case it doesn’t automatically download for you, look for the WeatherOutlook.zip file. Good luck!!

 

Advertisements