[All Hosts] (DevX) updating tool articles for WXP with unified manifest (#4792)

* [All Hosts] (DevX) updating tool articles for WXP with unified manifest

* clarifications

* add more articles

* fix link

* Apply suggestions from code review

Co-authored-by: Elizabeth Samuel <[email protected]>

* more review changes

* format fix

* typo

* Apply suggestions from code review

Co-authored-by: Elizabeth Samuel <[email protected]>

* fix bookmarks

* Update docs/toc.yml

* review changes

* more review changes

* updating screen shots

* working on merge conflicts

* metadata date

---------

Co-authored-by: Elizabeth Samuel <[email protected]>

Author: Rick-Kirkham

docs/develop/convert-xml-to-json-manifest.md

@@ -1,47 +1,96 @@
 ---
 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: 02/12/2025
 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
+> [!IMPORTANT]
+> You can create an Outlook add-in with the latest released version of Teams Toolkit. To create an add-in for Excel, PowerPoint, or Word, install the prerelease version as described in [Install a prerelease version](/microsoftteams/platform/toolkit/install-teams-toolkit?tabs=vscode#install-a-prerelease-version). The toolkit creates projects that use the [unified manifest for Microsoft 365](json-manifest-overview.md). Support for this manifest in Excel, PowerPoint, and Word is preview only. 
+
+## 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. The **New Project** dropdown menu opens. The options listed will vary depending on your version of Teams Toolkit. 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 options in New Project dropdown menu. The last option is called 'Office Add-in'.":::
 
-1. In the **App Features Using an Outlook Add-in** drop down, select **Taskpane**.
+1. The **App Features Using an Office Add-in** dropdown menu opens. The options listed will vary depending on your version of Teams Toolkit. Select **Task pane**.
 
-    :::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 options in the App Features Using an Office Add-in dropdown menu. The option 'Task pane' is selected.":::
 
-1. In the **Workspace folder** dialog that opens, select the folder where you want to create the project.
+1. If you're making an Outlook add-in, the toolkit shows a **Programming Language** dropdown menu. Select either **TypeScript** or **JavaScript**. (For Excel, PowerPoint, and Word add-ins, a TypeScript project is always created.)
+1. If you're making an Outlook add-in, the toolkit shows a **Framework** dropdown menu. Select **Default** or **React**. (For Excel, PowerPoint, and Word add-ins, a default project is always created.)
+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 <kbd>F5</kbd>. 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
+
+> [!NOTE]
+> This section only applies if you are developing the add-in on a *Windows* computer. If you work on a Mac, you can test the add-in by having your Microsoft 365 administrator deploy the add-in as an [integrated app](/microsoft-365/admin/manage/test-and-deploy-microsoft-365-apps) in the Microsoft 365 Admin Center.
+
+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.

docs/develop/teams-toolkit-overview.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).

docs/images/teams-toolkit-create-office-add-in.png

@@ -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: 02/12/2025
 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, if there's a "start:desktop" script, run `npm run start:desktop`; otherwise, run `npm run start`. 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 add-in only manifest
 

docs/images/teams-toolkit-create-office-task-pane-capability.png

@@ -0,0 +1,80 @@
+---
+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: 02/12/2025
+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. The command to sideload the add-in depends on when the project was created. If the "scripts" section of the project's package.json file has a "start:desktop" script, then run `npm run start:desktop`; otherwise, run `npm run start`. 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 <relative-path-to-unified-manifest> 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&nbsp;line
+    npx office-addin-debugging stop <relative-path-to-unified-manifest>
+    ``` 
+
+### 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&nbsp;line
+    npm install -g @microsoft/teamsapp-cli
+
+    teamsapp install --file-path <relative-path-to-zip-file>
+    ``` 
+
+1. When you use the Teams Toolkit CLI 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. Replace the "{GUID of the add-in}" with the GUID in the "id" property of the unified manifest.
+
+    ```command&nbsp;line
+    teamsapp uninstall -manifest-id {GUID of the add-in}
+    ```

docs/images/teams-toolkit-create-outlook-add-in.png

@@ -1,14 +1,16 @@
 ---
 title: Sideload Office Add-ins on iPad for testing
 description: Test your Office Add-in on iPad by sideloading.
-ms.date: 09/09/2024
+ms.date: 02/12/2025
 ms.localizationpriority: medium
 ---
 
 # Sideload Office Add-ins on iPad for testing
 
 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).