旁加载使用 Microsoft 365 统一清单的 Office 加载项

旁加载使用 Microsoft 365 统一清单 的加载项的过程因要使用的工具以及加载项项目的创建方式而异。

使用 Yeoman 生成器为 Office 加载项 (Yo Office) 旁加载加载项

通过 系统提示、bash shell 或终端使用旁加载中所述的过程。

使用 Microsoft 365 代理工具包旁加载

1. 首先， 确保关闭要旁加载到的 Office 桌面应用程序。

2. 在 Visual Studio Code中，打开“代理工具包”。

3. 仅适用于 Outlook：在 “帐户 ”部分中，验证是否已登录到 Microsoft 365。

4. 选择“查看 | Visual Studio Code中的运行”。 在 “运行和调试 ”下拉菜单中，根据加载项选择其中一个选项。

   • Excel Desktop (Edge Chromium)
   • Outlook Desktop (Edge Chromium)
   • PowerPoint Desktop (Edge Chromium)
   • Word桌面 (Edge Chromium)

5. 按 F5。 项目生成并打开节点开发服务器窗口。 此过程可能需要几分钟时间，然后打开所选 Office 应用程序的桌面版本。 现在可以使用加载项。 对于 Outlook 加载项，请确保在 Microsoft 365 帐户标识的收件箱中工作。

6. 若要停止调试并卸载加载项，请选择“在Visual Studio Code中运行 | 停止调试”。 关闭服务器窗口不会可靠地停止服务器，关闭 Office 应用程序不会可靠地导致 Office 取消获取加载项。

   注意

   如果前面的步骤似乎不起作用，请在 Visual Studio Code 中打开终端来卸载加载项，然后使用系统提示、bash shell 或终端完成旁加载部分的卸载步骤（最后一个步骤）。

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

1. 首先， 确保要旁加载到的 Office 桌面应用程序已关闭。
2. 打开系统提示符、bash shell 或 Visual Studio Code 终端，并导航到项目的根目录。
3. 旁加载加载项的命令取决于项目的创建时间。 "scripts"如果项目的 package.json 文件的节具有“start：desktop”脚本，则运行 npm run start:desktop;否则运行 npm run start。 项目生成并打开节点开发服务器窗口。 此过程可能需要几分钟时间，然后 Office 主机应用程序 (Excel、Outlook、PowerPoint 或桌面Word) 打开。
4. 在某些版本的 Office 上，加载项可能无法完全激活。 例如，加载项的按钮可能不会显示在功能区上。 如果发生这种情况，请选择“主页”功能区上的“加载项”按钮。 在打开的浮出控件上，选择加载项。 这将完成安装。
5. 现在可以使用加载项。
6. 使用完加载项后，请确保运行 命令 npm run stop。 关闭服务器窗口不会可靠地停止服务器，关闭 Office 应用程序不会可靠地导致 Office 取消获取加载项。

旁加载其他 NodeJS 和 npm 项目

有两种工具可用于旁加载。

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

1. 若要旁加载加载项，请运行以下命令。 此命令将清单的 属性中引用的 "icons" 统一清单和两个图标图像文件放入 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>
   

使用 Microsoft 365 代理工具包 CLI (命令行接口) 旁加载

1. 创建 zip 包。 请参阅 手动创建外接程序包文件。

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

   npm install -g @microsoft/m365agentstoolkit-cli
   

3. 运行以下命令以旁加载加载项。

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

   重要

   此命令返回有关加载项的一些信息，包括自动生成的游戏 ID，如以下示例所示。

   

   你将需要此游戏 ID 来结束旁加载和调试会话。 它记录在 Windows 计算机上的以下注册表项中：

   HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Wef\Developer\OutlookSideloadManifestPath\TitleId

   由于历史原因，字符串“Outlook”位于密钥名称中，但它适用于随 Agents Toolkit CLI 一起安装的任何加载项。

   仅记录随 CLI 一起安装的最新加载项。 如果在卸载与 CLI 一起安装的早期加载项之前，使用 CLI 旁加载加载项，则注册表中不会记录早期加载项的游戏 ID。 因此，建议同时将其保存在项目根目录中的文本文件中，并在 Mac 和 Windows 计算机上 TitleID.txt 命名该文件。

4. 使用代理工具包 CLI 启动加载项时， 始终使用以下命令停止会话。 关闭服务器窗口不会可靠地停止服务器，关闭 Office 应用程序不会可靠地导致 Office 取消获取加载项。 将“{title ID}”替换为加载项的游戏 ID，包括“U_”前缀;例如 。 U_90d141c6-cf4f-40ee-b714-9df9ea593f39

   atk uninstall --mode title-id --title-id {title ID} --interactive false
   

   重要

   命令的文档uninstall介绍了使用加载项清单 ID 而不是标题 ID 的方法。 由于 CLI 调用的 API 中的 bug，此选项当前不起作用。 必须使用 uninstall 上面提供的 命令，并且必须包含 --interactive false 选项。

通过 Teams 应用商店旁加载

使用统一清单的加载项可以通过 Teams 应用商店手动旁加载，即使它们没有与 Teams 相关的功能。 步骤如下。

1. 如果尚未由工具创建应用包，请手动创建应用包。 请参阅 手动创建外接程序包文件。

2. 关闭所有 Office 应用程序，然后按照手动清除缓存中的说明 清除 Office 缓存。

3. 打开 Teams，从 应用 栏中选择“应用”，然后选择 “应用 ”窗格底部的“管理 应用 ”。

4. 在“应用”对话框中选择“上传应用”，然后在打开的对话框中，选择“上传自定义应用”。

5. 在“ 打开 ”对话框中，导航到应用包并选择应用包。

6. 在打开的对话框中选择“ 添加 ”。

7. 当系统提示你添加应用时， 请不要 在 Teams 中打开它。 相反，请关闭 Teams。

8. 下一个任务是启动托管项目的 HTML 和 JavaScript 文件的本地 Web 服务器。 如何执行此作取决于多个因素，包括项目的文件夹结构、使用的工具（如捆绑包、任务管理器、服务器应用程序）以及配置这些工具的方式。 以下说明仅适用于满足以下条件的项目。

   • 项目的根目录中有一个 webpack.config.js 文件，该文件类似于使用 Yeoman Generator for Office 外接程序 或 Microsoft 365 代理工具包创建的外接程序项目中的文件。

   • 项目的根目录中有一个 package.json 文件，与同一两个工具创建的类似，并且该文件包含一个“脚本”部分，其中包含以下脚本。

     "dev-server": "webpack serve --mode development"
     

9. 在命令提示符或项目根目录中Visual Studio Code终端中，运行 npm run dev-server 以在 localhost 上启动服务器。

10. 打开外接程序面向的 Office 应用程序。 等待加载项加载。 这可能需要多达两分钟的时间。 根据 Office 版本，功能区按钮和其他项目可能会自动显示。 在某些版本中，需要手动激活加载项：选择“主页”功能区上的“加载项”按钮，然后在打开的浮出控件中选择加载项。 它将具有清单的 属性中指定的 "name.short" 名称。

手动创建外接程序包文件

使用统一清单时，安装和旁加载单元是 zip 格式的包文件。 此文件通常由用于创建和测试加载项的工具创建，但在某些情况下，可以手动创建它。 为此，请使用任何 zip 实用工具创建包含以下文件的 zip 文件。

• 统一清单，位于 zip 文件的根目录中。
• 清单的 属性中 "icons" 引用的两个图像文件。
• 清单的 属性中 "localizationInfo" 引用的任何本地化文件。
• 属性中 "copilotAgents" 引用的任何声明性代理文件。
• 任何第二级补充文件。 例如，声明性代理配置文件有时引用第二级补充文件，例如插件配置文件。 还应包括这些内容。

为了最大程度地提高与 Microsoft 365 开发工具的兼容性，建议将包中包含的文件保存在项目根目录中名为 appPackage 的文件夹中，并将包文件放在 appPackage 文件夹中名为 build 的子文件夹中。

下面是建议结构的示例。 \build\appPackage.zip 文件中的结构必须镜像 appPackage 文件夹的结构，生成文件夹本身除外。

\appPackage
    \assets
        color.png
        outline.png
    \build
        appPackage.zip
    manifest.json

\appPackage
    \agents
        myAgent.json
        \plugins
            myPlugin.json
    \assets
        color.png
        outline.png
    \build
        appPackage.zip
    \languages
        fr-FR.json
        es-MX.json
    manifest.json