Export (0) Print
Expand All

Best practices for developing apps for Office

apps for Office

This topic suggests best practices for implementing, debugging, and testing an app for Office.

Last modified: February 27, 2014

Applies to: Access app for SharePoint | Excel 2013 | Excel 2013 RT | Excel 2013 SP1 | Excel Online | Outlook 2013 | Outlook 2013 RT | Outlook 2013 SP1 | Outlook Web App | OWA for Devices | PowerPoint 2013 | PowerPoint 2013 RT | PowerPoint 2013 SP1 | PowerPoint Online | Project 2013 | Project 2013 SP1 | Word 2013 | Word 2013 RT | Word 2013 SP1

   Office.js: v1.0, v1.1

   Apps for Office manifests schema: v1.0, v1.1

In this article
Manifest file
HTML and JavaScript pages
Resource usage
Activation and implementation rules for mail apps
Additional resources

The following best practices pertain to implementing and testing the manifest file of an app for Office:

  • Uniquely identify an app for Office

    When you start creating an app for Office by using the manifest file of an existing app, make sure that you assign a unique identifier in the Id element in the new manifest. One way to do this systematically is to use a tool like "Napa" Office 365 Development Tools or Visual Studio to generate a new GUID.

    If you use "Napa" Office 365 Development Tools or Visual Studio 2012 (or a later version) to create the app, "Napa" Office 365 Development Tools or Visual Studio automatically assigns a unique ID in the Id element.

Icon for task pane and content apps for Office
  • Keep the same Id when updating a task pane app or content app

    When you update and redeploy a task pane or content app, make sure that the Id element in the app's manifest uses the same GUID as the older version of the app. This ensures that any document that had the older version of the app persisted into it will continue to work with the new version. If you change the Id GUID in the manifest when you update an app, the Id persisted into the document will no longer match and the app can't be activated.

Validating the manifest file

Make sure that you make validating the app for Office manifest file a part of your development and testing efforts. For more information on validating the manifest, see the topic Validating the app for Office manifest.

Icon for mail apps for Office
  • Make sure your mail app is reinstalled after you update the manifest

    When you develop and test a mail app, you may need to update the manifest. If you are using "Napa" Office 365 Development Tools or Visual Studio to develop the app, "Napa" Office 365 Development Tools and Visual Studio automatically reinstalls the app and restarts Outlook after you update the manifest. However, if you are not using these tools to develop your app, you should uninstall the mail app and reinstall it using the Exchange Admin Center after you make changes to the manifest. Then you can test your changes on the Outlook clients that your app supports, including the Outlook rich client, Outlook Web App or OWA for Devices.

The following are best practices for implementing or testing the HTML and JavaScript pages of an app:

  • Use META tag to control appropriate display of an app for Office

    Because an Office host application requires components of at least Internet Explorer 9 in a browser control to open the app HTML page, you should place an appropriate document compatibility meta element as a child element of the head element in your HTML file, before all other elements except for the title and other meta elements.

    The following is an example of a meta element that specifies the mode "IE=Edge":

    <!DOCTYPE html>
        <meta http-equiv="X-UA-Compatible" content="IE=Edge">

    Using IE=Edge displays the app in the highest mode available on the client computer. As app developer, you should make sure that your app displays properly in modes ranging from the minimum supported IE9 to the latest available mode. This way you can ensure a quality experience for all users of the app.

    For more information about using the meta element and an X-UA-Compatible header, see HTTP-EQUIV attribute | httpEquiv property and Defining Document Compatibility.

  • All apps for Office, including mail apps, must include a reference to both the Office.js and MicrosoftAjax.js JavaScript libraries. For information about best practices for referencing Office.js and other associated files, see the article Referencing the JavaScript API for Office library from its content delivery network (CDN)

  • Browse across multiple domains only when absolutely necessary

    When possible, avoid browsing across multiple domains. In scenarios where this is necessary, such as using oAuth to share resources on one site with another site on a different domain, specify them using the AppDomains and AppDomain elements in the manifest file of the app.

  • Avoid using the javascript: protocol in a link HREF or form ACTION

    When an app is running in Excel Online, Outlook Web App or OWA for Devices in Internet Explorer 10, using the javascript: protocol to run JavaScript in a link HREF or form ACTION will be blocked. This is because the IFrame that hosts the app in the specified hosts uses the sandbox attribute, which blocks execution of JavaScript calls made using the javascript: protocol. To avoid this problem, use the onclick and onsubmit events (for links and forms, respectively) to execute the script.

  • Set Internet Explorer to use the most recent version of HTML or JavaScript pages

    Set Internet Explorer to check for newer versions of stored pages to expedite the development of your app for Office. This ensures that after you modify the HTML or JavaScript code for your app, you only need to close and reopen the app pane to see the results. You can do so by following these steps:

    1. In Internet Explorer 9, choose Internet options. In the General tab, under Browsing history, choose Settings.

    2. Select the option Every time I visit the webpage if it is not already selected.

  • Verify the app does not use HTTP

    To make sure apps are not delivering content using HTTP, when testing apps, you should make sure the following settings are selected in Internet Explorer and no security warnings appear in your test scenarios:

    • Make sure the security setting, Display mixed content, for the Internet zone is set to Prompt. You can do that by selecting the following in Internet Explorer: on the Security tab of the Internet Options dialog box, select the Internet zone, select Custom level, scroll to look for Display mixed content, and select Prompt if it is not already selected.

    • Make sure Warn if Changing between Secure and not secure mode is selected in the Advanced tab of the Internet Options dialog box.

  • Security practices for developers

    See the following sections for security best practices:

Icon for task pane and content apps for Office
  • Create no more than 200 bindings

    Task pane and content apps that bind to regions of a document should create no more than 200 bindings per document.

The following lists some common web practices and specific resource usage rules for apps for Office to improve performance on the web.

  • Common web practices

    • Include only necessary JavaScript libraries

    • Include images at the appropriate resolution

    • Avoid long-running tasks that block the host application

  • Following resource usage rules

    To provide a satisfactory experience for users of apps for Office, be aware that these apps must perform within specific performance requirements. Test your apps to make sure they follow resource usage rules. For more information, see Following resource usage rules in apps for Office.

If you are creating a mail app, check out the following best practices for activation rules. Make sure you follow the rules for implementing mail apps so that your apps activate and work as you expect.

Icon for mail apps for Office
  • Verify a regular expression for the item HTML body returns same results in all Outlook clients

    If you use an ItemHasRegularExpressionMatch rule with BodyAsHTML as the PropertyName attribute, be aware that the HTML body of an item is slightly different between the Outlook rich client, and Outlook Web App or OWA for Devices, and define your regular expression carefully. Consider the following regular expression:


    A rule with this regular expression would match the string "http-equiv="Content-Type" which exists in the HTML body of an item in the Outlook rich client, as part of the following meta tag:

    <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=us-ascii">

    The same rule does not return this match in Outlook Web App or OWA for Devices because for these hosts, the HTML body does not include that meta tag. This can affect whether the mail app is activated appropriately for the various Outlook clients. In this example, use the following regular expression instead:

  • Verify a regular expression for the item plain text body returns expected results on different browsers

    If you use an ItemHasRegularExpressionMatch rule with BodyAsPlaintext as the PropertyName attribute, test your regular expression on all the browsers that your app supports.

    Because different browsers use different ways to obtain the text body of a selected item, you should make sure that your regular expression supports the subtle differences that can be returned as part of the body text. For example, some browsers such as Internet Explorer 9 uses the innerText property of the DOM, and others such as Firefox uses the .textContent() method to obtain the text body of an item. Also, different browsers may return line breaks differently: a line break is "\r\n" on Internet Explorer, and "\n" on Firefox and Chrome. For more information, see W3C DOM Compatibility - HTML.

  • Avoid obtaining the entire body of an item

    Avoid using a regular expression such as .* in a rule to obtain the entire body of a message or appointment item, particularly if the body contains a large number of characters. The regular expression does not necessarily return the expected results.

  • Follow implementation rules

    To provide a satisfactory experience for users of mail apps, please be aware of the limits for setting up activation rules and using various features such as custom properties, settings, and Exchange Web Service. See Limits for activation and JavaScript API for mail apps in Outlook for more information.

© 2014 Microsoft