Best practices for developing Office Add-ins

Office Add-ins

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

Last modified: May 01, 2015

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". For details, see New name for apps for Office and SharePoint.

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 or Visual Studio 2012 (or a later version) to create the app, Napa 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 Validate the Office Add-ins 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 or Visual Studio to develop the app, Napa 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.

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 Office Add-ins.

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 clients, 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 an 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 add-ins in Outlook for more information.

© 2015 Microsoft