Edit

Share via

Stage an Office Add-in on Microsoft Azure with Visual Studio

  • Article

The simplest Office Add-in is made up of an manifest file and an HTML page. The manifest file describes the add-in's characteristics, such as its name, what Office desktop clients 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.

Important

The process described in this article doesn't apply to Outlook add-ins. For instructions about staging add-ins for Outlook on Azure, see Stage an Outlook Add-in on Microsoft Azure with Visual Studio.

Prerequisites

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

    Note

    If you've previously installed Visual Studio 2022, 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 manifest file

  1. Open File Explorer on your development computer.

  2. Right-click (or select and hold) the C:\ drive and then choose New > Folder.

  3. Name the new folder AddinManifests.

  4. Right-click (or select and hold) 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 manifest file. In a real-world scenario, you might instead choose to deploy the 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, 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 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 that launches from Home > Add-ins > Get Add-ins.

  6. Close Word.

Step 3: 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 application, such as Excel, repeat the steps and choose a project type with your desired Office application.

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

  1. With your add-in project open in Visual Studio, right-click (or select and hold) the web project and then choose Publish.

  2. Follow the instructions at Publish your web app. Skip the article sections that precede Publish your web app, but be sure that the Visual Studio button is selected at the top of the page.

    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 web app is running and waiting for your content." This is the current default page for the web app.

  3. 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 5: Edit and deploy the add-in 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 (or select and hold) the manifest folder, and then choose Open. The add-in manifest file opens.

  3. In the 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 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 6: Insert and run the add-in in the Office client application

  1. Start Word and create a document.

  2. Select Home > Add-ins, then select Get 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.

Deploy updates

You'll deploy updates to your web application in the same manner as described previously. Changes to the manifest require redistributing your manifest to users. The process to do so depends on your publishing method. For more information on updating your add-in, see Maintain your Office Add-in.

See also