将外接程序项目导入到 Microsoft 365 代理工具包

2025-05-19

适用于 Visual Studio Code 的 Agents Toolkit 扩展是一种功能丰富的工具，用于在 Microsoft 365 开发人员平台上使用扩展，包括 Teams 应用、Office 加载项和 Copilot 扩展等。它还可以轻松地使用超越 Teams 应用、加载项和 Copilot 扩展之间的边界的扩展。例如，它使旁加载此类跨界扩展更容易。

不能有用于将加载项导入工具包的算法过程，因为算法必须对项目的以下方面做出假设。

现有加载项的文件夹和文件结构。但这些结构因用于创建项目的工具以及该工具的版本而异。在创建项目后，加载项的开发人员可能还更改了结构。
各种配置文件中的设置。但这些设置也因项目的创建方式和自创建以来对配置所做的更改而异。
Web 应用程序的客户端源代码使用了哪种语言 TypeScript 或 JavaScript。

但是，我们可以提出一些一般性建议。

注意

本文不适用于使用 Visual Studio 创建的外接程序项目。此类项目基于 ASP.NET Web 应用程序框架，设计为在 Internet 信息服务器 (IIS) 上运行。将此类项目转换为在 Agents Toolkit 中工作将明显更加困难，并且本文的作用域外。
代理工具包中的外接程序项目必须使用 Microsoft 365 的统一清单。如果外接程序项目使用统一清单尚不支持的功能，则无法将其导入代理工具包，除非你首先对其进行重新设计，使其不使用不受支持的功能。
目前，使用统一清单的加载项无法在 Mac 上旁加载。如果开发计算机是 Mac，则在支持在 Mac 上旁加载之前，不要将项目导入代理工具包。

有两种基本策略可用。

使用工具包的导入功能
从新的工具包项目开始

无论选择哪种，首先请确保已安装 Visual Studio Code 和 Agents Toolkit 扩展。

使用工具包的导入功能

使用导入功能有四个任务。

准备现有清单
导入项目
验证加载项是否可以旁加载
导入后：根据需要调整项目结构

准备现有清单

重要

如果现有项目使用仅外接程序清单，则导入功能会自动将其转换为统一清单。因此，在导入项目之前，必须执行确保清单已准备好进行转换中的步骤。

导入项目

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

验证加载项是否可以旁加载

注意

使用统一清单的加载项只能在 Office 版本 2304 (内部版本 16320.20000) 或更高版本上旁加载。

使用 Microsoft 365 代理工具包旁加载中的说明旁加载加载项。

如果遇到问题，作为故障排除步骤，请尝试使用系统提示、bash shell 或终端进行旁加载。如果可以，则问题与工具包隔离。

旁加载问题可能是文件和文件夹结构或配置设置的结果，这些设置与代理工具包通常的预期不同。请参阅导入后：根据需要调整项目结构和设置部分。

导入后：根据需要调整项目结构和设置

导入过程会创建Visual Studio Code或代理工具包所需的一些文件夹和文件，但不会重新组织源文件;例如 HTML、JavaScript 和 CSS 文件。它也不会更改项目中任何文件（包括工具配置文件）的内容。建议更改项目以匹配在代理工具包中创建的项目模式。工作时，请记住以下几点。

工具包项目中的 HTML 文件没有内联 <script> 元素。它们仅使用 <script> 具有 src 加载外部文件的属性的元素。
新工具包项目中的源文件位于名为 \src 的文件夹中。在此文件夹中，源文件根据通常运行的运行时进一步划分为子文件夹。下面是一个典型的结构。
```
\src
    \commands
       commands.html
       commands.js
    \taskpane
       taskpane.css
       taskpane.html
       taskpane.js
```
代理工具包项目具有名为 \appPackage 的文件夹。应位于应用包 zip 文件中的清单和任何其他文件都位于此文件夹中。

重要

清单中的 URL 将反映项目的原始结构。如果对文件和文件夹结构进行更改，请根据需要更改这些 URL。
工具配置文件（如 webpack.config.js）可能具有 URL。根据需要更改这些内容。

从新的工具包项目开始

作为使用工具包的导入功能的替代方法，你可以在工具包中创建一个全新的外接程序项目，并将文件从现有项目移到其中，并更改其他文件。以下是需要执行的任务。

如果现有项目使用仅外接程序清单，请将其转换。请参阅转换加载项以使用 Microsoft 365 的统一清单。
在 Agents Toolkit 中创建新的外接程序项目。对于工具包要求你做出的每个选择（例如在 JavaScript 和 TypeScript 之间进行选择），请做出与现有外接程序最匹配的选择。请参阅使用 Microsoft 365 代理工具包创建 Office 外接程序项目。
将新项目的 \appPackage 文件夹中的清单替换为已转换的清单。

注意

如果转换过程生成了任何语言字符串文件（如 fr-fr.json），请将这些文件添加到 \appPackage 文件夹中。
将新项目的 \src 文件夹中的文件替换为旧项目中的源文件。为了最大程度地提高与新项目中配置文件的兼容性，我们建议根据通常运行源文件的运行时将源文件划分为子文件夹。例如，为函数命令、任务窗格、自动运行事件和 Excel 自定义函数的源文件提供单独的文件夹。
编辑清单以确保其中的任何 URL 都与项目的新结构兼容。
检查新项目中的配置文件，确保它们与项目的组织兼容。

提示

如果旧项目和新项目具有相同名称的配置文件 (如 babel.config.json) ，请使用文件比较 (“diff”) 工具查找差异。对于每个差异，请确定哪个文件适用于新项目，并根据需要在新项目中更改该文件。
webpack.config.js 可能需要编辑。无法为该文件提供通用规则，但在大多数情况下，以下原则适用。
- 确保 URL 与项目结构匹配。
- 确保 \src 文件夹下的每个子文件夹都有一个entry子属性。
- 确保 plugins 数组还考虑 了 \src 文件夹下的每个子文件夹。
- 确保 extensions 和 rules 属性考虑项目中应由加载程序处理和捆绑的文件类型。
确保可以在新项目中旁加载加载项。请参阅验证加载项是否可以旁加载。

通过