diff --git a/docs/develop/convert-xml-to-json-manifest.md b/docs/develop/convert-xml-to-json-manifest.md index d6f0cbeb8b..fb955337ed 100644 --- a/docs/develop/convert-xml-to-json-manifest.md +++ b/docs/develop/convert-xml-to-json-manifest.md @@ -2,7 +2,7 @@ title: Convert an add-in to use the unified manifest for Microsoft 365 description: Learn the various methods for converting an add-in with an add-in only manifest to the unified manifest for Microsoft 365 and sideload the add-in. ms.topic: how-to -ms.date: 04/12/2024 +ms.date: 09/19/2024 ms.localizationpriority: medium --- @@ -10,11 +10,18 @@ ms.localizationpriority: medium To add Teams capabilities to an add-in that uses the add-in only manifest, or to just future proof the add-in, you need to convert it to use the unified manifest for Microsoft 365. +> [!NOTE] +> +> - Projects created in Visual Studio, as distinct from Visual Studio Code, can't be converted at this time. +> - If you [created the project with Teams Toolkit](teams-toolkit-overview.md) or with the "unified manifest" option in the [Yeoman generator for Office Add-ins (Yo Office)](yeoman-generator-overview.md), it already uses the unified manifest. + + [!INCLUDE [Unified manifest support note for Office applications](../includes/unified-manifest-support-note.md)] + There are three basic tasks to converting an add-in project from the add-in only manifest to the unified manifest. - Ensure that your add-in is ready to convert. - Convert the XML-formatted add-in only manifest itself to the JSON format of the unified manifest. -- Package the new manifest and the two icon image files into a zip file for sideloading or deployment. +- Package the new manifest and two icon image files (described later) into a zip file for sideloading or deployment. *Depending on how you sideload the converted add-in, this task may be done for you automatically.* [!INCLUDE [non-unified manifest clients note](../includes/non-unified-manifest-clients.md)] @@ -28,9 +35,20 @@ There are three basic tasks to converting an add-in project from the add-in only The following sections describe conditions that must be met before you convert the manifest. -### Ensure that you have the two image files +### Uninstall the existing version of the add-in + +To avoid conflicts with UI control names and other problems, be sure the existing add-in isn't installed on the computer where you do the conversion. + +### Ensure that you have two special image files + +If your add-in only manifest doesn't already have both **\** and **\** (in that order) elements, then add them just below the **\** element. The values of the **DefaultValue** attribute should be the full URLs of image files. The images must be a specified size as shown in the following table. -When you've added the files to the project, add **\** and **\** (in that order) to the add-in only manifest just below the **\** element. The following is an example. +|Office application|\|\| +|:---------------|:---------------|:---------------| +|Outlook|64x64 pixels|128x128 pixels| +|All other Office
applications|32x32 pixels|64x64 pixels| + +The following markup is an example. ```xml @@ -46,22 +64,34 @@ When you've added the files to the project, add **\** and **\ ``` -### Ensure that your function command names are short enough +### Update the add-in ID, version, domain, and function names in the manifest + +1. Change the value of the `` element to a new random GUID. + +1. Update the value of the `` element and ensure that it conforms to the [semver standard](https://semver.org/) (MAJOR.MINOR.PATCH). Each segment can have no more than five digits. For example, change the value `1.0.0.0` to `1.0.1`. The semver standard's prerelease and metadata version string extensions aren't supported. + +1. Be sure that the domain segment of the add-in's URLs in the manifest are pointing to `https://localhost:3000`. -If your manifest has any **\** elements, make sure their values have fewer than 65 characters. The value of this element must exactly match the name of a function in a JavaScript or TypeScript file. If you change it in the manifest, be sure to change it in the code file too. +1. If your manifest has any **\** elements, make sure their values have fewer than 65 characters. -### Ensure that your SSO add-in requests permissions + > [!IMPORTANT] + > The value of this element must exactly match the name of an action that's mapped to a function in a JavaScript or TypeScript file with the [Office.actions.associate](/javascript/api/office/office.actions#office-office-actions-associate-member(1)) function. If you change it in the manifest, be sure to change it in the `actionId` parameter passed to `associate()` too. -If your add-in uses Microsoft single sign-on with the on-behalf-of (OBO) flow, your add-in has a **\** element that specifies the Microsoft Graph or other API permissions that the add-in needs. With the unified manifest, permissions must be requested at runtime in the code. Update your code as needed to request these permissions. The exact code depends on the architecture and authorization code libraries you are using. Typically, code requests permissions in a function that requests an access token. +### Verify that the modified add-in only manifest works +1. Validate the modified add-in only manifest. See [Validate an Office Add-in's manifest](../testing/troubleshoot-manifest.md). + +1. Verify that the add-in can be sideloaded and run. See [Sideload an Office Add-in for testing](../testing/test-debug-office-add-ins.md#sideload-an-office-add-in-for-testing). + +Resolve any problems before you attempt to convert the project. ## Conversion tools and options There are several ways to carry out the remaining tasks, depending on the IDE and other tools you want to use for your project, and on the tool you used to create the project. - [Convert the project with Teams Toolkit](#convert-the-project-with-teams-toolkit) -- [Projects created with the Office Yeoman Generator (aka "Yo Office")](#projects-created-with-the-office-yeoman-generator-aka-yo-office) -- [NodeJS and npm projects that aren't created with Yeoman Generator](#nodejs-and-npm-projects-that-arent-created-with-yeoman-generator) +- [Convert projects created with the Yeoman generator for Office Add-ins (aka "Yo Office")](#convert-projects-created-with-the-yeoman-generator-for-office-add-ins-aka-yo-office) +- [Convert NodeJS and npm projects that weren't created with the Yeoman generator for Office Add-ins (Yo Office)](#convert-nodejs-and-npm-projects-that-werent-created-with-the-yeoman-generator-for-office-add-ins-yo-office) ### Convert the project with Teams Toolkit @@ -78,43 +108,33 @@ The easiest way to convert is to use Teams Toolkit. :::image type="content" source="../images/teams-toolkit-icon.png" alt-text="Teams Toolkit icon."::: -1. Select **Create a new app**. -1. In the **New Project** drop down, select **Outlook Add-in**. +1. Select **Create a New App**. +1. In the **New Project** dropdown menu, select **Office Add-in**. - :::image type="content" source="../images/teams-toolkit-create-outlook-add-in.png" alt-text="The four options in New Project drop down. The fourth option is called 'Outlook add-in'."::: + :::image type="content" source="../images/teams-toolkit-create-office-add-in.png" alt-text="The five options in New Project dropdown menu. The fifth option is called 'Office Add-in'."::: -1. In the **App Features Using an Outlook Add-in** drop down, select **Import an Existing Outlook Add-in**. +1. In the **App Features Using an Office Add-in** dropdown menu, select **Import an Existing Office Add-in**. - :::image type="content" source="../images/teams-toolkit-create-outlook-task-pane-capability.png" alt-text="The two options in the App Features Using an Outlook Add-in drop down. The second option is called 'Import an Existing Outlook add-in'."::: + :::image type="content" source="../images/teams-toolkit-create-office-task-pane-capability.png" alt-text="The three options in the App Features Using an Office Add-in dropdown menu. The third option is called 'Import an Existing Office Add-in'."::: -1. In the **Existing add-in project folder** drop down, browse to the root folder of the add-in project. -1. In the **Select import project manifest file** drop down, browse to the add-in only manifest file, typically named **manifest.xml**. +1. In the **Existing add-in project folder** dropdown menu, browse to the root folder of the add-in project. +1. In the **Select import project manifest file** dropdown menu, browse to the add-in only manifest file, typically named **manifest.xml**. 1. In the **Workspace folder** dialog, select the folder where you want to put the converted project. 1. In the **Application name** dialog, give a name to the project (with no spaces). Teams Toolkit creates the project with your source files and scaffolding. It then opens the project *in a second Visual Studio Code window*. Close the original Visual Studio Code window. #### Sideload the add-in in Visual Studio Code -You can sideload the add-in using the Teams Toolkit or in a command prompt, bash shell, or terminal. - -##### Sideload with the Teams Toolkit +You can sideload the add-in using the Teams Toolkit or in a command prompt, bash shell, or terminal. For more information, see: -1. First, *make sure Outlook desktop is closed.* -1. In Visual Studio Code, open the Teams Toolkit. -1. In the **ACCOUNTS** section, verify that you're signed into Microsoft 365. -1. Select **View** | **Run** in Visual Studio Code. In the **RUN AND DEBUG** drop down menu, select the option, **Outlook Desktop (Edge Chromium)**, and then press **F5**. The project builds and a Node dev-server window opens. This process may take a couple of minutes and then Outlook desktop opens. -1. You can now work with your add-in. Be sure you're working in the **Inbox** of *your Microsoft 365 account identity*. +- [Sideload with Teams toolkit](../testing/sideload-add-in-with-unified-manifest.md#sideload-with-the-teams-toolkit) +- [Sideload with a system prompt, bash shell, or terminal](../testing/sideload-add-in-with-unified-manifest.md#sideload-with-a-system-prompt-bash-shell-or-terminal) -##### Sideload with a system prompt, bash shell, or terminal +> [!NOTE] +> Add-ins that use the unified manifest can be sideloaded only on Office Version 2304 (Build 16320.20000) or later. -1. First, *make sure Outlook desktop is closed.* -1. Open a system prompt, bash shell, or the Visual Studio Code **TERMINAL**, and navigate to the root of the project. -1. Run the command `npm run start:desktop`. The project builds and a Node dev-server window opens. This process may take a couple of minutes then Outlook desktop opens. -1. You can now work with your add-in. -1. When you're done working with your add-in, make sure to run the command `npm run stop`. +### Convert projects created with the Yeoman generator for Office Add-ins (aka "Yo Office") -### Projects created with the Office Yeoman Generator (aka "Yo Office") - -If the project was created with the Office Yeoman Generator and you don't want to use the Teams Toolkit, convert it using the following steps. +If the project was created with the Yeoman generator for Office Add-ins and you don't want to use the Teams Toolkit, convert it using the following steps. 1. In the root of the project, open a command prompt or bash shell and run the following command. This converts the manifest and updates the package.json to specify current tooling packages. The new unified manifest is in the root of the project and the old add-in only manifest is in a backup.zip file. For details about this command, see [Office-Addin-Project](https://www.npmjs.com/package/office-addin-project). @@ -123,13 +143,11 @@ If the project was created with the Office Yeoman Generator and you don't want t ``` 1. Run `npm install`. -1. To sideload the add-in, run `npm run start:desktop`. This command puts the unified manifest and the two image files into a zip file and sideloads it to the Office application. It also starts the server in a separate NodeJS window to host the add-in files on localhost. - -When you're ready to stop the dev server and uninstall the add-in, run the command `npm run stop`. +1. To sideload the add-in, see [Sideload add-ins created with the Yeoman generator for Office Add-ins (Yo Office)](../testing/sideload-add-in-with-unified-manifest.md#sideload-add-ins-created-with-the-yeoman-generator-for-office-add-ins-yo-office). -### NodeJS and npm projects that aren't created with Yeoman Generator +### Convert NodeJS and npm projects that weren't created with the Yeoman generator for Office Add-ins (Yo Office) -If you don't want to use the Teams Toolkit and your project wasn't created with the Office Yeoman generator, use the office-addin-manifest-converter tool. +If you don't want to use the Teams Toolkit and your project wasn't created with Yo Office, use the office-addin-manifest-converter tool. In the root of the project, open a command prompt or bash shell and run the following command. This command puts the unified manifest in a subfolder with the same name as the filename stem of the original add-in only manifest. For example, if the manifest is named **MyManifest.xml**, the unified manifest is created at **.\MyManifest\MyManifest.json**. For more details about this command, see [Office-Addin-Manifest-Converter](https://www.npmjs.com/package/office-addin-manifest-converter). @@ -137,36 +155,9 @@ In the root of the project, open a command prompt or bash shell and run the foll npx office-addin-manifest-converter convert ``` -Once you have the unified manifest created, there are two ways to create the zip file and sideload it. They are described in the next two subsections. - -#### Sideload with the Office-Addin-Debugging tool - -1. To sideload the add-in, run the following command. This command puts the unified manifest and two default icon image files into a zip file and sideloads it to the Office application. It also starts a server in a separate NodeJS window to host the add-in files on localhost. Note that you pass the path to the *unified manifest* that you created in the previous step. For more details about this command, see [Office-Addin-Debugging](https://www.npmjs.com/package/office-addin-debugging). - - ```command line - npx office-addin-debugging start desktop - ``` - -1. When you use office-addin-debugging to start an add-in, *always stop the session with the following command*. Closing the server window doesn't reliably stop the server and closing the Office application doesn't reliably cause Office to unacquire the add-in. - - ```command line - npx office-addin-debugging stop - ``` - -#### Sideload with the Teams Toolkit CLI (command-line interface) - -1. Manually create the zip package using the following steps. - - 1. Open the unified manifest and scroll to the "icons" property. Note the relative path of the two image files. - 1. Use any zip utility to create a zip file that contains the unified manifest and the two image files. *The image files must have the same relative path in the zip file as they do in the project.* For example, if the relative path is "assets/icon-64.png" and "assets/icon-128.png", then you must include the "assets" folder with the two files in the zip package. - 1. If the folder contains other files, such as image files used in the Office ribbon, remove these from the zip package. It should have only the two image files specified in the "icons" property (in addition to the manifest in the root of the zip package). - -1. In the root of the project, open a command prompt or bash shell and run the following commands. - - ```command line - npm install -g @microsoft/teamsfx-cli +Once you have the unified manifest created, there are two ways to create the zip file and sideload it. For more information, see [Sideload other NodeJS and npm projects](../testing/sideload-add-in-with-unified-manifest.md#sideload-other-nodejs-and-npm-projects). - teamsfx m365 sideloading --file-path - ``` +## Next steps +Consider whether to maintain both the old and new versions of the add-in. See [Manage both a unified manifest and an add-in only manifest version of your Office Add-in](../concepts/duplicate-legacy-metaos-add-ins.md). diff --git a/docs/develop/teams-toolkit-overview.md b/docs/develop/teams-toolkit-overview.md index 70fbefed84..74f6dea45e 100644 --- a/docs/develop/teams-toolkit-overview.md +++ b/docs/develop/teams-toolkit-overview.md @@ -1,47 +1,90 @@ --- title: Create Office Add-in projects using Teams Toolkit description: Learn how to create Office Add-in projects using Teams Toolkit. -ms.date: 04/12/2024 +ms.date: 09/19/2024 ms.localizationpriority: high --- # Create Office Add-in projects with Teams Toolkit -A primary tool for developing Teams Apps is Teams Toolkit. You can create Office Add-ins with Teams Toolkit, with the following restrictions. +A primary tool for developing Teams Apps is Teams Toolkit. You can create Office Add-ins with Teams Toolkit. -- Add-ins created with Teams Toolkit use the [unified manifest for Microsoft 365](unified-manifest-overview.md). -- Only Outlook add-ins can be created at this time. We're working hard to enable support in Teams Toolkit for add-ins to other Office applications and platforms. +Add-ins created with Teams Toolkit use the [unified manifest for Microsoft 365](unified-manifest-overview.md). + + [!INCLUDE [Unified manifest support note for Office applications](../includes/unified-manifest-support-note.md)] + +> [!TIP] +> There's another Visual Studio Code extension that creates Office Add-ins that use the add-in only manifest. See [Create Office Add-in projects using Office Add-ins Development Kit for Visual Studio Code](development-kit-overview.md). [!INCLUDE [non-unified manifest clients note](../includes/non-unified-manifest-clients.md)] Install the latest version of Teams Toolkit into Visual Studio Code as described in [Install Teams Toolkit](/microsoftteams/platform/toolkit/install-teams-toolkit?tabs=vscode). -## Create an Outlook Add-in project +## Create an Office Add-in project 1. Open Visual Studio Code and select Teams Toolkit icon in the **Activity Bar**. :::image type="content" source="../images/teams-toolkit-icon.png" alt-text="Teams Toolkit icon."::: -1. Select **Create a new app**. -1. In the **New Project** drop down, select **Outlook add-in**. +1. Select **Create a New App**. +1. In the **New Project** dropdown menu, select **Office Add-in**. - :::image type="content" source="../images/teams-toolkit-create-outlook-add-in.png" alt-text="The four options in New Project drop down. The fourth option is called 'Outlook add-in'."::: + :::image type="content" source="../images/teams-toolkit-create-office-add-in.png" alt-text="The five options in New Project dropdown menu. The fifth option is called 'Office Add-in'."::: -1. In the **App Features Using an Outlook Add-in** drop down, select **Taskpane**. +1. In the **App Features Using an Office Add-in** dropdown menu, select **Taskpane** or **Content Add-in**. (For simplicity, the remainder of this article assumes you selected **Taskpane**. For more information about content add-ins, see [Content Office Add-ins](../design/content-add-ins.md).) - :::image type="content" source="../images/teams-toolkit-create-outlook-task-pane-capability.png" alt-text="The two options in the App Features Using an Outlook Add-in drop down. The first option 'Taskpane' is selected."::: + :::image type="content" source="../images/teams-toolkit-create-office-task-pane-capability.png" alt-text="The three options in the App Features Using an Office Add-in dropdown menu. The first option 'Taskpane' is selected."::: -1. In the **Workspace folder** dialog that opens, select the folder where you want to create the project. +1. In the **Programming Language** dropdown menu, select either **TypeScript** or **JavaScript**. +1. In the **Framework** dropdown menu, select **Default** or **React**. +1. In the **Workspace Folder** dialog that opens, select the folder where you want to create the project. 1. Give a name to the project (with no spaces) when prompted. Teams Toolkit will create the project with basic files and scaffolding. It will then open the project *in a second Visual Studio Code window*. Close the original Visual Studio Code window. + + > [!NOTE] + > The project that's generated is configured to be installable on Excel, Outlook, PowerPoint, and Word. You can edit the manifest and source files as needed to change which Office applications are supported. + 1. In the Visual Studio Code **TERMINAL** navigate to the root of the project and run `npm install`. -1. Before you make changes to the project, verify that you can sideload your Outlook add-in from Visual Studio Code. Use the following steps: - 1. Ensure that your account in your Microsoft 365 developer tenancy is also an email account in desktop Outlook. If it isn't, follow the guidance in [Add an email account to Outlook](https://support.microsoft.com/office/add-an-email-account-to-outlook-e9da47c4-9b89-4b49-b945-a204aeea6726). - 1. **Close Outlook desktop**. - 1. In Visual Studio Code, open Teams Toolkit. - 1. In the **ACCOUNTS** section, verify that you're signed into Microsoft 365. - 1. Select **View** | **Run** in Visual Studio Code. In the **RUN AND DEBUG** drop down menu, select the option, **Outlook Desktop (Edge Chromium)**, and then press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, Outlook desktop will open. - 1. Open the **Inbox** *of your Microsoft 365 account identity* and open any message. A **Contoso Add-in** tab with two buttons will appear on the **Home** ribbon (or the **Message** ribbon, if you have opened the message in its own window). - 1. Click the **Show Taskpane** button and a task pane opens. Click the **Perform an action** button and a small notification appears near the top of the message. - 1. To stop debugging and uninstall the add-in, select **Run** | **Stop Debugging** in Visual Studio Code. +1. After the installation completes, verify that you can sideload your add-in from Visual Studio Code. The steps to sideload vary depending on the Office application on which you want to test the add-in. + +### Sideload in Excel, PowerPoint, or Word + +1. Select **View** | **Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select one of these options: + + - **Excel Desktop (Edge Chromium)** + - **PowerPoint Desktop (Edge Chromium)** + - **Word Desktop (Edge Chromium)** + +1. Press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, the desktop version of the Office application you selected opens. + + > [!NOTE] + > If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts. + +1. A **Contoso Add-in** tab with two buttons will appear on the **Home** ribbon. Use one button to perform an action in the open Office document. Use the other to open the add-in's task pane. + + > [!NOTE] + > Regardless of which button you select, a **WebView Stop On Load** prompt appears. Select **OK**. + +1. To stop debugging and uninstall the add-in, select **Run** | **Stop Debugging** in Visual Studio Code. + +### Sideload in Outlook + +1. Ensure that your account in your Microsoft 365 developer tenancy is also an email account in desktop Outlook. If it isn't, follow the guidance in [Add an email account to Outlook](https://support.microsoft.com/office/e9da47c4-9b89-4b49-b945-a204aeea6726). +1. **Close Outlook desktop**. +1. In Visual Studio Code, open Teams Toolkit. +1. In the **ACCOUNTS** section, verify that you're signed into Microsoft 365. +1. Select **View** | **Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select the option, **Outlook Desktop (Edge Chromium)**, and then press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes and then Outlook desktop will open. + + > [!NOTE] + > If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts. + +1. Open the **Inbox** *of your Microsoft 365 account identity* and open any message. A **Contoso Add-in** tab with two buttons will appear on the **Home** ribbon (or the **Message** ribbon, if you have opened the message in its own window). +1. Click the **Show Taskpane** button and a task pane opens. Click the **Perform an action** button and a small notification appears near the top of the message. + + > [!NOTE] + > Regardless of which button you select, a **WebView Stop On Load** prompt appears. Select **OK**. + +1. To stop debugging and uninstall the add-in, select **Run** | **Stop Debugging** in Visual Studio Code. + +## Developing your project Now you can change and develop the project. In places where the guidance in the Office Add-ins documentation branches depending on what type of manifest is being used, be sure to follow the guidance for the unified manifest. diff --git a/docs/images/teams-toolkit-create-office-add-in.png b/docs/images/teams-toolkit-create-office-add-in.png new file mode 100644 index 0000000000..650f05c740 Binary files /dev/null and b/docs/images/teams-toolkit-create-office-add-in.png differ diff --git a/docs/images/teams-toolkit-create-office-task-pane-capability.png b/docs/images/teams-toolkit-create-office-task-pane-capability.png new file mode 100644 index 0000000000..6a4c12463c Binary files /dev/null and b/docs/images/teams-toolkit-create-office-task-pane-capability.png differ diff --git a/docs/images/teams-toolkit-create-outlook-add-in.png b/docs/images/teams-toolkit-create-outlook-add-in.png deleted file mode 100644 index 9ddd42a92b..0000000000 Binary files a/docs/images/teams-toolkit-create-outlook-add-in.png and /dev/null differ diff --git a/docs/images/teams-toolkit-create-outlook-task-pane-capability.png b/docs/images/teams-toolkit-create-outlook-task-pane-capability.png deleted file mode 100644 index 537af1445e..0000000000 Binary files a/docs/images/teams-toolkit-create-outlook-task-pane-capability.png and /dev/null differ diff --git a/docs/includes/unified-manifest-sideload-restrictions-note.md b/docs/includes/unified-manifest-sideload-restrictions-note.md new file mode 100644 index 0000000000..1b3882d797 --- /dev/null +++ b/docs/includes/unified-manifest-sideload-restrictions-note.md @@ -0,0 +1,2 @@ +> [!NOTE] +> Currently, an add-in that uses the [Unified manifest for Microsoft 365](../develop/json-manifest-overview.md) cannot be sideloaded on the web, Mac, or iPad. To sideload an add-in with a unified manifest on Windows, see [Sideload Office Add-ins that uses the unified manifest for Microsoft 365](../testing/sideload-add-in-with-unified-manifest.md). \ No newline at end of file diff --git a/docs/outlook/sideload-outlook-add-ins-for-testing.md b/docs/outlook/sideload-outlook-add-ins-for-testing.md index f3ddcf8b26..024d8a6411 100644 --- a/docs/outlook/sideload-outlook-add-ins-for-testing.md +++ b/docs/outlook/sideload-outlook-add-ins-for-testing.md @@ -1,7 +1,7 @@ --- title: Sideload Outlook add-ins for testing description: Use sideloading to install an Outlook add-in for testing without having to first put it in an add-in catalog. -ms.date: 08/01/2024 +ms.date: 09/19/2024 ms.topic: how-to ms.localizationpriority: medium --- @@ -15,15 +15,7 @@ Sideload your Outlook add-in for testing without having to first put it in an ad ## Sideload an add-in that uses the unified app manifest for Microsoft 365 -The process to sideload an add-in that uses the unified app manifest for Microsoft 365 varies depending on the tool you used to create your add-in project. - -- For add-in projects created using the [Teams Toolkit](/microsoftteams/platform/toolkit/install-teams-toolkit?tabs=vscode), use one of the following options. - - [Sideload in Visual Studio Code with Teams Toolkit](../develop/convert-xml-to-json-manifest.md#sideload-with-the-teams-toolkit) - - [Sideload in Visual Studio Code with a system prompt, bash shell, or terminal](../develop/convert-xml-to-json-manifest.md#sideload-with-a-system-prompt-bash-shell-or-terminal) -- For add-in projects created using the [Yeoman generator for Office Add-ins](../develop/yeoman-generator-overview.md), in a command prompt, navigate to the root of your project. Then, run `npm run start:desktop`. The project builds and a Node dev-server window opens. This process may take a couple of minutes before it opens Outlook desktop. -- For NodeJS and npm projects that weren't created with the Yeoman generator, use one of the following options. - - [Sideload with the Office-Addin-Debugging tool](../develop/convert-xml-to-json-manifest.md#sideload-with-the-office-addin-debugging-tool) - - [Sideload with the Teams Toolkit CLI (command-line interface)](../develop/convert-xml-to-json-manifest.md#sideload-with-the-teams-toolkit-cli-command-line-interface) +The process to sideload an add-in that uses the unified app manifest for Microsoft 365 varies depending on the tool you used to create your add-in project. For more information, see [Sideload Office Add-ins that use the unified manifest for Microsoft 365](../testing/sideload-add-in-with-unified-manifest.md). ## Sideload an add-in that uses an XML manifest diff --git a/docs/testing/sideload-add-in-with-unified-manifest.md b/docs/testing/sideload-add-in-with-unified-manifest.md new file mode 100644 index 0000000000..f6e0365730 --- /dev/null +++ b/docs/testing/sideload-add-in-with-unified-manifest.md @@ -0,0 +1,81 @@ +--- +title: Sideload Office Add-ins that use the unified manifest for Microsoft 365 +description: Test your Office Add-in on Windows by sideloading. +ms.date: 09/19/2024 +ms.localizationpriority: medium +--- + +# Sideload Office Add-ins that use the unified manifest for Microsoft 365 + +The process of sideloading an add-in that uses the [Unified manifest for Microsoft 365](../develop/json-manifest-overview.md) varies depending on the tool you want to use and on how the add-in project was created. + +> [!NOTE] +> An add-in that uses the unified manifest can be sideloaded on Office on Windows, Version 2304 (Build 16320.20000) or later. Currently, it can't be sideloaded on the web, Mac, or iPad. + +## Sideload add-ins created with the Yeoman generator for Office Add-ins (Yo Office) + +Use the process described in [Sideload with a system prompt, bash shell, or terminal](#sideload-with-a-system-prompt-bash-shell-or-terminal). + +## Sideload with the Teams Toolkit + +1. First, *make sure Office desktop application that you want to sideload into is closed.* +1. In Visual Studio Code, open Teams Toolkit. +1. Required for Outlook only: in the **ACCOUNTS** section, verify that you're signed into Microsoft 365. +1. Select **View** | **Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select one of these options as appropriate for your add-in. + + - **Excel Desktop (Edge Chromium)** + - **Outlook Desktop (Edge Chromium)** + - **PowerPoint Desktop (Edge Chromium)** + - **Word Desktop (Edge Chromium)** + +1. Press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes and then the desktop version of the Office application that you selected opens. You can now work with your add-in. For an Outlook add-in, be sure you're working in the **Inbox** of *your Microsoft 365 account identity*. +1. To stop debugging and uninstall the add-in, select **Run** | **Stop Debugging** in Visual Studio Code. Closing the server window doesn't reliably stop the server and closing the Office application doesn't reliably cause Office to unacquire the add-in. + +## Sideload with a system prompt, bash shell, or terminal + +1. First, *make sure the Office desktop application that you want to sideload into is closed.* +1. Open a system prompt, bash shell, or the Visual Studio Code **TERMINAL**, and navigate to the root of the project. +1. Run the command `npm run start:desktop`. The project builds and a Node dev-server window opens. This process may take a couple of minutes then the Office host application (Excel, Outlook, PowerPoint, or Word) desktop opens. +1. You can now work with your add-in. +1. When you're done working with your add-in, make sure to run the command `npm run stop`. Closing the server window doesn't reliably stop the server and closing the Office application doesn't reliably cause Office to unacquire the add-in. + +## Sideload other NodeJS and npm projects + +There are two tools you can use to sideload. + +### Sideload with the Office-Addin-Debugging tool + +1. To sideload the add-in, run the following command. This command puts the unified manifest and the two icon image files that are referenced in the manifest's "icons" property into a zip file and sideloads it to the Office application. It also starts a server in a separate NodeJS window to host the add-in files on localhost. For more details about this command, see [Office-Addin-Debugging](https://www.npmjs.com/package/office-addin-debugging). + + ```command line + npx office-addin-debugging start desktop + ``` + +1. When you use office-addin-debugging to start an add-in, *always stop the session with the following command*. Closing the server window doesn't reliably stop the server and closing the Office application doesn't reliably cause Office to unacquire the add-in. + + ```command line + npx office-addin-debugging stop + ``` + +### Sideload with the Teams Toolkit CLI (command-line interface) + +1. Manually create a zip package using the following steps. + + 1. Open the unified manifest and scroll to the "icons" property. Note the relative path of the two image files. + 1. Use any zip utility to create a zip file that contains the unified manifest and the two image files. *The image files must have the same relative path in the zip file as they do in the project.* For example, if the relative path is "assets/icon-64.png" and "assets/icon-128.png", then you must include the "assets" folder with the two files in the zip package. + 1. If the folder contains other files, such as image files used in the Office ribbon, remove these from the zip package. It should have only the two image files specified in the "icons" property (in addition to the manifest in the root of the zip package). + +1. In the root of the project, open a command prompt or bash shell and run the following commands. + + ```command line + npm install -g @microsoft/teamsfx-cli + ``` + ```command line + teamsfx m365 sideloading --file-path + ``` + +1. When you finish a session working with the add-in, *always stop the session with the following command*, where `` is replaced with the value of the "id" property of the manifest. Closing the server window doesn't reliably stop the server and closing the Office application doesn't reliably cause Office to unacquire the add-in. + + ```command line + teamsfx m365 unacquire --manifest-id + ``` diff --git a/docs/testing/sideload-an-office-add-in-on-ipad.md b/docs/testing/sideload-an-office-add-in-on-ipad.md index 12a8dd33b4..6fac0ddf5c 100644 --- a/docs/testing/sideload-an-office-add-in-on-ipad.md +++ b/docs/testing/sideload-an-office-add-in-on-ipad.md @@ -9,6 +9,8 @@ ms.localizationpriority: medium To see how your add-in will run in Office on iOS, you can sideload your add-in's manifest onto an iPad using iTunes. This action won't enable you to set breakpoints and debug your add-in's code while it's running, but you can see how it behaves and verify that the UI is usable and rendering appropriately. +[!INCLUDE [Unified manifest note about platform sideloading restrictions](../includes/unified-manifest-sideload-restrictions-note.md)] + > [!NOTE] > To sideload an Outlook add-in, see [Sideload Outlook add-ins for testing](../outlook/sideload-outlook-add-ins-for-testing.md). diff --git a/docs/testing/sideload-an-office-add-in-on-mac.md b/docs/testing/sideload-an-office-add-in-on-mac.md index a15d928468..b0f14c8b17 100644 --- a/docs/testing/sideload-an-office-add-in-on-mac.md +++ b/docs/testing/sideload-an-office-add-in-on-mac.md @@ -9,6 +9,8 @@ ms.localizationpriority: medium To see how your add-in will run on Office on Mac, you can sideload your add-in's manifest. This action won't enable you to set breakpoints and debug your add-in's code while it's running, but you can see how it behaves and verify that the UI is usable and rendering appropriately. +[!INCLUDE [Unified manifest note about platform sideloading restrictions](../includes/unified-manifest-sideload-restrictions-note.md)] + > [!NOTE] > To sideload an Outlook add-in, see [Sideload Outlook add-ins for testing](../outlook/sideload-outlook-add-ins-for-testing.md). diff --git a/docs/testing/sideload-office-add-ins-for-testing.md b/docs/testing/sideload-office-add-ins-for-testing.md index 34f568528e..9b6b43f7e2 100644 --- a/docs/testing/sideload-office-add-ins-for-testing.md +++ b/docs/testing/sideload-office-add-ins-for-testing.md @@ -1,7 +1,7 @@ --- title: Sideload Office Add-ins to Office on the web description: Test your Office Add-in in Office on the web by sideloading. -ms.date: 08/17/2023 +ms.date: 09/19/2024 ms.localizationpriority: medium --- @@ -9,6 +9,8 @@ ms.localizationpriority: medium When you sideload an add-in, you're able to install the add-in without first putting it in an add-in catalog. This is useful when testing and developing your add-in because you can see how your add-in will appear and function. +[!INCLUDE [Unified manifest note about platform sideloading restrictions](../includes/unified-manifest-sideload-restrictions-note.md)] + When you sideload an add-in on the web, the add-in's manifest is stored in the browser's local storage, so if you clear the browser's cache, or switch to a different browser, you have to sideload the add-in again. The steps to sideload an add-in on the web vary based on the following factors.