你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用 Bot Framework SDK 创建机器人

适用于：SDK v4

本文介绍如何使用 Bot Framework SDK for C#、Java、JavaScript 或 Python 生成第一个机器人，以及如何使用 Bot Framework Emulator 测试机器人。

创建第一个机器人不需要 Azure 订阅或 Azure AI 机器人服务资源。 本快速入门重点介绍如何在本地创建第一个机器人。 若要了解如何在 Azure 中创建机器人，请参阅创建 Azure 机器人资源。

注意

Bot Framework JavaScript、C# 和 Python SDK 将继续受支持，但 Java SDK 即将停用，长期支持最终将于 2023 年 11 月结束。 仅执行此存储库中的关键安全性和缺陷修复。

使用 Java SDK 构建的现有机器人将继续正常运行。

对于新的机器人生成，请考虑使用 Power Virtual Agents 并参阅选择合适的聊天机器人解决方案。

有关详细信息，请参阅机器人构建的未来。

先决条件

C#

• .NET 6.0 SDK
• Bot Framework Emulator
• 了解 ASP.NET Core 和 C# 中的异步编程

C# 模版

当前机器人示例使用 .NET Core 3.1 模板。

Visual Studio

• Visual Studio 2022 或更高版本
• 适用于 Visual Studio 的 Bot Framework v4 SDK 模板

若要将机器人模板添加到 Visual Studio，请下载并安装 Bot Framework v4 SDK Templates for Visual Studio VSIX 文件。

注意

可以在 Visual Studio 中安装模板。

1. 在菜单中，选择扩展，然后选择管理扩展。
2. 在管理扩展对话框中，搜索并安装 Bot Framework v4 SDK templates for Visual Studio。

有关将 .NET 机器人部署到 Azure 的信息，请参阅如何预配和发布机器人。

VS Code / CLI

.NET Core 模板将帮助你使用 Bot Framework v4 快速生成新的对话式 AI 机器人。 截至 2020 年 5 月，这些模板及其生成的代码需要 .NET Core 3.1 或更高版本。

要安装 Bot Framework 模板：

1. 打开控制台窗口。

2. 下载并安装 .NET Core SDK download 3.1 版或更高版本。

3. 可以使用此命令来确定安装了哪些版本的 .NET Core 命令行接口。

   dotnet --version
   

4. 安装三个 Bot Framework C# 模板：回显、核心和空机器人模板。

   dotnet new -i Microsoft.Bot.Framework.CSharp.EchoBot
   dotnet new -i Microsoft.Bot.Framework.CSharp.CoreBot
   dotnet new -i Microsoft.Bot.Framework.CSharp.EmptyBot
   

5. 验证模板是否已正确安装。

   dotnet new --list
   

注意

上述步骤安装所有三个 Bot Framework 模板。 无需安装所有模板，只需安装要使用的模板即可。 本文使用回显机器人模板。

Java

• Java 1.8 或更高版本
• Bot Framework Emulator
• Visual Studio Code 或你喜欢用的 IDE（如果要编辑机器人代码）。
• 安装 Maven
• 安装 node.js 12.10 或更高版本。
• 一个 Azure 帐户（如果要部署到 Azure）。

Java 模板

使用 Yeoman 生成器，利用 Bot Framework v4 中的核心 AI 功能快速创建会话式 AI 机器人。 有关详细信息，请参阅 yeoman.io。

生成器支持三种不同的模板选项，如下所示。

模板	说明
回显机器人	如果你只是想在“Hello World!”的基础上稍作改进，但不会做太多改动，那么这是个不错的模板。 此模板只能处理基本操作，比如向机器人发送消息，以及让机器人通过向用户重复消息来处理消息。 此模板生成一个机器人，该机器人仅向用户“回显”用户对机器人所说的任何内容。
空机器人	如果你熟悉 Bot Framework v4，并且只需要一个基本的主干项目，则这是一个很好的模板。 如果要从文档中取示例代码并将其粘贴到最小机器人中以供学习，这也是一个不错的选择。
核心机器人	如果要创建高级机器人，这是一个很好的模板，因为它使用多轮次对话以及 Azure AI LUIS 来实现语言理解。 此模板创建一个机器人，该机器人可以提取地点和日期来预订航班。

注意

语言理解（LUIS）将于 2025 年 10 月 1 日停用。 从 2023 年 4 月 1 日开始，将无法创建新的 LUIS 资源。 语言理解功能的较新版本现已作为 Azure AI 语言的一部分提供。

对话语言理解（CLU）是 Azure AI 语言的一项功能，是 LUIS 的更新版本。 有关 Bot Framework SDK 中的语言理解支持的详细信息，请参阅自然语言理解。

安装 Yeoman

1. 确保已安装 12.10 node.js 12.10 或更高版本。

2. 安装最新的 npm。

   npm install -g npm
   

3. 安装 Yeoman。 请确保全局安装。

   npm install -g yo
   

4. 安装 generator-botbuilder-java。 请确保全局安装。

   npm install -g generator-botbuilder-java
   

5. 验证 Yeoman 和 generator-botbuilder-java 是否正确安装。

   yo botbuilder-java --help
   

JavaScript

• Node.js
• Bot Framework Emulator
• 了解 restify 和 JavaScript 中的异步编程
• Visual Studio Code 或你喜欢用的 IDE（如果要编辑机器人代码）。

JavaScript 和 TypeScript 模板

要为 Bot Framework v4 安装 Yeoman 和 Yeoman 生成器，请执行以下操作：

1. 打开终端或权限提升的命令提示符。

2. 切换到 JavaScript 机器人的目录。 如果还没有目录，请先创建它。

   mkdir myJsBots
   cd myJsBots
   

3. 确保你拥有最新版本的 npm 和 Yeoman。

   npm install -g npm
   npm install -g yo
   

4. 安装 Yeoman 生成器。 Yeoman 是用于创建应用程序的工具。 有关详细信息，请参阅 yeoman.io。

   npm install -g generator-botbuilder
   

   注意

   仅当使用 Windows 作为开发操作系统时，才需要安装下面列出的 Windows 生成工具。 对某些安装，restify 安装步骤将显示与 node-gyp 相关的错误。 如果存在这种情况，可以尝试使用提升的权限运行此命令。 如果系统上已安装 Python，此调用也可能会挂起而不会退出：

   仅当你在 Windows 上时运行此命令。

   npm install -g windows-build-tools
   

Python

• Python 3.8.3
• Bot Framework Emulator
• 了解通过 Python 进行的异步编程

创建和启用虚拟环境

虚拟环境是特定 Python 解释器和区别于全局设置的库的组合。 虚拟环境特定于项目，但保留在项目文件夹中。 使用虚拟环境的一项优势是，随着项目的开发，虚拟环境始终反映出项目的确切依赖项。 若要了解有关虚拟环境的详细信息，请参阅创建虚拟环境。

导航到要在其中创建机器人的目录。 然后针对首选平台运行以下命令。 激活虚拟环境后，命令行/终端应以 (venv) 开头。 这让你了解虚拟环境处于活动状态。 可以通过键入 deactivate 随时停用虚拟环境。

macOS/Linux

python3 -m venv venv
source venv/bin/activate

Windows

python -m venv venv
venv\Scripts\activate.bat

Python 模板

运行以下 pip install 命令来安装需要的包：

pip install botbuilder-core
pip install asyncio
pip install aiohttp
pip install cookiecutter==1.7.0

重要

如果使用 32 位版本的 Python，请确保也运行 pip install cryptography==2.8。

创建机器人

C#

Visual Studio

在 Visual Studio 中，创建一个新的机器人项目并使用 Echo Bot (Bot Framework v4 - .NET Core 3.1) 模板。 要仅显示机器人模版，请选择“AI 机器人”项目类型。

VS Code

请确保已安装 .NET Core 3.1 或更高版本。

1. 在 Visual Studio Code 中打开一个新的终端窗口。

2. 转到要创建机器人项目的目录。

3. 使用以下命令创建新的回显机器人项目。 将 <your-bot-name> 替换为要用于机器人项目的名称。

   dotnet new echobot -n <your-bot-name>
   

CLI

1. 打开新的终端窗口。

2. 转到要创建机器人项目的目录。

3. 使用以下命令创建新的回显机器人项目。 将 <your-bot-name> 替换为要用于机器人项目的名称。

   dotnet new echobot -n <your-bot-name>
   

得益于该模板，项目包含在此快速入门中创建机器人所需的所有代码。 无需任何其他代码即可测试机器人。

我创建了一个回显机器人我遇到了问题

Java

运行以下命令以通过模板创建回显机器人。 该命令对其参数使用默认选项。

yo botbuilder-java -T "echo"

Yeoman 会提示你输入用来创建机器人的一些信息。 对于本教程，请使用默认值。

? What's the name of your bot? (echo)
? What's the fully qualified package name of your bot? (com.mycompany.echo)
? Which template would you like to start with? (Use arrow keys) Select "Echo Bot"
? Looking good.  Shall I go ahead and create your new bot? (Y/n) Enter "y"

生成器支持许多命令行选项，这些选项可用于更改生成器的默认值或预先设定提示。 选项区分大小写。

命令行选项	说明
--help, -h	列出所有受支持的命令行选项的帮助文本
--botName, -N	为机器人项目指定的名称
--packageName, -P	要用于机器人的 Java 包名称
--template, -T	用于生成项目的模板。 选项包括 echo、empty 和 core。 有关不同模板的详细信息，请参阅 C#、JavaScript、Python 或 Java 语言的 GitHub 存储库。
--noprompt	生成器在创建新机器人之前不会提示确认。 命令行上未传递的任何要求选项都将使用合理的默认值。 此选项旨在启用自动生成机器人以进行测试。

得益于该模板，项目包含在此快速入门中创建机器人所需的所有代码。 无需任何其他代码即可测试机器人。

我创建了一个回显机器人，我遇到了问题

JavaScript

1. 使用生成器创建回显机器人。

   yo botbuilder
   

   Yeoman 会提示你输入用来创建机器人的一些信息。 对于本教程，请使用默认值。

   ? What's the name of your bot? my-chat-bot
   ? What will your bot do? Demonstrate the core capabilities of the Microsoft Bot Framework
   ? What programming language do you want to use? JavaScript
   ? Which template would you like to start with? Echo Bot - https://aka.ms/bot-template-echo
   ? Looking good.  Shall I go ahead and create your new bot? Yes
   

得益于该模板，项目包含在此快速入门中创建机器人所需的所有代码。 无需任何其他代码即可测试机器人。

我创建了一个回显机器人我遇到了问题

Python

1. 从工作目录中，运行以下命令下载回显机器人模板及其依赖项：

   cookiecutter https://github.com/microsoft/BotBuilder-Samples/releases/download/Templates/echo.zip
   

2. 系统会提示你提供机器人的名称和描述。 输入以下值：

   • bot_name：echo_bot
   • bot_description：回显用户响应的机器人。

   

我创建了一个回显机器人我遇到了问题

启动机器人

C#

Visual Studio

在 Visual Studio 中：

1. 打开您的机器人项目。
2. 运行项目而不进行调试。
3. Visual Studio 将生成应用程序，将其部署到 localhost，然后启动 Web 浏览器以显示应用程序的 default.htm 页。

此时，机器人正在本地端口 3978 上运行。

VS Code

在 Visual Studio Code 中：

1. 打开机器人项目文件夹。

   如果系统提示你选择一个项目，请选择所创建的机器人。

2. 从菜单上，选择“运行”，然后选择“运行但不调试”。

   • 如果提示选择环境，请选择 .Net Core。
   • 如果此命令更新了启动设置，请保存更改并重新运行命令。

   run 命令将生成应用程序，将其部署到 localhost，然后启动 Web 浏览器以显示应用程序的 default.htm 页。

此时，机器人正在本地端口 3978 上运行。

CLI

从命令提示符或终端输入以下命令：

1. 将目录 () 更改为机器人的项目文件夹。

2. 使用 dotnet run 启动机器人。

   dotnet run
   

3. 此命令将生成应用程序并将其部署到 localhost。

应用程序的默认网页不会显示，但此时，机器人在本地端口 3978 上运行。

我启动了回显机器人我遇到了问题

Java

1. 从终端导航到保存机器人的目录，然后执行下面列出的命令。

2. 生成 Maven 项目并将其打包为 .jar 文件（存档）。

   mvn package
   

3. 在本地运行机器人。 将 archive-name 替换为上一命令中的实际名称。

   java -jar .\target\<archive-name>.jar
   

现在，你已准备好启动模拟器。

我启动了回显机器人我遇到了问题

JavaScript

在终端或命令提示符中，将目录切换到为机器人创建的目录，并使用 npm start 启动机器人。

cd my-chat-bot
npm start

此时，机器人正在本地端口 3978 上运行。

我启动了回显机器人我遇到了问题

Python

1. 从命令行/终端将目录切换到 echo_bot。

   cd echo_bot
   

2. 安装回显机器人模板的依赖项。

   pip install -r requirements.txt 
   

3. 安装依赖项后，运行以下命令以启动机器人：

   python app.py
   

   如果看到以下屏幕截图中显示的最后一行，则表示机器人已准备就绪，可以开始进行测试：

   

4. 复制最后一行中的 http 地址。 使用 Emulator 与机器人交互时，需要用到它。

我启动了回显机器人我遇到了问题

启动模拟器并连接机器人

1. 启动 Bot Framework Emulator。

2. 选择模拟器的“欢迎”选项卡中的“打开机器人”。

3. 输入机器人的 URL，即本地主机和端口，并将 /api/messages 添加到路径。 地址通常为：http://localhost:3978/api/messages。

   

4. 然后选择“连接” 。

   向机器人发送消息，机器人将会回复。

   

我启动了模拟器并连接到我的机器人我遇到了问题

后续步骤

• 有关如何使用 Visual Studio 或 Visual Studio Code 以及 Bot Framework Emulator 进行调试的信息，请参阅调试机器人。
• 有关 ngrok 的信息，请参阅 Tunneling （ngrok）。

将机器人部署到 Azure