您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

使用模拟器进行调试Debug with the emulator

Bot Framework Emulator 是一个桌面应用程序,允许机器人开发人员在本地或远程测试和调试机器人。The Bot Framework Emulator is a desktop application that allows bot developers to test and debug their bots, either locally or remotely. 使用此模拟器,你可以和机器人聊天并检查机器人发送和接收的消息。Using the emulator, you can chat with your bot and inspect the messages that your bot sends and receives. 模拟器会显示消息,因为它们会出现在网上聊天 UI 中,并在与机器人交换消息时记录 JSON 请求和响应。The emulator displays messages as they would appear in a web chat UI and logs JSON requests and responses as you exchange messages with your bot. 在将机器人部署到云之前,请使用模拟器在本地运行和测试。Before you deploy your bot to the cloud, run it locally and test it using the emulator. 可以使用模拟器测试机器人,即使还没有使用 Azure 机器人服务创建它或将其配置为在任何通道上运行。You can test your bot using the emulator even if you have not yet created it with Azure Bot Service or configured it to run on any channels.

先决条件Prerequisites

在本地运行机器人Run a bot locally

在将机器人连接到 Bot Framework Emulator 之前,需在本地运行机器人。Before connecting your bot to the Bot Framework Emulator, you need to run your bot locally. 可以使用 Visual Studio 或 Visual Studio Code 来运行机器人,也可以使用命令行。You can use Visual Studio or Visual Studio Code to run your bot, or use command line. 若要使用命令行来运行机器人,请执行以下操作:To run a bot using command line, do the following:

  • 转到命令提示符,将目录切换为机器人项目目录。Go to the command prompt and change directory to your bot project directory.

  • 运行以下命令来启动机器人:Start the bot by running the following command:

    dotnet run
    
  • 复制“应用程序已启动。 按 CTRL+C 可将其关闭。”之前的行中的端口号Copy the port number in the line before Application started. Press CTRL+C to shut down.

    C# 端口号

此时,机器人应该正在本地运行。At this point, your bot should be running locally.

连接到在 localhost 上运行的机器人Connect to a bot running on localhost

配置模拟器以进行身份验证Configure the emulator for authentication

如果机器人要求身份验证,则会显示登录对话框,你必须按如下所示配置模拟器。If a bot requires authentication, displaying a login dialog, you must configure the emulator as shown below.

使用登录验证码Using sign-in verification code

  1. 启动模拟器。Start the emulator.
  2. 在模拟器中,单击左下角的齿轮图标,或右上角的“模拟器设置” 选项卡。In the emulator, click the gear icon in the bottom left, or the Emulator Settings tab in the upper right.
  3. 选中“使用 OAuthCards 的登录验证码” 框。Check the box by Use a sign-in verification code for OAuthCards.
  4. 选中“绕过本地地址的 ngrok” 框。Check the box by Bypass ngrok for local address
  5. 单击“保存” 按钮。Click the Save button.

单击机器人显示的“登录”按钮时,将生成一个验证码。When you click the login button displayed by the bot, a validation code will be generated. 在机器人输入聊天框中输入验证码,以便进行身份验证。You wil enter the code in the bot input chat box for the authentication to take place. 之后,你可以执行允许的操作。After that you can perform the allowed operations.

或者,你可以执行下述步骤。Alternatively, you can perform the steps described below.

使用身份验证令牌Using authentication tokens

  1. 启动模拟器。Start the emulator.
  2. 在模拟器中,单击左下角的齿轮图标,或右上角的“模拟器设置” 选项卡。In the emulator, click the gear icon in the bottom left, or the Emulator Settings tab in the upper right.
  3. 选中“使用版本 1.0 身份验证令牌” 框。Check the box by Use version1.0 authentication tokens.
  4. 输入“ngrok” 工具的本地路径。Enter the local path to the ngrok tool. 有关工具的详细信息,请参阅 ngrokFor more the tool information, see ngrok.
  5. 选中“在模拟器启动时运行 ngrok” 框。Check the box by Run ngrok when the Emulator starts up.
  6. 单击“保存” 按钮。Click the Save button.

单击机器人显示的“登录”按钮时,系统将要求你输入凭据。When you click the login button displayed by the bot, you will be asked to enter your credentials. 身份验证令牌已生成。An authentication token is generated. 之后,你可以执行允许的操作。After that you can perform the allowed operations.

模拟器 UI

若要连接到在本地运行的机器人,请单击“打开机器人”。 To connect to a bot running locally and click Open bot. 将此前复制的端口号添加到以下 URL 中,并将更新的 URL 粘贴到“机器人 URL”栏中:Add the port number your copied earlier into the following URL and paste the updated URL in the Bot URL bar:

http://localhost:端口号/api/messageshttp://localhost:port number/api/messages

模拟器 UI

如果机器人是使用 Microsoft 帐户 (MSA) 凭据运行的,也请输入这些凭据。If your bot is running with Microsoft Account (MSA) credentials, enter these credentials too.

使用机器人凭据Use bot credentials

打开机器人时,如果机器人使用凭据运行,请设置“Microsoft 应用 ID”和“Microsoft 应用密码” 。When you open the bot, set the Microsoft App ID and Microsoft App password if your bot is running with credentials. 如果使用 Azure 机器人服务创建了机器人,则可以在机器人的应用服务上的“设置”->“配置”部分下使用凭据 。If you created your bot with the Azure Bot Service, the credentials are available on the bot's App Service, under the Settings -> Configuration section. 如果不知道这些值,可以从本地运行机器人的配置文件中删除这些值,然后在模拟器中运行机器人。If you do not know the values, you can remove those from the locally running bot's configuration file, then run the bot in the Emulator. 如果机器人没有使用这些设置运行,则也不需要使用这些设置运行模拟器。If the bot isn't running with these settings, you don't need to run the emulator with the settings either.

创建 AD 标识提供者应用程序时,请记住以下事项:When creating an AD identity provider application, remember the following:

  • 当支持的帐户类型已设置为单租户时,如果使用个人订阅而不是 Microsoft 帐户,则模拟器会发出错误:机器人的 Microsoft 应用 ID 或 Microsoft 应用密码不正确。 When the supported account types is set to single tenant, if you use a personal subscription instead of a Microsoft account, the emulator would issue the error: The bot's Microsoft App ID or Microsoft App Password is incorrect..
  • 在这种情况下,受支持的帐户类型必须设置为“任何组织目录(任何 Azure AD 目录 - 多租户)中的帐户和个人 Microsoft 帐户(例如 Xbox)”。 In this case, the supported account types must be set to Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Xbox).

有关详细信息,请参阅创建 Azure AD 标识提供者应用程序For more information, see Create an Azure AD identity provider application.

使用检查器查看消息活动的详细信息View detailed Message Activity with the Inspector

向机器人发送消息,机器人应该回复。Send a message to your bot and the bot should respond back. 可以单击聊天窗口中的消息气泡,并使用窗口右侧的“检查器” 功能检查原始 JSON 活动。You can click on the message bubble within the conversation window and inspect the raw JSON activity using the INSPECTOR feature to the right side of the window. 选中时,消息气泡将变为黄色,并在聊天窗口左侧显示活动 JSON 对象。When selected, the message bubble will turn yellow and the activity JSON object will be displayed to the left of the chat window. 此 JSON 信息包含密钥元数据,例如通道 ID、活动类型、聊天 ID、文本消息、终结点 URL,等等。The JSON information includes key metadata, including the channel ID, activity type, conversation ID, the text message, endpoint URL, and so on. 可以检查用户发送的活动,以及机器人响应的活动。You can inspect activities sent from the user, as well as activities the bot responds with.

模拟器消息活动

提示

可以在连接到通道的机器人中调试状态变化,只需将检测中间件添加到机器人即可。You can debug state changes in a bot connected to a channel by adding Inspection Middleware to the bot.

检查服务Inspect services

使用新 v4 模拟器,还可以检查来自 LUIS 和 QnA 的 JSON 响应。With the new v4 emulator you can also inspect the JSON responses from LUIS and QnA. 将机器人与已连接的语言服务结合使用,可以选择右下角“LOG”窗口中的“跟踪” 。Using a bot with a connected language service, you can select trace in the LOG window to the bottom right. 此新工具还提供直接从模拟器更新语言服务的功能。This new tool also provides features to update your language services directly from the emulator.

LUIS 检查器

使用已连接的 LUIS 服务,你会注意到跟踪链接指定了 Luis 跟踪 。With a connected LUIS service, you'll notice that the trace link specifies Luis Trace. 选中时,将看到 LUIS 服务中的原始响应,其中包括意向、实体以及指定分数。When selected, you'll see the raw response from your LUIS service, which includes intents, entities along with their specified scores. 此外可以选择为用户表达重新分配意向。You also have the option to re-assign intents for your user utterances.

QnA 检查器

使用已连接的 QnA 服务,日志将显示“QnA 跟踪” ,选择后,可以预览与该活动相关联的问题和答案对,以及置信度分数。With a connected QnA service, the log will display QnA Trace, and when selected you can preview the question and answer pair associated with that activity, along with a confidence score. 可以在此处为答案添加备用问题表述。From here, you can add alternative question phrasing for an answer.

登录到 AzureLogin to Azure

可以使用 Emulator 登录到 Azure 帐户。You can use Emulator to login in to your Azure account. 若要添加和管理机器人所依赖的服务,则这特别有用。This is particularly helpful for you to add and manage services your bot depends on. 按以下步骤登录到 Azure:Log into Azure by following these steps:

  • 单击“文件”->“使用 Azure 登录”Azure 登录Click on File -> Sign in with Azure Azure login
  • 在欢迎屏幕上,单击“使用 Azure 帐户登录”。可以选择让 Emulator 保持你处于已登录状态,即使 Emulator 应用程序重启也是如此。On the welcome screen click on Sign in with your Azure account You can optionally have Emulator keep you signed in across Emulator application restarts. Azure 登录Azure login

禁用收集数据Disabling data collection

如果你决定不再允许 Emulator 收集使用情况数据,可以按照以下步骤轻松地禁用数据收集功能。If you decide that you no longer want to allow the Emulator to collect usage data, you can easily disable data collection by following these steps:

  1. 导航到 Emulator 的设置页,方法是单击左侧导航栏中的“设置”按钮(齿轮图标)。Navigate to the Emulator's settings page by clicking on the Settings button (gear icon) in the nav bar on the left side.

    禁用数据收集

  2. 取消选中“数据收集”部分下标记为“允许我们收集使用情况数据,帮助改进 Emulator”的复选框。 Uncheck the checkbox labeled Help improve the Emulator by allowing us to collect usage data under the Data Collection section.

    禁用数据收集

  3. 单击“保存”按钮。Click the "Save" button.

    禁用数据收集

如果改变想法,只需重新选中该复选框即可启用此功能。If you change your mind, you can always enable it by re-checking the checkbox.

其他资源Additional resources

Bot Framework Emulator 为开放源代码。The Bot Framework Emulator is open source. 可以参与开发并提交 Bug 和建议You can contribute to the development and submit bugs and suggestions.

有关疑难解答,请参阅排查常见问题和该部分中的其他疑难解答文章。For troubleshooting, see troubleshoot general problems and the other troubleshooting articles in that section.

后续步骤Next steps

使用检测中间件调试连接到通道的机器人。Use inspection middleware to debug a bot connected to a channel.