Specify the Office hosts and APIs your app requires

apps for Office

Learn how to specify the API requirement sets and methods your app requires for its features in your app's manifest.

Applies to: Access apps for SharePoint | apps for Office | Excel | Office Add-ins | Outlook | 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
Referencing the JavaScript API for Office library and manifest schema version
Specifying the minimum version of a requirement set
Specifying requirement sets and required methods
Requirement sets
Methods that aren't part of a requirement set
Additional resources

The apps for Office platform lets you design apps that run with one or more Office host applications. In the manifest for your app, you must specify the app's type (content, task pane, or mail app), and can optionally specify which family of host application it's designed to work with. For example, the following Hosts and Host declaration in your app's manifest specifies that the app will work with workbooks, which maps to support for the Excel family of host applications.

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

However, as new APIs are added to the JavaScript API for Office (office.js), not all members of a given host family will necessarily support these APIs when they are first added to the JavaScript API for Office library. For example, they may be supported by Excel on the Windows desktop when first released, but only later will be supported by Excel Online in the browser. To make sure that your app can access a certain API at runtime, you should also specify its API requirements in your app's manifest, as requirement sets, or as individual required methods with the Requirements, Sets, Set, and Methods elements. When you specify these API requirements, the apps for Office platform will query the host application before activating your app to make sure that only a host that supports the specified APIs can activate the app.

For requirement sets and required methods to work optimally, you should reference the most current version of the JavaScript API for Office library available in the <head> tag of the web page (such as an .html, .aspx, or .php file) that implements the UI of your app. To do that, add a script tag with its src attribute set to the following CDN URL:

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

For more information, see Referencing the JavaScript API for Office library from its content delivery network (CDN).

Additionally, the Requirements, Sets, Set, and Methods elements require that your app's manifest uses version 1.1 of the app manifest schema. To do that, make sure that the xmlns attribute of the OfficeApp element is specified as follows:

<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="TaskPaneApp">

When specifying a requirement set, you should specify the minimum version of the requirement set that supports the essential features of your app. You specify this version in the manifest using the MinVersion attribute of the Set element (or the DefaultMinVersion attribute of the Sets element). This will make sure that if a user can activate your app, he or she will be able to use the essential features of your app. Because releases of office.js are backward-compatible, releases of Office that support a later version of office.js will also be able to support your app as well.

The Requirements element is an optional element in the version 1.1 app manifest. Use this element to specify the named sets of API methods or individual methods that your app requires in order to run. If you don't specify this element in the manifest, your app should run in all Office host applications specified in the optional Hosts element (for information on how to specify the Hosts element, see Specify the Office host applications your app supports). For content and task pane apps, if you omit both the Hosts and Requirements elements, then the app should load in all Office host applications that support that specific type of app for Office.

Important note Important

For mail apps, if you use version 1.1 of the app for Office manifest, there is only one "Mailbox" requirement set available. This requirement set contains the entire subset of API supported in mail apps for Outlook, and you must specify the "Mailbox" requirement set in your mail app's manifest (it's not optional as is the case for content and task pane apps). Also, you can't declare support for specific methods in mail apps.

The following tables describe the Requirements, Sets, Set, Methods, and Method elements that you use to specify requirement sets or individual methods in content and task pane apps.

Requirements element

Description

Specifies the minimum set of Office.js requirements that the app for Office needs to activate.

Optional attributes

None

Required attributes

None

Child elements

Sets, Methods

Note Note

The Sets and Methods elements don't apply to mail apps.

Default version attribute pattern

x.y

If omitted, version default value

1.1

Sets element

Description

Specifies the list of required API sets from the JavaScript API for Office that the app requires in order to activate.

Optional attributes

DefaultMinVersion (string) - specifies the default MinVersion value for all child Set elements.

Required attributes

Name (string)

Child elements

Set

Set element

Description

Specifies an individual set from the JavaScript API for Office that the app requires in order to activate.

Optional attributes

MinVersion (string) - specifies the minimum version of the API set required by the app.

Required attributes

Name (string)

Methods element

Description

Specifies the list of required methods from the JavaScript API for Office that the app requires in order to activate.

Optional attributes

None

Required attributes

None

Child elements

Method

Method element

Description

Specifies an individual method from the JavaScript API for Office that the app requires in order to activate.

Optional attributes

None

Required attributes

Name

You must specify the name of the method qualified with its parent object. For example, to specify the getSelectedDataAsync method, you must specify Document.getSelectedDataAsync

Important note Important

Because there is no way to specify the minimum version requirement for individual methods, to make sure that a method is available at runtime, you should also use an if statement when calling that method in the script of your app. For more information about how to do this, see Check host application support for specific API members at runtime.

In the following example, the app should load in all Office host applications that support:

  • Office.js v1.1 TableBindings requirements set, with a minimum version requirement of 1.1

  • Office.js v1.1 OOXML requirements set, with a minimum version requirement of 1.1

  • Office.js Office.context.document.getSelectedDataAsync method

<Requirements>
   <Sets DefaultMinVersion="1.1">
      <Set Name="TableBindings" MinVersion="1.1"/>
      <Set Name="OOXML" MinVersion="1.1"/>
   </Sets>
   <Methods>
      <Method Name="Document.getSelectedDataAsync"/>
   </Methods>
</Requirements>

The following table lists the names of requirement sets, the methods in each set, and the Office host applications that will load an app that specifies that set.

Set name

Version

Methods in set

Office host support

ActiveView

1.1

Document.getActiveViewAsync

PowerPoint

PowerPoint Online

BindingEvents

1.1

Binding.addHanderAsync

Binding.removeHanderAsync

Access web apps

Excel

Excel Online

Word

CompressedFile

1.1

Supports output to Office Open XML (OOXML) format as a byte array (Office.FileType.Compressed) when using the Document.getFileAsync method.

PowerPoint

Word

CustomXmlParts

1.1

CustomXmlNode.getNodesAsync

CustomXmlNode.getNodeValueAsync

CustomXmlNode.getXmlAsync

CustomXmlNode.setNodeValueAsync

CustomXmlNode.setXmlAsync

CustomXmlPart.addHandlerAsync

CustomXmlPart.deleteAsync

CustomXmlPart.getNodesAsync

CustomXmlPart.getXmlAsync

CustomXmlPart.removeHandlerAsync

CustomXmlParts.addAsync

CustomXmlParts.getByIdAsync

CustomXmlParts.getByNamespaceAsync

CustomXmlPrefixMappings.addNamespaceAsync

CustomXmlPrefixMappings.getNamespaceAsync

CustomXmlPrefixMappings.getPrefixAsync

Word

DocumentEvents

1.1

Document.addHandlerAsync

Document.removeHandlerAsync

Excel

Excel Online

PowerPoint

Word

Word Online

File

1.1

Document.getFileAsync

File.closeAsync

File.getSliceAsync

PowerPoint

Word

Word Online

HtmlCoercion

1.1

Supports coercion to HTML (Office.CoercionType.Html) when reading and writing data using the Document.getSelectedDataAsync, Document.setSelectedDataAsync, Binding.getDataAsync, or Binding.setDataAsync methods.

Word

Mailbox

1.1

All API members supported by mail apps (those members accessed from Office.context and Office.context.mailbox in your app's code).

Outlook

Outlook Web App

OWA for Devices

MatrixBindings

1.1

Bindings.addFromNamedItemAsync

Bindings.addFromSelectionAsync

Bindings.getAllAsync

Bindings.getByIdAsync

Bindings.releaseByIdAsync

MatrixBinding.getDataAsync

MatrixBinding.setDataAsync

Excel

Excel Online

Word

MatrixCoercion

1.1

Supports coercion to the "matrix" (array of arrays) data structure (Office.CoercionType.Matrix) when reading and writing data using the Document.getSelectedDataAsync, Document.setSelectedDataAsync, Binding.getDataAsync, or Binding.setDataAsync methods.

Excel

Excel Online

Word

OoxmlCoercion

1.1

Supports coercion to Open Office XML (OOXML) format (Office.CoercionType.Ooxml) when reading and writing data using the Document.getSelectedDataAsync, Document.setSelectedDataAsync, Binding.getDataAsync, or Binding.setDataAsync methods.

Word

PartialTableBindings

1.1

Access web apps

PdfFile

1.1

Supports output to PDF format (Office.FileType.Pdf) when using the Document.getFileAsync method.

PowerPoint

Word

Selection

1.1

Document.getSelectedDataAsync

Document.setSelectedDataAsync

Excel

Excel Online

PowerPoint

Project

Word

Settings

1.1

Settings.get

Settings.remove

Settings.saveAsync

Settings.set

Access web apps

Excel

Excel Online

PowerPoint

PowerPoint Online

Word

Word Online

TableBindings

1.1

Bindings.addFromNamedItemAsync

Bindings.addFromSelectionAsync

Bindings.getAllAsync

Bindings.getByIdAsync

Bindings.releaseByIdAsync

TableBinding.addColumnsAsync

TableBinding.addRowsAsync

TableBinding.deleteAllDataValuesAsync

TableBinding.getDataAsync

TableBinding.setDataAsync

Access web apps

Excel

Excel Online

Word

TableCoercion

1.1

Supports coercion to the "table" data structure (Office.CoercionType.Table) when reading and writing data using the Document.getSelectedDataAsync, Document.setSelectedDataAsync, Binding.getDataAsync, or Binding.setDataAsync methods.

Access web apps

Excel

Excel Online

Word

TextBindings

1.1

Bindings.addFromNamedItemAsync

Bindings.addFromSelectionAsync

Bindings.getAllAsync

Bindings.getByIdAsync

Bindings.releaseByIdAsync

TextBinding.getDataAsync

TextBinding.setDataAsync

Excel

Excel Online

Word

TextCoercion

1.1

Supports coercion to text format (Office.CoercionType.Text) when reading and writing data using the Document.getSelectedDataAsync, Document.setSelectedDataAsync, Binding.getDataAsync, or Binding.setDataAsync methods.

Excel

Excel Online

PowerPoint

Project

Word

Word Online

TextFile

1.1

Supports output to text format (Office.FileType.Text) when using the Document.getFileAsync method.

Word

The following methods in the JavaScript API for Office v1.1 aren't part of a requirement set.

Method name

Office host support

Bindings.addFromPromptAsync

Access web apps, Excel and Excel Online

Document.getFilePropertiesAsync

Excel, Excel Online, Word, and PowerPoint

Document.getProjectFieldAsync

Project Standard 2013 and Project Professional 2013

Document.getResourceFieldAsync

Project Standard 2013 and Project Professional 2013

Document.getSelectedResourceAsync

Project Standard 2013 and Project Professional 2013

Document.getSelectedTaskAsync

Project Standard 2013 and Project Professional 2013

Document.getSelectedViewAsync

PowerPoint and PowerPoint Online

Document.getTaskAsync

Project Standard 2013 and Project Professional 2013

Document.getTaskFieldAsync

Project Standard 2013 and Project Professional 2013

Document.goToByIdAsync

Excel, Excel Online, Word, and PowerPoint

Settings.addHandlerAsync

Access web apps, Excel, Excel Online, Word, and PowerPoint

Settings.refreshAsync

Access web apps, Excel, Excel Online, Word, PowerPoint, and PowerPoint Online

Settings.removeHandlerAsync

Access web apps, Excel, Excel Online, Word, and PowerPoint

TableBinding.clearFormatsAsync

Excel, Excel Online

TableBinding.setFormatsAsync

Excel, Excel Online

TableBinding.setTableOptionsAsync

Excel, Excel Online

Show:
© 2015 Microsoft