Configure Office Add‐in capability within your Teams app

Configure Office Add-in capability within your Teams app

Introduction

Office Add-ins are web apps that extend the functionality of Outlook, Word, Excel and PowerPoint. An Office Add-in consists of two parts.

• The add-in manifest that defines the settings and capabilities of the add-in.
• The web application that defines the UI and functionality of add-in components such as task panes, content add-ins, and dialog boxes.

The web application uses the Office JavaScript API to interact with content in the Office document where the add-in is running. Your add-in can also do other things that web applications typically do, like call external web services, facilitate user authentication, and more.

For more information, start with Office Add-ins Overview.

Prerequisites

To configure an Office Add-in as additional capability, you must meet the following conditions:

• You have a Microsoft 365 account that includes Teams, or separate subscriptions to both Microsoft 365 and Teams, to test the application. For example, an.onmicrosoft.com account.
• Node.js (the latest LTS version). Visit the Node.js site to download and install the right version for your operating system.

Overview

The following are the major steps to adding an Office Add-in to a Teams app. Details are in the sections below.

1. Prepare the Teams app project
2. Create an Office Add-in project that is initially separate from your Teams app project.
3. Merge the manifest from the Office Add-in project into the unified Microsoft 365 manifest.
4. Copy the Office Add-in files to the Teams app project.
5. Edit the tooling configuration files.
6. Run the app and add-in locally at the same time

Prepare the Teams app project

Begin by separating the source code for the tab (or bot) into its own subfolder. These instructions assume that the project initially has the following structure. To create a Teams app project with this structure, be sure you are using the latest released version of Teams Toolkit.

|-- .vscode/
|-- appPackage/
|-- build
|-- env/
|-- infra/
|-- node_modules/
|-- src/
|-- .gitignore
|-- .localConfigs
|-- .webappignore
|-- package-lock.json
|-- package.json
|-- teamsapp.local.yml
|-- teamsapp.yml
|-- tsconfig.json
|-- web.config

NOTE: If you are working with a new Teams tab project, the node_modules folder and the package-lock.json file will not be present. The node_modules is created in a later step when you run npm install in the root of the project. The build folder will not be present unless and until you run a build script on the project.

1. Create a folder under the root named "tab" (or "bot").

   NOTE: For simplicity, the remainder of this article assumes that the existing Teams app is a tab. If you started with a bot instead, replace "tab" with "bot" in all of these instructions, including the content you add or edit in various files.

2. Copy the infra folder into the new subfolder, and then delete the azure.parameters.json file from the new tab/infra folder.

3. Move the node_modules and src folders into the new subfolder.

4. Move the .webappignore, package-lock.json, package.json, tsconfig.json, and web.config files into the new subfolder.

|-- .vscode/
|-- appPackage/
|-- build
|-- env/
|-- infra/
|-- tab/
|-- |-- infra/
|-- |-- node_modules/
|-- |-- src/
|-- |-- .webappignore
|-- |-- package-lock.json
|-- |-- package.json
|-- |-- tsconfig.json
|-- |-- web.config
|-- .gitignore
|-- .localConfigs
|-- teamsapp.local.yml
|-- teamsapp.yml

5. In the package.json that you just moved to the tab folder, delete the script named "dev:teamsfx" from the "scripts" object. This script is added to a new package.json in the next step.

6. Create a new file named package.json in the root of the project and give it the following content:

{
    "name": "CombinedTabAndAddin",
    "version": "0.0.1",
    "author": "Contoso",
    "scripts": {
        "dev:teamsfx": "env-cmd --silent -f .localConfigs npm run start:tab",
        "build:tab": "cd tab && npm run build",
        "install:tab": "cd tab && npm install",
        "start:tab": "cd tab && npm run start",
        "test": "echo \"Error: no test specified\" && exit 1"
    },
    "devDependencies": {
        "@microsoft/teamsfx-cli": "2.0.2-alpha.4f379e6ab.0",
        "@microsoft/teamsfx-run-utils": "alpha",
        "env-cmd": "^10.1.0",
        "office-addin-dev-settings": "^2.0.3",
        "ncp": "^2.0.0"
    }
}

7. Change the "name", "version", and "author" properties, as needed.

8. Open the teamsapp.yml file in the root of the project and find the line ignoreFile: .webappignore. Change this to ignoreFile: ./tab/.webappignore.

9. Open the teamsapp.local.yml file in the root of the project and find the line args: install --no-audit. Change this to args: run install:tab --no-audit.

10. Open TERMINAL in Visual Studio Code. Navigate to the root of the project and run npm install. Among other things, a new node_modules folder and a new package.lock.json file are created in the project root.

11. Next run npm run install:tab. Among other things, a new node_modules folder and a new package.lock.json file are created are created in the tab folder, if they aren't there already.

12. Verify that you can sideload the tab with the following steps:

    i. Open Teams Toolkit, and in the ACCOUNTS section, verify that you are signed into Microsoft 365.

    ii. Select View | Run in Visual Studio Code.

    iii. In the RUN AND DEBUG drop down menu, select the option, Debug in Teams (Edge), and then press F5. The project will build and run. This process may take a couple of minutes. Eventually, Teams opens in a browser with a prompt to add your tab app.

    Note a: If this is the first time you've debugged a Teams app on this computer, you will be prompted to install an SSL certificate. Select Install and then Yes to the second prompt. Login to your Microsoft 365 account if you are prompted to do so.

    Note b: We recommend you use the release version of Teams Toolkit extension to generate the Teams tab project, or you might run into the following problem: If you have to use private build version anyway, you need to add 2 environment variables below to your system to run the app:

    SIDELOADING_SERVICE_ENDPOINT = https://titles.prod.mos.microsoft.com/
    SIDELOADING_SERVICE_SCOPE = https://titles.prod.mos.microsoft.com/.default
    

    iv. Select Add.

    v. To stop debugging and uninstall the app, select Run | Stop Debugging in Visual Studio Code.

Create an Office add-in project

1. Open a second instance of Visual Studio Code.

2. With Teams Toolkit open in Visual Studio Code, select Create a new app.

3. In the Select an option drop down, select Office add-in, and then select Taskpane.

4. Select the folder where you want to create the add-in.

5. Give a name (with no spaces) to the project when prompted and Teams Toolkit will create the project with basic files and scaffolding and open it in a separate Visual Studio Code window. You will used this project as a source for files and markup that you add to the Teams project.

6. Although you won't be developing this project, verify that it can be sideloaded from Visual Studio Code before you continue. Use the following steps:

   Note: Office includes Word Excel and PowerPoint, the following will be used to Excel as an example.

   i. First, make sure Excel desktop is closed.

   ii. In Visual Studio Code, open the Teams Toolkit.

   iii. In the ACCOUNTS section, verify that you are signed into Microsoft 365.

   iv.Select View | Run in Visual Studio Code. In the RUN AND DEBUG drop down menu, select the option, Excel Desktop (Edge Chromium), and then press F5. The project builds and a Webpack dev-server window opens. This process may take a couple of minutes. Eventually, Excel desktop will open.

   v. Click the Add-ins button on Home Tab ribbon, will show the flyout. Developer Add-ins will be shown in flyout, Click your Add-ins.

   vi. Select any range of cells in the worksheet. At the bottom of the task pane, choose the Run link to set the color of the selected range to yellow.

   vii. To stop debugging and uninstall the add-in, select Run | Stop Debugging in Visual Studio Code. If the Webpack dev-server window does not close, open the Visual Studio Code TERMINAL in the root of the project and run npm stop.

Merge the manifest

The Teams app's manifest is generated at debug-and-sideload time (or build time) from the file manifest.json in the \appPackage folder of the Teams project. This file is actually a kind of template for a manifest. In this article it is referred to as the "template" or "manifest template". Most of the markup is hardcoded into the template, but there are also some configuration files that contain data that gets injected into the final generated manifest. In this procedure, you do the following:

• Copy markup from the add-in's manifest to the Teams app's manifest template.
• Edit the configuration files.

Unless specified otherwise, the file you change is \appPackage\manifest.json.

1. Copy the "$schema" and "manifestVersion" property values from the add-in's manifest to the corresponding properties of the Teams app's manifest template file.

2. Adjust the "name.full", "description.short", and "description.full" property values as needed to take account of the fact that an Office add-in is part of the app.

3. Do the same for the "name.short" value. We recommend that you keep the ${{TEAMSFX_ENV}} on the end of the name. This variable is replaced with "local" when you are debugging on localhost and with "dev" when you are either debugging from a remote domain or in production mode. (Historically, Office Add-in developer documentation has used the term "dev" or "dev mode" to refer to running the add-in on a localhost. It has used the term "prod" or "production mode" to refer to running the add-in on a remote host for staging or production. Teams developer documentation has used the term "local" to refer to running the add-in on a localhost, and the term "dev" to refer to running the add-in on a remote host for remote debugging, which is usually called "staging". We are working on getting the terminology consistent.)

   The following is an example:

   "short": "Contoso Tab and Add-in-${{TEAMSFX_ENV}}",

   Notes: The "name.short" value appears in both the Teams tab capability and the Office add-in. Examples:

   • It is the label under the launch button of the Teams tab.
   • It is content of the title bar of the add-in's task pane.

4. If you changed the "name.short" value from its default (which is the name of the project followed by the ${{TEAMSFX_ENV}} variable), make exactly the same change in all places where the project name appears in the following two files in the root of the project: teamsapp.yml and teamsapp.local.yml.

5. If there is no "authorization.permissions.resourceSpecific" array in the Teams manifest template, copy it from the add-in manifest as a top-level property. If there already is one in the Teams template, copy any objects from the array in the add-in manifest to the array in the Teams template. The following is an example:

   "authorization": {
           "permissions": {
               "resourceSpecific": [
                   {
                       "name": "MailboxItem.Read.User",
                       "type": "Delegated"
                   },
                   {
                       "name": "Document.ReadWrite.User",
                       "type": "Delegated"
                   }
               ]
           }
       },
   

6. In the env/.env.local file, find the lines that assign values to the TAB_DOMAIN and TAB_ENDPOINT variables. Add the following lines immediately below them:

   ADDIN_DOMAIN=localhost:3000
   ADDIN_ENDPOINT=https://localhost:3000
   

7. In the env/.env.dev file, add the following line just below the TAB_ENDPOINT= ... line:

   ADDIN_ENDPOINT=
   

8. In the Teams manifest template, add the placeholder "${{ADDIN_DOMAIN}}", to the top of the "validDomains" array. The Teams Toolkit will replace this with a localhost domain when you are developing locally. When you deploy the finished combined app to staging or production, Teams Toolkit will replace the placeholder with the staging/production URI. The following is an example:

   "validDomains": [
       "${{ADDIN_DOMAIN}}",
   
       // other domains or placeholders
   ],
   

9. Copy the entire "extensions" property from the add-in's manifest into the Teams app manifest template as a top-level property.

10. Copy the color.png and outline.png files from the appPackage directory of the add-in project to the appPackage/build directory of the Teams app project.

Copy the Office Add-in files to the Teams app project

1. Create a top-level folder called "add-in" in the Teams app project.
2. Copy the following files and folders frrom the add-in project to the "add-in" folder of the Teams app project.
   • /appPackage
   • /infra
   • /src
   • .eslintrc.json
   • babel.config.json
   • package-lock.json
   • package.json
   • tsconfig.json
   • webpack.config.js
3. When you have finished the copy, delete the manifest.json file in the /add-in/appPackage folder. Your folder structure should now look like the following:

   |-- .vscode/
   |-- add-in/
   |-- |-- appPackage/assets/
   |-- |-- infra/
   |-- |-- src/
   |-- |-- .eslintrc.json
   |-- |-- babel.config.json
   |-- |-- package-lock.json
   |-- |-- package.json
   |-- |-- tsconfig.json
   |-- |-- webpack.config.js
   |-- appPackage/
   |-- build\appPackage/
   |-- env/
   |-- infra/
   |-- node_modules/
   |-- tab/
   |-- |-- infra/
   |-- |-- node_modules/
   |-- |-- src/
   |-- |-- .webappignore
   |-- |-- package-lock.json
   |-- |-- package.json
   |-- |-- tsconfig.json
   |-- |-- web.config
   |-- .gitignore
   |-- .localConfigs
   |-- package.json
   |-- teamsapp.local.yml
   |-- teamsapp.yml
   

Edit the tooling configuration files

1. Open the package.json file in the root of the project.

2. Add the following scripts to the "scripts" object:

   "install:add-in": "cd add-in && npm install",
   "postinstall": "npm run install:add-in && npm run install:tab",
   "build:add-in": "cd add-in && npm run build",
   "build:add-in:dev": "cd add-in && npm run build:dev",
   "build": "npm run build:tab && npm run build:add-in",
   

3. Open the package.json file in the add-in folder (not the tab folder, and not the root of the project).

4. Three of the scripts in the "scripts" object have a manifest.json parameter like the following.

   "start": "office-addin-debugging start appPackage/manifest.json",
   "stop": "office-addin-debugging stop appPackage/manifest.json",
   "validate": "office-addin-manifest validate appPackage/manifest.json",
   

   In the "start" script, change appPackage/manifest.json to ../appPackage/build/appPackage.local.zip. When you are done, the line should look like this:

   "start": "office-addin-debugging start ../appPackage/build/appPackage.local.zip",
   

   In the "validate" and "stop" scripts, change the parameter to ../appPackage/build/manifest.local.json. When you are done, they should look like this:

   "stop": "office-addin-debugging stop ../appPackage/build/manifest.local.json",
   "validate": "office-addin-manifest validate ../appPackage/build/manifest.local.json",
   

5. In Visual Studio Code, open the TERMINAL. Navigate to the add-in folder, and then run the command npm install.

6. In the add-in folder, open the webpack.config.js file.

7. Change the line from: "appPackage/manifest*.json", to from: "../appPackage/build/manifest*.json",.

8. In the root of project, open the teamsapp.local.yml file and find the provision section. Use the # character to comment out the lines that validate the manifest template. This is necessary because the Teams manifest validation system is not yet compatible with the changes you made to the manifest template. When you are done, the lines should look like the following:

   # - uses: teamsApp/validateManifest
   #   with:
   #     # Path to manifest template
   #     manifestPath: ./appPackage/manifest.json
   

   Be careful to comment out only the teamsApp/validateManifest section. Do not comment out the teamsManifest/validateAppPackage section!

9. Repeat the preceding step for the teamsapp.yml file. The three lines are found in both the provision and the publish sections. Comment them out in both places.

10. Open the .vscode\tasks.json file in the add-in project and copy all of the tasks in the "tasks" array. Add them to "tasks" array of the same file in the Teams project. Do not remove any of the tasks that are already there. Be sure all tasks are separated by commas.

11. In each of the task objects that you just copied, add the following "options" property to ensure that these tasks run in the add-in folder.

        "options": {
        "cwd": "${workspaceFolder}/add-in/"
    }
    

    For example, the "Debug: Excel Desktop" task should like the following when you are done.

    {
        "label": "Debug: Excel Desktop",
        "type": "npm",
        "script": "start -- --app excel",
        "presentation": {
            "clear": true,
            "panel": "dedicated"
        },
        "problemMatcher": [],
        "options": {
            "cwd": "${workspaceFolder}/add-in/"
        }
    },
    

12. Add the following task to the tasks array in the .vscode\tasks.json file of the project. Among other things, this will create the final manifest.

    {
        // Create the debug resources.
        // See https://aka.ms/teamsfx-tasks/provision to know the details and how to customize the args.
        "label": "Create resources",
        "type": "teamsfx",
        "command": "provision",
        "args": {
            "template": "${workspaceFolder}/teamsapp.local.yml",
            "env": "local"
        }
    },
    

13. Add the following task to the tasks array. Note that it adds a "Start Add-in Locally" task that combines the tab app's "Create resources" task with the add-in's debugging task and specifies that they must run in that order.

    {
        "label": "Start Excel Add-in Locally",
        "dependsOn": [
            "Create resources",
            "Debug: Excel Desktop"
        ],
        "dependsOrder": "sequence"
    },
    

14. Add the following task to the tasks array. It combines the "Start Teams App Locally" task with the "Start Add-in Locally" and specifies that they must run in that order.

    {
        "label": "Start App and Excel Add-in Locally",
        "dependsOn": [
            "Start Teams App Locally",
            "Start Excel Add-in Locally"
        ],
        "dependsOrder": "sequence"
    },
    

15. Open the .vscode\launch.json file in the project, which configures the RUN AND DEBUG UI in Visual Studio Code and add the following two objects to the top of the "configurations" array.

    {
        "name": "Launch Add-in Excel Desktop (Edge Chromium)",
        "type": "msedge",
        "request": "attach",
        "port": 9229,
        "timeout": 600000,
        "webRoot": "${workspaceRoot}",
        "preLaunchTask": "Start Excel Add-in Locally",
        "postDebugTask": "Stop Debug"
    },
    {
        "name": "Launch App and Add-in Excel Desktop (Edge Chromium)",
        "type": "msedge",
        "request": "attach",
        "port": 9229,
        "timeout": 600000,
        "webRoot": "${workspaceRoot}",
        "preLaunchTask": "Start App and Excel Add-in Locally",
        "postDebugTask": "Stop Debug"
    },
    

16. Open the .vscode\launch.json file in the project, add the following two objects to the top of the "configurations" array.

    {
        "name": "Attach to Frontend in Excel (Edge)",
        "type": "msedge",
        "request": "launch",
        "url": "https://excel.office.com/host/${{local:M365_APP_ID}}?${account-hint}",
        "cascadeTerminateToConfigurations": [
            "Attach to Local Service"
        ],
        "presentation": {
            "group": "all",
            "hidden": true
        },
        "internalConsoleOptions": "neverOpen"
    },
    {
        "name": "Attach to Frontend in Excel (Chrome)",
        "type": "chrome",
        "request": "launch",
        "url": "https://excel.office.com/host/${{local:M365_APP_ID}}?${account-hint}",
        "cascadeTerminateToConfigurations": [
            "Attach to Local Service"
        ],
        "presentation": {
            "group": "all",
            "hidden": true
        },
        "internalConsoleOptions": "neverOpen"
    },
    

17. Open the .vscode\launch.json file in the project, add the following two objects to the top of the "compounds" array.

    {
        "name": "Debug in Excel (Edge)",
        "configurations": [
            "Attach to Frontend in Excel (Edge)",
            "Attach to Local Service"
        ],
        "preLaunchTask": "Start Teams App Locally",
        "presentation": {
            "group": "group 4: Excel",
            "order": 1
        },
        "stopAll": true
    },
    {
        "name": "Debug in Excel (Chrome)",
        "configurations": [
            "Attach to Frontend in Excel (Chrome)",
            "Attach to Local Service"
        ],
        "preLaunchTask": "Start Teams App Locally",
        "presentation": {
            "group": "group 4: Excel",
            "order": 2
        },
        "stopAll": true
    },
    

18. In the "compounds" section of the same file, rename the "Debug in Teams (Edge)" compound to "Launch App Debug (Edge)", and rename the "Debug in Teams (Chrome)" compound to "Launch App Debug (Chrome)".

19. Verify that you can sideload the add-in capability of the Teams app to Excel with the following steps:

    i. First, make sure Excel desktop is closed.

    ii. In Visual Studio Code, open the Teams Toolkit.

    iii. In the ACCOUNTS section, verify that you are signed into Microsoft 365.

    iv. Select View | Run in Visual Studio Code. In the RUN AND DEBUG drop down menu, select the option, Launch Add-in Excel Desktop (Edge Chromium) (not any of the "Launch App ..." options), and then press F5. The project builds and a Webpack dev-server window opens. This process may take a couple of minutes. Eventually, Excel desktop will open.

    v. Click the Add-ins button on Home Tab ribbon, will show the flyout. Developer Add-ins will be shown in flyout, Click your Add-ins.

    vi. Select any range of cells in the worksheet. At the bottom of the task pane, choose the Run link to set the color of the selected range to yellow.

    vii. To stop debugging and uninstall the add-in, select Run | Stop Debugging in Visual Studio Code. If the Webpack dev-server window does not close, open the Visual Studio Code TERMINAL in the root of the project and run npm stop.

Run the app and add-in locally at the same time

You can sideload and run the app and the add-in simultaneously, but the debugger cannot reliably attach when both are running. So to debug, run only one at a time.

To debug the app, see the last step of the Prepare the Teams app project above.

To debug the add-in, see the last step of the Edit the tooling configuration files above.

To see both the app and the add-in running at the same time, take the following steps.

1. First, make sure Excel desktop is closed.

2. In Visual Studio Code, open the Teams Toolkit.

3. In the ACCOUNTS section, verify that you are signed into Microsoft 365.

4. Select View | Run in Visual Studio Code. In the RUN AND DEBUG drop down menu, select the option, Launch App and Add-in Excel Desktop (Edge Chromium), and then press F5. The project builds and a Webpack dev-server window opens to host the add-in. The tab app is hosted in the Visual Studio Code terminal. This process may take a couple of minutes. Eventually, both of the following will happen:

   • Teams opens in a browser with a prompt to add your tab app. If Teams has not opened by the time Excel desktop opens, then automatic sideloading has failed. You can manually sideload it to see both the app and the add-in running at the same time. For sideloading instructions, see Upload your app in Teams. You'll find the manifest.zip file to upload at C:\Users\{yourname}\AppData\Local\Temp.

   • Excel desktop opens.

5. In the Teams prompt, select Add and the tab will open.

6. In Excel, click the Add-ins button on Home Tab ribbon, will show the flyout. Developer Add-ins will be shown in flyout, Click your Add-ins. Select any range of cells in the worksheet. At the bottom of the task pane, choose the Run link to set the color of the selected range to yellow.

7. To stop debugging and uninstall the add-in, select Run | Stop Debugging in Visual Studio Code. If the Webpack dev-server window does not close, open the Visual Studio Code TERMINAL in the root of the project and run npm stop.

8. If you had to manually sideload the Teams Tab app, remove it from Teams as instructed in Remove your app.