Make your apps a native part of Office with Office Add-ins

Speaker: Andrew Salamatov

Office Platform

The Office add-ins platform is part of the Office developer ecosystem. It’s important to understand the full power of this ecosystem. The ecosystem consists of 3 pillars

  • Add-ins and web parts: enabling devs to extend the Office UI, e.g. buttons
  • Web and device apps: application that you can build on top of the data that is in Office 365
  • Voice, video, connectors and bots: conversations as a platform, e.g. actionable messages


There are 3 key aspects to the Office add-in framework:

  • Native experiences through web technologies
  • Write once, run everywhere
  • Modern distribution and deployment

As an IT Pro it was painful to deploy add-ins. Performance and deployment are core problems. The COM model is limited to Win32 clients. You have to have a platform that is cross-platform, that is not something that COM could bring. A few years ago a new journey was started to build a new platform based on web. You build a solution once and the same set of APIs works on Windows, Max, web and mobile. This enables you to build a solution once and distribute it everywhere.

In terms of modern distribution, the add-in is in the store, the advantage is that the developer can update it and it loads automatically at the end users. It automatically goes out from the store. Administrators can install for users or groups of users, the organizational catalog for Office 365.

The add-in is nothing more than a web app and an XML manifest. The web app is hosted by the developer wherever you choose. The manifest describes how the add-in integrated into Office. One key thing that it does is that it specified where the code lies.

An add-in is a set of extension points in the Office UI. The most common way to extend Office is to add a command to the ribbon. Commands can be in the ribbon, they can be buttons or context menus. Context menus are in Excel only. The next set of add-ins are contents which are rich web contents embedded within a document like a Chart. Contextual popups are supported only in Outlook and it enables developers to register a regular expression. The last add-ins are the modules, like in Outlook the Calendar, Mail.

The power of the platform, you can reach any device now:

Add-in examples in desktop and web

You can insert content add-ins directly in OneNote. There are a couple of symmetries across clients. Build an add-in once and run it in multiple clients. This isn’t true for every add-in, but some add-ins can be built to work in Word, Excel, PowerPoint and so on.

What kind of complex things can you do with add-ins? Qorus Document Builder, document template solution in Word, e.g. generate contracts from a template. Store the templates in OneDrive. Qorus connect to OneDrive and searches for the template. Solution that start to span across all of Office.

  • Add-in VSTS in Outlook, to easily create bugs out of an email.
  • Add-in Trello in Outlook, creates a new card in Trello out of an email.
  • Bommerang.
  • EverNote.
  • Salesforce.

New feature released in January: pin a task pane to stay open. The API is connected to one email but now the task pane stays one and refreshes automatically.

Add-ins on mobile

One of the exciting things is bringing add-ins to mobile. There is a strict set of UI guidelines for mobile, add-ins should feel like part of Office. Same set of add-ins also on mobile, build an add-in once and run it everywhere.

The UI looks different, you have to write different UI for mobile and desktop but the business logic is the same. The view will be different but the model, viewmodel and controllers will work the same way.

Get focused on the most important action and scenario that makes sense on a mobile device, that answer will be different on desktop. The average session in Outlook mobile is 24 seconds, 3 seconds in an add-in.

The add-in should feel 80% like in the environment that it is in and 20% brand. Working with Office UI Fabric that will generate the UI for each device, for now recommend using framework

It’s important to nail the scenario and nail the UI.

Building great add-ins

Create delightful UI by leveraging Office UI Fabric and following Office US patterns.

Use add-ins command by creating commands for actions, creating groups and tabs to group functionality, totally 66 buttons.

Use popup dialog for Auth by minimizing sign-in promps, using identity token for SSO in Outlook.

Be lightning fast, by using async operations, add-in should load in 500 ms or less.

Getting started

Go to, for Outlook is the place to go.

  • Visual Studio has project templates to help you get going.
  • Use Yeoman project generator.


  1. The manifest defines the host, extension points like buttons with actions.
  2. Build the UI for the button. Many ways to do it, for example use editor Plunkr at, side-by-side view.
    1. Add references.
      1. Bootstrap free themes.
      2. Trello API.
    2. Add code in html file.
    3. Add code in js file.
  3. Download it as zip file, grab the html and js files. Let’s hook it up to Outlook by initializing Office and interacting with it.
    1. Add reference to office.js
  4. The add-in has to be hosted on a url. Let’s deploy it to Azure (copy to site/wwwroot) and load up the add-in.

UI-less button

  1. In the manifest: extension point with Action type executeFunction with name.
  2. New html file with references only
  3. New js file.
    1. initialize is empty.
    2. Office will invoke the function from the manifest. Function has event parameter. Callback with success calling Office.context.mailbox.item.NotificationMessages to post feedback to the user. The last part is event.completed() so Office knows that you are done, if user navigates away before you are done then the user will be prompted.

What’s next

  • Parity across Office clients
  • Pinnable task pane on Web and Mac
  • OneNote add-ins on all platforms
  • Simplifying auth with AAD
  • Ui and performance improvements, add-ins to perform natively seamless for users
  • More APIs coming

Links and resources

  • Developer resources at, for Outlook at
  • Join the Office 365 developer program.
  • Interact on stackoverflow, all the engineers are on on-call rotation to monitor and answer questions on stackoverflow.
  • Upcoming hackathon at