Export (0) Print
Expand All

How to: Create a content or task pane app that targets multiple Office releases

apps for Office

This article describes the best practices for creating a content or task pane app that targets multiple releases of Office.

Last modified: May 01, 2015

Applies to: apps for Office | Excel | Office Add-ins | PowerPoint | Project | Word

Learn more about supported hosts and other requirements.

Note Note

The name "apps for Office" is changing to "Office Add-ins". During the transition, the documentation and the UI of some Office host applications and Visual Studio tools might still use the term "apps for Office".

In this article
Use a version 1.0 app manifest
Reference version 1.1 of Office.js
Use defensive programming to check for host support of v1.1 API members
Additional resources

When Office 2013 was first released (RTM), apps for Office and their associated Office host applications supported only version 1.0 of the JavaScript API for Office (Office.js) and version 1.0 of the app manifest schema. When Office 2013 Service Pack 1 (SP1) was released, apps for Office added support for version 1.1 of the JavaScript API for Office (Office.js), which includes new APIs and features, and support for new app manifests that conform to the version 1.1 app manifest schema.

If you want your content or task pane app to support the fullest range of possible Office 2013 host applications (both RTM and SP1 or later), and use new API features when running in SP1 or later hosts, your app needs to be implemented in the following way:

  • Use a v1.0 app manifest

  • Reference v1.1 or later of Office.js

  • Use defensive programming when calling v1.1 or later members of the API to check for host application support

A v1.0 app manifest is necessary because it's the "lowest common denominator" with respect to Office host applications. Host applications in the RTM release of Office 2013 can't use a v1.1 app manifest, but the SP1 release can use either v1.0 or v1.1 app manifests.

Referencing v1.1 or later of Office.js provides full backward compatibility with v1.0 API features, but also lets your app use new APIs and features when it's running in the context of Office 2013 SP1 or later host applications.

However, because new v1.1 APIs aren't supported by the RTM release of Office 2013, when you call a new v1.1 API you must use an if statement in the script of your app to determine if the host application supports that object, method, or enumeration. This technique lets you test for API support to avoid errors in RTM hosts, and to branch your code to "light up" app features that will work only in SP1 or later hosts.

Note: If you submit your app to the Office Store when it's configured to use a v1.0 app manifest and v1.1 or later Office.js, you will receive a warning that directs you to the techniques described in this topic. Also, this strategy won't work for mail apps. If your mail app requires features in v1.1 or later Office.js, it must also use a v1.1 app manifest.

To make sure that your content or task pane app is using a v1.0 app manifest, it must reference the v1.0 app schema in the xmlns attribute of the OfficeApp tag of the manifest XML file, like this example:

<?xml version="1.0" encoding="UTF-8"?>
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.0" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   xsi:type="TaskPaneApp">
<!--Remaining app manifest tags omitted-->
</OfficeApp>

When developing your app with Visual Studio 2013, make sure to observe the following:

For task pane app projects, Visual Studio uses a v1.0 app manifest by default.

However, if you use the Manifest Designer (in Solution Explorer, double-click the <projectname>Manifest folder in the "Office" project), avoid the following settings on the Activation tab:

  • Don't add any API sets under Required API Sets

  • Don't select the Any Office application that is available in Office 365 or Office 2013 SP1 option under Applications

Changing either of these settings requires v1.1 app manifest features, and Visual Studio will change the xmlns attribute and other values in your manifest file to conform to the v1.1 app manifest schema.

For content app projects, Visual Studio uses a v1.0 app manifest by default only for content apps created for Excel.

To make sure your app uses only Excel and a v1.0 app manifest:

  • Don't choose Access or PowerPoint in the Create app for Office wizard when you first create your project.

  • After creating your project, if you use the Activation tab of the Manifest Designer:

    • Don't choose Access or PowerPoint under Applications

    • Don't select the Any Office application that is available in Office 365 or Office 2013 SP1 option under Applications

    • Don't add any API sets under Required API Sets

Support for content apps in Access and PowerPoint, and the required API sets feature was added in Office 2013 SP1. If you change any of these three settings in the Manifest Designer, Visual Studio will modify your app to use a v1.1 app manifest.

To make sure that your content or task pane app is using Office.js v1.1, each HTML page in your app must reference that version of Office.js in a script tag inside the head tag of the page:

<script src="https://appsforoffice.microsoft.com/lib/1.1/hosted/office.js" type="text/javascript"></script>

If you're developing your content or task pane app with Visual Studio 2013, the Home.html page in the App folder of your app's web project will reference Office.js v1.1 by default.

If your app calls new members of the v1.1 API, your code should check for host support to handle activation in RTM host applications. In its most basic form, to determine if a host application supports a specific object, method, or enumeration, use an if statement in this form in your app's script:

if(Office.context.document.goToByIdAsync){
// Code to run if true.
}

The example above tests for support of the Document.goToByIdAsync method, which is a new method added in Office.js v1.1 that is only supported when apps are hosted by the SP1 or later releases of Excel, Word, or PowerPoint.

Here's another more complex use of this feature in a function that tests whether inserting and binding to selected data is supported:

function dataInsertionSupported() {
    return Office.context.document.setSelectedDataAsync &&
        (Office.context.document.bindings &&
        Office.context.document.bindings.addFromSelectionAsync)
}
Show:
© 2015 Microsoft