转换外接程序以使用 Microsoft 365 的统一清单

项目
01/01/2025

若要将 Teams 功能添加到使用仅外接程序清单的外接程序，或仅面向将来的外接程序，需要将其转换为使用 Microsoft 365 的统一清单。

将外接程序项目从仅外接程序清单转换为统一清单有三个基本任务。

确保加载项已准备好进行转换。
将仅 XML 格式的外接程序清单本身转换为统一清单的 JSON 格式。
将新清单和两个图标图像文件打包到 zip 文件中，以便旁加载或部署。

注意

在连接到 Microsoft 365 订阅版本 2304 (内部版本 16320.000000) 或更高版本的 Office web 版、新的 Outlook 和 Office on Windows 中，直接支持使用 Microsoft 365 统一清单的 Office 加载项。

当包含统一清单的应用包部署在 AppSource 或 Microsoft 365 管理中心时，将从统一清单生成并存储仅外接程序清单。此仅外接程序清单允许在不直接支持统一清单的平台上安装外接程序，包括 Mac 上的 Office、移动版 Office、Windows 上早于 2304 (内部版本 16320.00000) 的 Office 订阅版本，以及 Windows 上的 Office 永久版本。

注意

使用统一清单的加载项只能在 Office 版本 2304 (内部版本 16320.20000) 或更高版本上旁加载。
在 Visual Studio 中创建的项目与Visual Studio Code不同，目前无法转换。
如果使用 Teams 工具包或 Office Yeoman 生成器中的“统一清单”选项创建了项目，则它已使用统一清单。

确保加载项已准备好进行转换

以下部分介绍在转换清单之前必须满足的条件。

确保拥有两个图像文件

将文件添加到项目后，<将 IconUrl> 和 <HighResolutionIconUrl> () 添加到 Description> 元素下方<的仅外接程序清单。示例如下。

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

确保函数命令名称足够短

如果清单包含任何 <FunctionName> 元素，请确保其值少于 65 个字符。此元素的值必须与 JavaScript 或 TypeScript 文件中函数的名称完全匹配。如果在清单中对其进行更改，请务必在代码文件中也对其进行更改。

确保 SSO 加载项请求权限

如果外接程序使用Microsoft单一登录和代表 (OBO) 流，则外接程序具有一个 <Scopes> 元素，该元素指定外接程序所需的 Microsoft Graph 或其他 API 权限。使用统一清单时，必须在运行时在代码中请求权限。根据需要更新代码以请求这些权限。确切的代码取决于所使用的体系结构和授权代码库。通常，代码在请求访问令牌的函数中请求权限。

转换工具和选项

有多种方法可以执行剩余任务，具体取决于要用于项目的 IDE 和其他工具，以及用于创建项目的工具。

使用 Teams 工具包转换项目
使用 Office Yeoman 生成器创建的项目 (又名“Yo Office”)
未使用 Yeoman 生成器创建的 NodeJS 和 npm 项目

使用 Teams 工具包转换项目

最简单的转换方法是使用 Teams 工具包。

先决条件

安装Visual Studio Code
安装 Teams 工具包

将外接程序项目导入 Teams 工具包

打开Visual Studio Code并选择“活动栏”上的“Teams 工具包”图标。
选择“ 创建新应用”。
在 “新建项目 ”下拉列表中，选择“ Outlook 外接程序”。
在“ 使用 Outlook 加载项的应用功能 ”下拉列表中，选择“ 导入现有 Outlook 外接程序”。
在 “现有外接程序项目文件夹 ”下拉列表中，浏览到外接程序项目的根文件夹。
在 “选择导入项目清单文件” 下拉列表中，浏览到仅外接程序清单文件，通常名为 manifest.xml。
在 “工作区文件夹 ”对话框中，选择要放置已转换项目的文件夹。
在“ 应用程序名称 ”对话框中，为项目 (指定一个名称，) 没有空格。 Teams 工具包使用源文件和基架创建项目。然后在第二个Visual Studio Code窗口中打开项目。关闭原始Visual Studio Code窗口。

在 Visual Studio Code 中旁加载加载项

可以使用 Teams 工具包或在命令提示符、bash shell 或终端中旁加载加载项。

使用 Teams 工具包旁加载

首先， 请确保 Outlook 桌面已关闭。
在Visual Studio Code中，打开 Teams 工具包。
在 “帐户 ”部分中，验证是否已登录到 Microsoft 365。
选择“查看 | Visual Studio Code中的运行”。在“运行和调试”下拉菜单中，选择“Outlook 桌面 (Edge Chromium) ”选项，然后按 F5。项目生成并打开节点开发服务器窗口。此过程可能需要几分钟时间，然后 Outlook 桌面打开。
现在可以使用加载项。请确保在 Microsoft 365 帐户标识的收件箱中工作。

使用系统提示、bash shell 或终端的旁加载

首先， 请确保 Outlook 桌面已关闭。
打开系统提示符、bash shell 或 Visual Studio Code 终端，并导航到项目的根目录。
如果项目package.json文件的“scripts”部分具有“start：desktop”脚本，则运行 npm run start:desktop;否则运行 npm run start。项目生成并打开节点开发服务器窗口。此过程可能需要几分钟时间，然后 Outlook 桌面打开。
现在可以使用加载项。
使用完加载项后，请确保运行命令 npm run stop。

使用 Office Yeoman 生成器创建的项目 (又名“Yo Office”)

如果项目是使用 Office Yeoman 生成器创建的，并且你不想使用 Teams 工具包，请使用以下步骤进行转换。

在项目的根目录中，打开命令提示符或 bash shell 并运行以下命令。这会转换清单并更新package.json以指定当前工具包。新的统一清单位于项目的根目录中，旧的仅外接程序清单位于 backup.zip 文件中。有关此命令的详细信息，请参阅 Office-Addin-Project。
```
npx office-addin-project convert -m <relative-path-to-XML-manifest>
```
运行 npm install。
旁加载加载项的命令取决于项目的创建时间。如果项目package.json文件的“scripts”部分具有“start：desktop”脚本，则运行 npm run start:desktop;否则运行 npm run start。此命令将统一清单和两个映像文件放入 zip 文件，并将其旁加载到 Office 应用程序。它还会在单独的 NodeJS 窗口中启动服务器，以在 localhost 上托管加载项文件。

准备好停止开发服务器并卸载加载项时，请运行命令 npm run stop。

未使用 Yeoman 生成器创建的 NodeJS 和 npm 项目

如果你不想使用 Teams 工具包，并且你的项目不是使用 Office Yeoman 生成器创建的，请使用 office-addin-manifest-converter 工具。

在项目的根目录中，打开命令提示符或 bash shell 并运行以下命令。此命令将统一清单置于子文件夹中，其名称与原始仅外接程序清单的文件名词干相同。例如，如果清单名为 MyManifest.xml，则会在 .\MyManifest\MyManifest.json 创建统一清单。有关此命令的更多详细信息，请参阅 Office-Addin-Manifest-Converter。

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

创建统一清单后，可通过两种方法创建 zip 文件并旁加载它。接下来的两个小节将介绍它们。

使用 Office-Addin-Debugging 工具旁加载

若要旁加载加载项，请运行以下命令。此命令将统一清单和两个默认图标图像文件放入 zip 文件，并将其旁加载到 Office 应用程序。它还会在单独的 NodeJS 窗口中启动服务器，以在 localhost 上托管加载项文件。请注意，将路径传递给在上一步中创建的 统一清单 。有关此命令的更多详细信息，请参阅 Office-Addin-Debugging。
```
npx office-addin-debugging start <relative-path-to-unified-manifest> desktop
```
使用 office-addin-debugging 启动外接程序时， 始终使用以下命令停止会话。关闭服务器窗口不会可靠地停止服务器，关闭 Office 应用程序不会可靠地导致 Office 取消获取加载项。
```
npx office-addin-debugging stop <relative-path-to-unified-manifest>
```

使用 Teams 工具包 CLI (命令行界面) 旁加载

使用以下步骤手动创建 zip 包。
1. 打开统一清单并滚动到“icons”属性。请注意两个图像文件的相对路径。
2. 使用任何 zip 实用工具创建包含统一清单和两个映像文件的 zip 文件。 图像文件在 zip 文件中的相对路径必须与项目中的相对路径相同。 例如，如果相对路径为“assets/icon-64.png”和“assets/icon-128.png”，则必须在 zip 包中包含包含两个文件的“assets”文件夹。
3. 如果文件夹包含其他文件（例如 Office 功能区中使用的图像文件），请从 zip 包中删除这些文件。除了 zip 包) 根目录中的清单之外，它应仅具有“icons”属性中指定的两个图像文件 (。

在项目的根目录中，打开命令提示符或 bash shell 并运行以下命令。

npm install -g @microsoft/teamsapp-cli

teamsapp install --file-path <relative-path-to-zip-file>

使用 Teams 工具包 CLI 启动加载项时， 始终使用以下命令停止会话。关闭服务器窗口不会可靠地停止服务器，关闭 Office 应用程序不会可靠地导致 Office 取消获取加载项。将“{GUID of the add-in}”替换为统一清单的“id”属性中的 GUID。
```
teamsapp uninstall -manifest-id {GUID of the add-in}
```

通过