Convert an add-in to use the unified manifest for Microsoft 365

To add Teams capabilities or a Copilot extension 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.

There are three basic tasks to converting an add-in project from the add-in only manifest to the unified manifest.

• Ensure that your manifest 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 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.

Ensure that your manifest is ready to convert

The following sections describe conditions that must be met before you convert the manifest.

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. If you experience any difficulties uninstalling the add-in, see Remove a ghost add-in.

Ensure that you have two special image files

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 the full URLs of image files. The images must be a specified size as shown in the following table.

The following markup is an example.

<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="MailApp">
  <Id>01234567-89ab-cdef-0123-4567-89abcdef0123</Id>
  <Version>1.0</Version>
  <ProviderName>Contoso</ProviderName>
  <DefaultLocale>en-us</DefaultLocale>
  <DisplayName DefaultValue="Great Add-in"/>
  <Description DefaultValue="A great add-in."/>
  <IconUrl DefaultValue="https://localhost:3000/assets/icon-64.png" />
  <HighResolutionIconUrl DefaultValue="https://localhost:300/assets/icon-128.png" />

  <!-- Other markup omitted -->

Reduce the number of add-in commands as needed

An add-in that uses the unified manifest may not have more than 20 add-in commands. If the total number of <Action> elements in the add-in only manifest is greater than 20, you must redesign the add-in to have no more than 20.

Update the add-in ID, version, ___domain, and function names in the manifest

1. Change the value of the <ID> element to a new random GUID.

2. Update the value of the <Version> element and ensure that it conforms to the semver standard (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.

3. Be sure that the ___domain segment of the add-in's URLs in the manifest are pointing to https://localhost:3000.

4. 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's mapped to a function in a JavaScript or TypeScript file with the Office.actions.associate function. If you change it in the manifest, be sure to change it in the actionId parameter passed to associate() too.

Shorten string values as needed

Review and change, as needed, manifest values in light of the following effects of the conversion.

• The first 30 characters of <DisplayName> becomes the value of "name.short" in the unified manifest.
• The first 100 characters of <DisplayName> becomes the value of "name.full" in the unified manifest.
• The first 250 characters of <Description> becomes the value of "description.short" in the unified manifest.
• The first 4000 characters of <Description> becomes the value of "description.full" in the unified manifest.
• The first 32 characters of the <ProviderName> becomes the value of "developer.name" in the unified manifest.

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.

2. Verify that the add-in can be sideloaded and run. See 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 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 projects created with the Yeoman generator for Office Add-ins (aka "Yo Office")

If the project was created with the Yeoman generator for Office Add-ins, 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.

   npx office-addin-project convert -m <relative-path-to-XML-manifest>
   

2. Run npm install.

3. To sideload the add-in, see Sideload add-ins created with the Yeoman generator for Office Add-ins (Yo Office).

Convert NodeJS and npm projects that weren't created with the Yeoman generator for Office Add-ins (Yo Office)

If 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.

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. For more information, see Sideload other NodeJS and npm projects.

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.