Host an Office Add-in on Microsoft Azure

The simplest Office Add-in is made up of an XML manifest file and an HTML page. The XML manifest file describes the add-in's characteristics, such as its name, what Office client applications it can run in, and the URL for the add-in's HTML page. The HTML page is contained in a web app that users interact with when they install and run your add-in within an Office client application. You can host the web app of an Office Add-in on any web hosting platform, including Azure.

This article describes how to deploy an add-in web app to Azure and sideload the add-in for testing in an Office client application.

Prerequisites

  1. Install Visual Studio 2019 and choose to include the Azure development workload.

    Note

    If you've previously installed Visual Studio 2019, use the Visual Studio Installer to ensure that the Azure development workload is installed.

  2. Install Office.

    Note

    If you don't already have Office, you can register for a free 1-month trial.

  3. Obtain an Azure subscription.

    Note

    If don't already have an Azure subscription, you can get one as part of your Visual Studio subscription or register for a free trial.

Step 1: Create a shared folder to host your add-in XML manifest file

  1. Open File Explorer on your development computer.

  2. Right-click the C:\ drive and then choose New > Folder.

  3. Name the new folder AddinManifests.

  4. Right-click the AddinManifests folder and then choose Share with > Specific people.

  5. In File Sharing, choose the drop-down arrow and then choose Everyone > Add > Share.

Note

In this walkthrough, you're using a local file share as a trusted catalog where you'll store the add-in XML manifest file. In a real-world scenario, you might instead choose to deploy the XML manifest file to a SharePoint catalog or publish the add-in to AppSource.

Step 2: Add the file share to the Trusted Add-ins catalog

  1. Start Word and create a document.

    Note

    Although this example uses Word, you can use any Office application that supports Office Add-ins such as Excel, Outlook, PowerPoint, or Project.

  2. Choose File > Options.

  3. In the Word Options dialog box, choose Trust Center and then choose Trust Center Settings.

  4. In the Trust Center dialog box, choose Trusted Add-in Catalogs. Enter the universal naming convention (UNC) path for the file share you created earlier as the Catalog URL (for example, \\YourMachineName\AddinManifests), and then choose Add catalog.

  5. Select the check box for Show in Menu.

    Note

    When you store an add-in XML manifest file on a share that is specified as a trusted web add-in catalog, the add-in appears under Shared Folder in the Office Add-ins dialog box when the user navigates to the Insert tab in the ribbon and chooses My Add-ins.

  6. Close Word.

Step 3: Create a web app in Azure using the Azure portal

To create the web app using the Azure portal, complete the following steps.

  1. Log on to the Azure portal using your Azure credentials.

  2. Under Azure Services select Web Apps.

  3. On the App Service page, select Add. Provide this information:

    • Choose the Subscription to use for creating this site.

    • Choose the Resource Group for your site. If you create a new group, you also need to name it.

    • Enter a unique App name for your site. Azure verifies that the site name is unique across the azureweb apps.net domain.

    • Choose whether to publish using code or a docker container.

    • Specify a Runtime stack.

    • Choose the OS for your site.

    • Choose a Region.

    • Choose the App Service plan to use for creating this site.

    • Choose Create.

  4. The next page will let you know that your deployment is underway and when it completes. When it is completed, select Go to resource.

  5. In the Overview section, choose the URL that is displayed under URL. Your browser opens and displays a webpage with the message "Your App Service app is up and running."

    Important

    While not strictly required in all add-in scenarios, using an HTTPS endpoint for your add-in is strongly recommended. Add-ins that are not SSL-secured (HTTPS) generate unsecure content warnings and errors during use. If you plan to run your add-in in Office on the web or publish your add-in to AppSource, it must be SSL-secured. If your add-in accesses external data and services, it should be SSL-secured to protect data in transit. Self-signed certificates can be used for development and testing, so long as the certificate is trusted on the local machine. Azure websites automatically provide an HTTPS endpoint.

Step 4: Create an Office Add-in in Visual Studio

  1. Start Visual Studio as an administrator.

  2. Choose Create a new project.

  3. Using the search box, enter add-in.

  4. Choose Word Web Add-in as the project type, and then choose Next to accept the default settings.

Visual Studio creates a basic Word add-in that you'll be able to publish as-is, without making any changes to its web project. To make an add-in for a different Office host type, such as Excel, repeat the steps and choose a project type with your desired Office host.

Step 5: Publish your Office Add-in web app to Azure

  1. With your add-in project open in Visual Studio, expand the solution node in Solution Explorer, then select App Service.

  2. Right-click the web project and then choose Publish. The web project contains Office Add-in web app files so this is the project that you publish to Azure.

  3. On the Publish tab:

    • Choose Microsoft Azure App Service.

    • Choose Select Existing.

    • Choose Publish.

  4. Visual Studio publishes the web project for your Office Add-in to your Azure web app. When Visual Studio finishes publishing the web project, your browser opens and shows a webpage with the text "Your App Service app has been created." This is the current default page for the web app.

  5. Copy the root URL (for example: https://YourDomain.azurewebsites.net); you'll need it when you edit the add-in manifest file later in this article.

Step 6: Edit and deploy the add-in XML manifest file

  1. In Visual Studio with the sample Office Add-in open in Solution Explorer, expand the solution so that both projects show.

  2. Expand the Office Add-in project (for example WordWebAddIn), right-click the manifest folder, and then choose Open. The add-in XML manifest file opens.

  3. In the XML manifest file, find and replace all instances of "~remoteAppUrl" with the root URL of the add-in web app on Azure. This is the URL that you copied earlier after you published the add-in web app to Azure (for example: https://YourDomain.azurewebsites.net).

  4. Choose File and then choose Save All. Next, Copy the add-in XML manifest file (for example, WordWebAddIn.xml).

  5. Using the File Explorer program, browse to the network file share that you created in Step 1: Create a shared folder and paste the manifest file into the folder.

Step 7: Insert and run the add-in in the Office client application

  1. Start Word and create a document.

  2. On the ribbon, choose Insert > My Add-ins.

  3. In the Office Add-ins dialog box, choose SHARED FOLDER. Word scans the folder that you listed as a trusted add-ins catalog (in Step 2: Add the file share to the Trusted Add-ins catalog) and shows the add-ins in the dialog box. You should see an icon for your sample add-in.

  4. Choose the icon for your add-in and then choose Add. A Show Taskpane button for your add-in is added to the ribbon.

  5. On the ribbon of the Home tab, choose the Show Taskpane button. The add-in opens in a task pane to the right of the current document.

  6. Verify that the add-in works by selecting some text in the document and choosing the Highlight! button in the task pane.

See also