As became apparent in the previous post introducing Web Add-ins, a Web Add-in consists of more than a single file containing the code. Distributing and installing a Web Add-in is more complex than handing someone an Office document containing the code and explaining how to change the settings in the Trust Center so that it can run. Why is this?

Well, it’s certainly not because Microsoft wants to make things exciting for us… Partly, it has to do with the Internet technology and it also is a question of security.

Since the mid-90’s and the first “macro virus”, security has been an on-going concern. Attempts to protect users have ranged from confirming a prompt to enable macro execution to the capability of locking out Office automation completely, with any number of nuances in between. Digital code-signing and trusted publishers, locations and documents have been added to the mix. You can see the whole gammut in File/Options/Trust Center/Trust Center Settings.

With the advent of the .NET Framework and VSTO there was an attempt to use .NET Framework security approaches, but these turned out to be an obstacle outside of corporate environments with an IT staff to manage installation and trust.

Over time, the realization dawned that trying to save people from themselves while still allowing customization of the Office applications is a fairly hopeless task. More and more, the prevailing philosophy is that people are responsible for what they install on their machines. In theory, Microsoft takes some responsibility in that what is offered via the “Office store” is supposedly checked and validated before being released to the public. (I thought a long time about this phrasing as I’ve seen a number of discussions that question the valdiation process…)

Another facet of this security concept is that the Web Add-in must declare what it is and what sites it intends to access before it can be loaded. This is what the XML Manifest is for, as defined for example in the “Hello World” sample. The XML Manifest is a kind of “configuration” file and is commonly used these days in software distribution.

Information about what is required and allowed in the XML Manifest for Web Add-ins is available on MSDN. A word of warning: working through the entire specification involves clicking through multiple pages. The documentation is well-organized, but we are talking about XML: for each “level” and entry at that level there’s a separate page…

So let’s take a quick look at the sample manifest and get a general idea what it means. The following discussion will not assume a deep knowledge of XML, but you will need an acquaintance with the basics.

<?xml version="1.0" encoding="utf-8"?>
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:type="TaskPaneApp">
  <Id>08afd7fe-1631-42f4-84f1-5ba51e242f98
  <Version>1.0
  <ProviderName>Microsoft
  <DefaultLocale>EN-US
  <isplayName DefaultValue="Hello World app"/>
  <Description DefaultValue="My first app."/>
  <IconUrl DefaultValue=
    "http://officeimg.vo.msecnd.net/_layouts/images/general/office_logo.jpg"/>

  <Hosts>
    <Host Name="Document"/>
    <Host Name="Workbook"/>
  </Hosts>

  <DefaultSettings>
    <SourceLocation DefaultValue="\\MyShare\MyManifests\HelloWorld\HelloWorld.html"/>
  </DefaultSettings>
  <Permissions>ReadWriteDocument
</OfficeApp>

The first line is familiar enough: it tells the consuming software that it’s dealing with an XML file that follows the standard rules (version=”1.0″) and uses UTF-8 encoding.

The second line introduces the document-level element, OfficeApp. It declares two namespaces and sets the type of Web Add-in. Both of the namespaces point to schemas (set of rules for the XML) and are required. Note the version number of the first schema: appforoffice/1.1. Since the original release of Office 2013 this has changed – and it could change again. (When new functionality is added or improvements are made a new schema is required.) You also need to be careful with the information and samples on MSDN: many of them still have the original code samples pointing to the original schema: appforoffice/1.0.

Besides typing the namespaces exactly, very important is specifying the xsi:type attribute. This tells the Office applications whether the Web Add-in is a task pane, content embedded on the document surface, or an Outlook mail add-in. Some digging is required to find the correct terms on MSDN: here, under Remarks.

The first child element under OfficeApp is Id and is required. For this you need to generate a GUID (Globally Unique Identifier). If you have Visual Studio, that has a GUID generator. There’s also one on-line that works quite nicely. This value should never change, even when you release a new version of your Add-in.

That brings us to the next element: Version. This, also, is required. You can assign the version number you wish, as long as it follows the expected RegEx pattern defined here. As long as you stick to what you know from Office versions (1.0, 1.1, etc.) you’ll be fine.

ProviderName is the name of the software manufacturer, such as Microsoft, or your name when publishing your own code. It’s required…

…As is the next element, DefaultLocale. This tells the Office application which main language the Add-in uses. Again, the entry needs to match a RegEx pattern. But if you stick to the LanguageId codes used by VBA you’ll be fine, such as EN-US or DE-DE.

DisplayName is fairly self-explanatory (and required). The designation can comprise up to 125 characters. In case you develop add-ins for multiple languages Display accepts Override child elements you can use to specifiy additional languages (cultures). All these elements are locale-aware.

The next element is also required: Description. It lets you provide a longer description of the add-in (up to 250 characters) and also supports Override elements for multiple languages.

IconUrl is not required. It allows you to specify the path to the icon you want to associate with your add-in. The specifications for the icon are given at the end of this article. Providing alternates for different locales is also supported by this element.

The Hosts element contains one or more Host elements. This is a list of the Office applications which may load the Add-in. (In the original 1.0 schema, the elements were named “Capabilities” and “Capability”.) Valid names are listed on the page for “Hosts”, under Child elements.

The content (child elements) of DefaultSettings is specific to the type of Add-in. A task pane supports only one child element: the location (URL) of the Add-in’s files, SourceLocation. If you created a Share on your machine or network, that would be the file path to the shared folder using a syntax like DefaultValue=”File:///C:/OfficeAddins/Test1/WebPage.html”

Finally, and very important, are the Permissions. These, again, are specific to the type of Add-in and delineate what the add-in may do. For a task pane the accepted values are Restricted, ReadDocument, ReadAllDocument, WriteDocument, ReadWriteDocument. What these mean is described in the documentation.

There are a few more possible child elements of OfficeApp, none of which are required (obviously). For example, you can provide a URL for support or list locations your Add-in accesses that are not in the default folder (this is for security reasons).

In the next post on this topic, we’ll take a look at the JavaScript side of the “Hello World” sample.

Leave a Reply