构建基本选项卡应用

选项卡是嵌入在 Microsoft Teams 中的 Teams 感知网页,也是开始 Teams 开发的好方法。 可以将它们添加为团队、群组聊天或个人用户的个人应用内部频道的一部分。

屏幕截图显示了 Teams 客户端中的概念选项卡应用。

在本教程中,将学习:

本分步指南可帮助您使用 Agents Toolkit 构建选项卡。 完成本指南后,你将看到以下输出:

屏幕截图显示已完成的应用

先决条件

确保安装以下用于构建和部署应用的工具。

  安装 用于使用...
Required    
  Visual Studio Code JavaScript、TypeScript 或 SharePoint 框架 (SPFx) 生成环境。 使用最新版本。
  Microsoft 365 代理工具包 可为应用创建项目基架的 Microsoft Visual Studio Code 扩展。 使用最新版本。
  Node.js 后端 JavaScript 运行时环境。 有关详细信息 Node.js 请参阅项目类型的版本兼容性表。
  Microsoft Teams Microsoft Teams 通过聊天、会议和通话应用与与你协作的每个人。
  Microsoft Edge(推荐)或 Google Chrome 包含开发人员工具的浏览器。
可选    
  适用于 Visual Studio Code 和 Azure CLI的 Azure 工具 用于访问存储的数据或为 Azure 中的 Teams 应用部署基于云的后端的 Azure 工具。
  适用于 Chrome 的 React 开发人员工具或适用于 Microsoft Edge 的 React 开发人员工具 用于开源 React JavaScript 库的浏览器 DevTools 扩展。
  Microsoft Graph 浏览器 Microsoft Graph 资源管理器,一个基于浏览器的工具,可让你从 Microsoft Graph 数据运行查询。
  Teams 开发人员门户 基于 Web 的门户,用于配置、管理和发布 Teams 应用,包括到组织或 Microsoft Teams 应用商店。

提示

如果使用 Microsoft Graph 数据,则应了解 Microsoft Graph 资源管理器并为其添加书签。 使用此基于浏览器的工具,可以在应用外部查询 Microsoft Graph。

准备开发环境

安装所需工具后,设置开发环境。

安装 Microsoft 365 代理工具包

Microsoft 365 Agents Toolkit (以前称为 Teams Toolkit) 通过为应用预配和部署云资源并发布到 Teams 应用商店的工具来帮助简化开发过程。

可以将 Agents Toolkit 与 Visual Studio Code 或名为 Microsoft 365 Agents Toolkit CLI (以前称为 TeamsFx CLI) 的命令行界面一起使用。

  1. 打开 Visual Studio Code,然后选择“扩展” (Ctrl+Shift+X 或“查看>扩展) ”。

  2. 在搜索框中输入 Microsoft 365 代理工具包。

  3. 选择“安装”。

    显示 Agents Toolkit 扩展安装的屏幕截图。

    Microsoft 365 Agents Toolkit 图标显示在 Visual Studio Code 活动栏中。

还可以从 Visual Studio Code Marketplace 安装 Agents Toolkit。

设置 Teams 开发租户

租户是组织在 Teams 中的空间或容器,可在其中聊天、共享文件和举行会议。 此空间也是上传和测试应用的地方。 让我们验证一下你是否准备好与租户一起开发。

检查“上传应用”选项

创建自定义应用后,必须使用“ 上传自定义应用” 选项将应用上传到 Teams。 登录 Microsoft 365 帐户以检查此选项是否已启用。

以下步骤可帮助验证是否可以在 Teams 中上传应用:

  1. 在 Teams 客户端中,选择 “应用 ”图标。

  2. 选择“管理应用”。

  3. 选择 “上传应用”。

  4. 查找“ 上传自定义应用”选项。 如果该选项可见,则可以上传自定义应用。

    屏幕截图显示在 Teams 中上传自定义应用的选项。

    注意

    如果找不到上传自定义应用的选项,请联系 Teams 管理员。

创建免费的 Teams 开发人员租户 (可选)

如果没有 Teams 开发人员帐户,请加入 Microsoft 365 开发人员计划。

  1. 转到 Microsoft 365 开发人员计划。

  2. 选择 “立即加入” 并按照屏幕上的说明进行操作。

  3. 在欢迎屏幕中,选择“ 设置 E5 订阅”。

  4. 设置管理员帐户。 完成后,将显示以下屏幕:

    屏幕截图显示 Microsoft 365 开发人员计划。

  5. 使用刚刚设置的管理员帐户登录到 Teams。 验证你是否在 Teams 中具有 “上传自定义应用” 选项。

获取免费的 Azure 帐户

如果想要在 Azure 中托管应用或访问资源,则必须具有 Azure 订阅。 在开始之前创建一个免费帐户。

现在,你拥有了设置帐户的所有工具。 接下来,让我们设置开发环境并开始构建! 首先选择要创建的应用。

为选项卡应用创建项目工作区

通过创建第一个应用开始 Microsoft Teams 应用开发。 此应用使用选项卡功能。

图中显示此应用具有三个功能。选项卡突出显示。

创建标签页项目工作区

如果先决条件到位,让我们开始吧!

注意

显示的 Visual Studio Code UI 来自 Mac。 Agents Toolkit 版本和环境可能因操作系统而异。

  1. 打开 Visual Studio Code。

  2. 选择 Visual Studio Code 活动栏中的 Microsoft 365 Agents Toolkit 图标。

  3. 选择“新建代理/应用>”Teams 应用。

    屏幕截图显示了 Teams 工具包边栏中“创建新项目”链接的位置。

  4. 选择 其他 Teams 功能

    显示要选择的其他 Teams 功能的屏幕截图。

  5. 在此示例中,选择 Tab 作为应用功能。

    屏幕截图显示要选择的应用功能。

  6. 选择 “默认文件夹 ”以将项目根文件夹存储在默认位置。

    屏幕截图显示如何选择默认位置。

按照以下步骤更改默认位置:

  1. 选择“ 浏览”。

    屏幕截图显示选择“浏览以查找存储”。

  2. 选择项目工作区的位置。

  3. 选择 “选择”文件夹。

    显示如何选择文件夹的屏幕截图。

  4. 为应用输入合适的名称,然后选择 Enter。

    屏幕截图显示在何处输入应用名称。

Teams 选项卡应用将在几秒钟内创建。

屏幕截图显示创建的应用。

创建应用后,Agents Toolkit 将显示以下消息:

屏幕截图显示预览项目。

可以选择“ 本地调试” 来预览项目。

创建 Teams 应用的快速回顾。 观看此有关创建 Teams 应用的简短回顾。

创建 Teams 应用

了解选项卡应用源代码

Agents Toolkit 提供用于构建应用的所有组件。 创建项目后,您可以在 Visual Studio Code 的资源管理器中查看项目文件夹和文件。

屏幕截图显示了结构选项卡。

尽管可以自由选择任何 UI 框架 (或不使用任何) ,但此示例模板代码提供了一个包含React组件的基架。

除此目录结构中的其他项目外,该工具包还维护:

Folder 目录
.vscode 用于调试的 VSCode 文件
appPackage 应用程序清单的模板
env 环境文件
infra 用于预配 Azure 资源的模板
src 应用程序的源代码

可以自定义以下文件,并演示一个示例实现以帮助你入门。

文件 目录
index.html HTML 文件。
src/Tab/App.css 应用的 CSS 文件。
src/Tab/App.tsx 选项卡源文件。 它调用 teamsjs SDK 来获取应用正在哪个 Microsoft 365 应用程序运行的上下文。
src/index.ts 使用 Microsoft Teams SDK 启动应用。
vite.config.js Vite 生成工具的配置。
nodemon.json Nodemon 监视并重新启动服务器的配置。

以下是特定于 Microsoft 365 Agents Toolkit 的项目文件。 可以 访问 Github 上的完整指南 ,了解 Microsoft 365 Agents Toolkit 的工作原理。

文件 目录
m365agents.yml 这是主的 Microsoft 365 Agents Toolkit 项目文件。 项目文件定义两个主要内容:属性和配置阶段定义。
m365agents.local.yml 这将覆盖 m365agents.yml 启用本地执行和调试的操作。

构建并运行你的第一个标签页应用

使用 Agents Toolkit 设置项目工作区后,生成选项卡项目。 你需要登录到 Microsoft 365 帐户。

登录到你的 Microsoft 365 帐户

使用 Microsoft 365 帐户登录 Teams。 如果使用的是 Microsoft 365 开发人员计划租户,则注册时设置的管理员帐户是 Microsoft 365 帐户。

  1. 打开 Visual Studio Code。
  2. 选择边栏中的 Microsoft 365 Agents Toolkit 图标。
  3. 选择“使用凭据 登录到 M365 ”。 此时将打开默认 Web 浏览器,以登录该帐户。
  4. 出现提示时关闭浏览器并返回到 Visual Studio Code。
  5. 返回到 Visual Studio Code 中的代理工具包。

边栏的 “帐户 ”部分显示 Microsoft 365 帐户名称。 如果为 Microsoft 365 帐户启用了自定义应用上传,则 Agents Toolkit 将显示已 启用自定义应用上传。

显示从何处登录到 Microsoft 365 和 Azure 的屏幕截图。

现在,你已准备好生成应用并在本地环境中运行它!

在 Visual Studio Code 本地生成和运行应用

若要在本地构建和运行应用,请执行:

在 Visual Studio Code 中,选择 F5 以在调试模式下运行应用程序。

了解在调试器中本地运行应用时会发生什么。

如果你想知道,按 F5 键时,代理工具包会:

  1. 检查以下先决条件:
  • 你已使用 Microsoft 365 帐户登录。
  • 已为 Microsoft 365 帐户启用自定义应用上传。
  • 已安装受支持 Node.js 版本。
  • 已安装 localhost 的开发证书。
  • 端口可用于选项卡应用。

注意

如果 Agents Toolkit 无法检查特定的先决条件,它会提示您进行检查。

  1. 安装 NPM 包。
  2. 向 Microsoft Entra ID 注册应用并配置应用。
  3. 在 Teams 开发人员门户中注册应用并配置应用。
  4. 启动选项卡应用。
  5. 在 Web 浏览器中启动 Teams 并上传选项卡应用。

显示按下 F5 键时的屏幕截图。

注意

首次运行应用时,下载所有依赖项,并生成应用。 生成完成后,将打开浏览器窗口。 此过程可能需要 3-5 分钟才能完成。

如有必要,该工具包将提示您安装本地证书。 此证书允许 Teams 从 https://localhost。

如果出现以下对话框,请选择“是”:

屏幕截图显示了 Microsoft 警告。

或者选择 “继续”,具体取决于你的操作系统:

屏幕截图显示了安装 SSL 证书的提示,以使 Teams 能够从 Mac 上的 localhost 加载应用程序。

Teams Web 客户端将在浏览器窗口中打开。

注意

如果工具包未提示安装证书,则必须手动安装证书。 有关详细信息,请参阅 添加手动证书。

  1. 如果出现提示,请使用 Microsoft 365 帐户登录。
  2. 当系统提示将自定义应用上传到本地计算机上的 Teams 时,选择“ 添加 ”。

屏幕截图显示将应用添加到 Teams。

  1. 恭喜,你的第一个应用正在 Teams 上运行!

屏幕截图显示已完成的应用

注意

如果要将应用扩展到 Outlook 和 Microsoft 365,可以从 Visual Studio Code 中的“运行和调试”下拉列表中选择使用 Outlook 和 Microsoft 365 调试应用。

您可以添加 SSO 功能以检索用户详细信息。 您可以像执行任何其他 Web 应用程序一样执行正常的调试活动,例如设置断点。 该应用支持热重新加载。 如果更改项目中的任何文件,页面将重新加载。

了解如何在应用未在本地运行时进行故障排除。

若要在 Teams 中成功运行应用,请确保已在 Teams 帐户中启用自定义应用上传。 可以在先决条件部分了解有关自定义应用上传的详细信息。

部署你的第一个 Teams 应用

你已了解如何使用选项卡应用创建、生成和运行 Teams 应用。 最后一步是在 Azure 上部署应用。

让我们使用代理工具包在 Azure 上部署第一个具有选项卡功能的应用。

登录到 Azure 帐户

使用此帐户访问 Microsoft Azure 门户并预配新的云资源以支持你的应用。

  1. 打开 Visual Studio Code。
  2. 打开在其中创建选项卡应用的项目文件夹。
  3. 选择边栏中的 Microsoft 365 Agents Toolkit 图标。
  4. 选择“使用凭据登录到 Azure”。

提示

如果已安装 AZURE 帐户扩展并使用同一帐户,则可以跳过此步骤。 使用与其他扩展中使用的帐户。

此时将打开默认 Web 浏览器,以登录该帐户。

  1. 出现提示时关闭浏览器并返回到 Visual Studio Code。

边栏的 ACCOUNTS 部分分别显示两个帐户。 它还列出了可用的可用 Azure 订阅数量。 确保至少有一个可用的可用 Azure 订阅。 如果没有,请注销并使用其他帐户。

恭喜,你已创建 Teams 应用! 现在,让我们继续学习如何使用 Agents Toolkit 将其中一个应用部署到 Azure。

将应用部署到 Azure。

部署包括两个步骤。 首先,创建必要的云资源 (也称为预配) 。 然后,应用的代码被复制到创建的云资源中。 在本教程中,您将部署选项卡应用。

预配和部署之间有何区别?
“预配”步骤在 Azure 和 Microsoft 365 中为应用创建资源,但不会 (HTML、CSS、JavaScript 等代码复制到资源中 ) 。 部署步骤会将应用的代码复制到预配步骤中创建的资源。 多次部署而不预配新资源是很常见的。 由于预配步骤可能需要一些时间才能完成,因此它与部署步骤是分开的。

选择 Visual Studio Code 边栏中的 Microsoft 365 Agents Toolkit 图标。

  1. 选择 “预配”。

    显示预配命令的屏幕截图。

  2. 选择现有订阅中的任何一个。

    屏幕截图显示所选的现有订阅。

  3. 选择要用于 Azure 资源的资源组。

    屏幕截图显示用于预配的资源。

    注意

    • 你的应用使用 Azure 资源托管。
    • 有关详细信息,请参阅 创建资源组。

    对话框警告你在 Azure 中运行资源时可能会产生成本。

  4. 选择 “预配”。

    屏幕截图显示预配对话框。

    预配过程在 Azure 云中创建资源。 这可能需要一些时间。 可以通过观看右下角的对话框来监视进度。 几分钟后,你会看到以下通知:

    屏幕截图显示在云中成功预配的资源。

    如果需要,可以查看预配的资源。 对于本教程,无需查看资源。

    预配的资源将显示在 ENVIRONMENT 部分中。

    屏幕截图显示预配的资源。

  5. 预配完成后,从 LIFECYCLE 面板中选择“部署”。

    屏幕截图显示应用部署到云。

    与预配一样,部署需要一些时间。 您可以通过观看右下角的对话框来监视该过程。 几分钟后,你将看到完成通知。

现在,可以使用相同的过程将机器人和消息扩展应用部署到 Azure。

注意

你的应用使用 Azure 资源托管。

运行部署的应用

预配和部署步骤完成后:

  1. (Ctrl+Shift+D / ⌘⇧-D 打开调试面板,或>从 Visual Studio Code 查看运行) 。

  2. 从启动配置下拉列表中选择启动 远程 (Edge) 。

  3. 选择“开始调试 (F5”) 以从 Azure 启动应用。

    屏幕截图显示如何远程启动应用。

  4. 当系统提示将应用上传到 Teams 时,选择“ 添加 ”。

    屏幕截图显示正在安装的应用。

    恭喜,你的第一个选项卡应用正在 Azure 环境中运行!

    屏幕截图显示立即或稍后试用该应用的消息。

了解将应用部署到 Azure 时会发生什么

部署之前,应用程序已在本地运行:

  • 后端使用 Azure Functions Core Tools 运行。
  • 应用程序 HTTP 终结点 (Microsoft Teams 在此加载应用程序) 在本地运行。

部署过程分为两步。 在活动 Azure 订阅上预配资源,然后将应用程序的后端和前端代码部署或上传到 Azure。

  • 后端(如果配置)使用各种 Azure 服务,包括 Azure 应用服务和 Azure 存储。
  • 前端应用程序部署到为静态 Web 托管配置的 Azure 存储帐户。

恭喜

成功了!

你已创建了一个选项卡应用。

现在您已经学会了创建基本应用,您可以继续创建更复杂的应用。 按照步骤生成和部署应用,你的应用将具有多种功能。

你已完成使用 JavaScript 生成选项卡应用的教程。