将外接程序转换为使用 Microsoft 365 (预览版的统一清单)

  • 项目

若要将 Teams 功能添加到使用 XML 清单的外接程序，或者为了将来证明加载项，需要将其转换为使用 Microsoft 365 的统一清单。

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

  • 确保具有 64x64 像素和 128x128 像素图像文件作为加载项的图标。
  • 将 XML 清单本身转换为统一清单的 JSON 格式。
  • 将新的清单和main图标和高分辨率图标图像文件打包到 zip 文件中，以便旁加载或部署。

注意

  • 统一清单是 Office 外接程序的预览功能，目前仅 Windows 版 Outlook 受支持。
  • 使用统一清单的加载项只能在 Office 内部版本 16.0.16501.10000 或更高版本上旁加载。
  • 在 Visual Studio 中创建的项目与Visual Studio Code不同，目前无法转换。
  • 如果使用 Teams 工具包或 Office Yeoman 生成器中的“统一清单”选项创建了项目，则它已使用统一清单。

确保拥有两个图像文件

很可能加载项中已有两个图像文件。 它们在 XML 清单中的 IconUrl 和 HighResolutionIconUrl 元素中指定。 由于这两个元素都是可选元素，因此外接程序项目 mignt 没有一个或两个元素。 这些是使用统一清单的外接程序所必需的，因此，如果项目尚未创建它们，则需要创建它们。 有关指导，请参阅为加载项Create图标。

将文件添加到项目后，<将 IconUrl> 和 <HighResolutionIconUrl> () 添加到 DESCRIPTION> 元素下方<的 XML 清单。 示例如下。

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

转换工具和选项

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

使用 Teams 工具包转换项目

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

先决条件

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

  1. 打开Visual Studio Code并选择“活动栏”上的“Teams 工具包”图标。

    Teams 工具包图标。

  2. 选择“Create新应用”。

  3. 在 “新建项目 ”下拉列表中，选择“ Outlook 外接程序”。

    “新建项目”下拉列表中的四个选项。第四个选项称为“Outlook 外接程序”。

  4. 在“ 使用 Outlook 加载项的应用功能 ”下拉列表中，选择“ 导入现有 Outlook 外接程序”。

    “使用 Outlook 加载项的应用功能”下拉列表中的两个选项。第二个选项称为“导入现有 Outlook 加载项”。

  5. 在 “现有外接程序项目文件夹 ”下拉列表中，浏览到外接程序项目的根文件夹。

  6. 在 “选择导入项目清单文件” 下拉列表中，浏览到 XML 清单文件。

  7. 在 “工作区文件夹 ”对话框中，选择要放置已转换项目的文件夹。

  8. 在“ 应用程序名称 ”对话框中，为项目 (指定一个名称，) 没有空格。 Teams 工具包使用源文件和基架创建项目。 然后在第二个Visual Studio Code窗口中打开项目。 关闭原始Visual Studio Code窗口。

在 Visual Studio Code 中旁加载加载项

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

使用 Teams 工具包旁加载
  1. 首先， 请确保 Outlook 桌面已关闭。
  2. 在Visual Studio Code中，打开 Teams 工具包。
  3. 在 “帐户 ”部分中，验证是否已登录到 Microsoft 365。
  4. 选择“查看 | Visual Studio Code中的运行”。 在“运行和调试”下拉菜单中，选择“Outlook 桌面 (Edge Chromium) ”选项，然后按 F5。 项目生成并打开节点开发服务器窗口。 此过程可能需要几分钟时间，然后 Outlook 桌面打开。
  5. 现在可以使用加载项。 请确保你在 Microsoft 365 帐户标识的收件箱中工作。
使用系统提示、bash shell 或终端的旁加载
  1. 首先， 请确保 Outlook 桌面已关闭。
  2. 打开系统提示符、bash shell 或 Visual Studio Code 终端，并导航到项目的根目录。
  3. 运行命令 npm run start:desktop。 项目生成并打开节点开发服务器窗口。 此过程可能需要几分钟时间，然后 Outlook 桌面打开。
  4. 现在可以使用加载项。

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

如果项目是使用 Office Yeoman 生成器 (使用除) “统一清单”选项以外的任何选项创建的，并且你不想使用 Teams 工具包，请使用以下步骤进行转换。

  1. 在项目的根目录中，打开命令提示符或 bash shell 并运行以下命令。 这会转换清单并更新package.json以指定当前工具包。 新的统一清单位于项目的根目录中，而旧的 XML 清单位于 backup.zip 文件中。 有关此命令的详细信息，请参阅 Office-Addin-Project。

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

  2. 运行 npm install。

  3. 若要旁加载加载项，请运行 npm run start:desktop。 此命令将统一清单和两个映像文件放入 zip 文件，并将其旁加载到 Office 应用程序。 它还会在单独的 NodeJS 窗口中启动服务器，以在 localhost 上托管加载项文件。

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

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

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

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

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

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

  1. 若要旁加载加载项，请运行以下命令。 此命令将统一清单和两个默认图标图像文件放入 zip 文件，并将其旁加载到 Office 应用程序。 它还会在单独的 NodeJS 窗口中启动服务器，以在 localhost 上托管加载项文件。 请注意，将路径传递给在上一步中创建的 统一清单 。 有关此命令的更多详细信息，请参阅 Office-Addin-Debugging。

    npx office-addin-debugging start <relative-path-to-unified-manifest> desktop

  2. 使用 office-addin-debugging 启动外接程序时， 始终使用以下命令停止会话。 关闭服务器窗口不会可靠地停止服务器，关闭 Office 应用程序不会可靠地导致 Office 取消获取加载项。

    npx office-addin-debugging stop <relative-path-to-unified-manifest>

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

  1. 使用以下步骤手动创建 zip 包。

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

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

    npm install -g @microsoft/teamsfx-cli

teamsfx m365 sideloading --file-path <relative-path-to-zip-file>