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

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

@@ -2,19 +2,26 @@
 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
 ---
 
 # Convert an add-in to use the unified manifest for Microsoft 365
 
 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 [Office Yeoman Generator](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 below) 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,13 @@ 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
 
-When you've added the files to the project, add **\<IconUrl\>** and **\<HighResolutionIconUrl\>** (in that order) to the add-in only manifest just below the **\<Description\>** element. The following is an example.
+If your add-in only manifest doesn't already have both **\<IconUrl\>** and **\<HighResolutionIconUrl\>** (in that order) elements, then add them just below the **\<Description\>** element. The values of the **DefaultValue** attribute should be, respectively, the full URLs of a 64x64 pixel image file and a 128x128 pixel image file. The following is an example.
 
 ```xml
 <OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="MailApp">
@@ -46,22 +57,34 @@ When you've added the files to the project, add **\<IconUrl\>** and **\<HighReso
   <!-- Other markup omitted -->
 ```
 
-### Ensure that your function command names are short enough
+### Update the add-in ID, version, domain, and function names in the manifest
 
-If your manifest has any **\<FunctionName\>** 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. Change the the value of the `<ID>` element to a new random GUID.
 
-### Ensure that your SSO add-in requests permissions 
+1. Update the value of the `<Version>` 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.
 
-If your add-in uses Microsoft single sign-on with the on-behalf-of (OBO) flow, your add-in has a **\<Scopes\>** 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. 
+1. Be sure that the domain segment of the add-in's URLs in the manifest are pointing to `https://localhost:3000`.
 
+1. If your manifest has any **\<FunctionName\>** elements, make sure their values have fewer than 65 characters. 
+
+   > [!IMPORTANT]
+   > The value of this element must exactly match the name of an action that is 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.
+
+### 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 Office Yeoman Generator (aka "Yo Office")](#convert-projects-created-with-the-office-yeoman-generator-aka-yo-office)
+- [Convert NodeJS and npm projects that aren't created with Yeoman Generator](#convert-nodejs-and-npm-projects-that-arent-created-with-yeoman-generator)
 
 ### Convert the project with Teams Toolkit
 
@@ -78,14 +101,14 @@ 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** drop down, 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 drop down. 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** drop down, 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 drop down. 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**.
@@ -94,25 +117,15 @@ The easiest way to convert is to use Teams Toolkit.
 
 #### 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
-
-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*.
+You can sideload the add-in using the Teams Toolkit or in a command prompt, bash shell, or terminal. For more information, see:
 
-##### Sideload with a system prompt, bash shell, or terminal
+- [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)
 
-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`.
+> [!NOTE] 
+> Add-ins that use the unified manifest can be sideloaded only on Office Version 2304 (Build 16320.20000) or later.
 
-### Projects created with the Office Yeoman Generator (aka "Yo Office")
+### Convert 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.
 
@@ -123,11 +136,9 @@ 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.
+1. To sideload the add-in, see [Sideload add-ins created with the Office Yeoman Generator](../testing/sideload-add-in-with-unified-manifest.md#sideload-add-ins-created-with-the-office-yeoman-generator-yo-office).
 
-When you're ready to stop the dev server and uninstall the add-in, run the command `npm run stop`.
-
-### NodeJS and npm projects that aren't created with Yeoman Generator
+### Convert NodeJS and npm projects that aren't created with Yeoman Generator
 
 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.
 
@@ -137,36 +148,9 @@ In the root of the project, open a command prompt or bash shell and run the foll
 npx office-addin-manifest-converter convert <relative-path-to-XML-manifest>
 ```
 
-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&nbsp;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 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&nbsp;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 <relative-path-to-zip-file>
-    ``` 
+## 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).