In the post, How to Setup a Chatbot Development Environment for Microsoft Bot Framework Version 4, you generated a basic bot project. In this post, I am going to go over some of the key areas for that codebase. If you are already familiar with bot framework v4 then this post will be a refresher for you.
Note: Microsoft bot framework is always changing and the generated code in the future may not reflect the code in this post. For this reason, I have cloned the current basic bot project sample and will be referring to it throughout this post. The sample is available at https://github.com/st2092/BasicBot. For the latest version of the basic bot code sample, go to https://github.com/Microsoft/BotBuilder-Samples.
Key Areas of Interest
There is a lot going on in the basic bot code. It can be overwhelming if you are new to bot framework development. So, I am going to talk about key portions of the code where the main logic and flow happens.
Startup.cs
The Startup.cs file is available at https://github.com/st2092/BasicBot/blob/master/Startup.cs and I’ll be referring to this file throughout this post.
// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.
using System;
using System.IO;
using System.Linq;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Bot.Builder;
using Microsoft.Bot.Builder.Integration.AspNet.Core;
using Microsoft.Bot.Configuration;
using Microsoft.Bot.Connector.Authentication;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
namespace Microsoft.BotBuilderSamples
{
/// <summary>
/// The Startup class configures services and the app's request pipeline.
/// </summary>
public class Startup
{
private ILoggerFactory _loggerFactory;
private bool _isProduction = false;
/// <summary>
/// Initializes a new instance of the <see cref="Startup"/> class.
/// This method gets called by the runtime. Use this method to add services to the container.
/// For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?LinkID=398940.
/// </summary>
/// <param name="env">Provides information about the web hosting environment an application is running in.</param>
/// <seealso cref="https://docs.microsoft.com/en-us/aspnet/core/fundamentals/startup?view=aspnetcore-2.1"/>
public Startup(IHostingEnvironment env)
{
_isProduction = env.IsProduction();
var builder = new ConfigurationBuilder()
.SetBasePath(env.ContentRootPath)
.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
.AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true)
.AddEnvironmentVariables();
Configuration = builder.Build();
}
/// <summary>
/// Gets the configuration that represents a set of key/value application configuration properties.
/// </summary>
/// <value>
/// The <see cref="IConfiguration"/> that represents a set of key/value application configuration properties.
/// </value>
public IConfiguration Configuration { get; }
/// <summary>
/// This method gets called by the runtime. Use this method to add services to the container.
/// </summary>
/// <param name="services">Specifies the contract for a <see cref="IServiceCollection"/> of service descriptors.</param>
public void ConfigureServices(IServiceCollection services)
{
var secretKey = Configuration.GetSection("botFileSecret")?.Value;
var botFilePath = Configuration.GetSection("botFilePath")?.Value;
if (!File.Exists(botFilePath))
{
throw new FileNotFoundException($"The .bot configuration file was not found. botFilePath: {botFilePath}");
}
// Loads .bot configuration file and adds a singleton that your Bot can access through dependency injection.
BotConfiguration botConfig = null;
try
{
botConfig = BotConfiguration.Load(botFilePath, secretKey);
}
catch
{
var msg = @"Error reading bot file. Please ensure you have valid botFilePath and botFileSecret set for your environment.
- You can find the botFilePath and botFileSecret in the Azure App Service application settings.
- If you are running this bot locally, consider adding a appsettings.json file with botFilePath and botFileSecret.
- See https://aka.ms/about-bot-file to learn more about .bot file its use and bot configuration.
";
throw new InvalidOperationException(msg);
}
services.AddSingleton(sp => botConfig ?? throw new InvalidOperationException($"The .bot configuration file could not be loaded. botFilePath: {botFilePath}"));
// Add BotServices singleton.
// Create the connected services from .bot file.
services.AddSingleton(sp => new BotServices(botConfig));
// Retrieve current endpoint.
var environment = _isProduction ? "production" : "development";
var service = botConfig.Services.FirstOrDefault(s => s.Type == "endpoint" && s.Name == environment);
if (service == null && _isProduction)
{
// Attempt to load development environment
service = botConfig.Services.Where(s => s.Type == "endpoint" && s.Name == "development").FirstOrDefault();
}
if (!(service is EndpointService endpointService))
{
throw new InvalidOperationException($"The .bot file does not contain an endpoint with name '{environment}'.");
}
// Memory Storage is for local bot debugging only. When the bot
// is restarted, everything stored in memory will be gone.
IStorage dataStore = new MemoryStorage();
// For production bots use the Azure Blob or
// Azure CosmosDB storage providers. For the Azure
// based storage providers, add the Microsoft.Bot.Builder.Azure
// Nuget package to your solution. That package is found at:
// https://www.nuget.org/packages/Microsoft.Bot.Builder.Azure/
// Un-comment the following lines to use Azure Blob Storage
// // Storage configuration name or ID from the .bot file.
// const string StorageConfigurationId = "<STORAGE-NAME-OR-ID-FROM-BOT-FILE>";
// var blobConfig = botConfig.FindServiceByNameOrId(StorageConfigurationId);
// if (!(blobConfig is BlobStorageService blobStorageConfig))
// {
// throw new InvalidOperationException($"The .bot file does not contain an blob storage with name '{StorageConfigurationId}'.");
// }
// // Default container name.
// const string DefaultBotContainer = "<DEFAULT-CONTAINER>";
// var storageContainer = string.IsNullOrWhiteSpace(blobStorageConfig.Container) ? DefaultBotContainer : blobStorageConfig.Container;
// IStorage dataStore = new Microsoft.Bot.Builder.Azure.AzureBlobStorage(blobStorageConfig.ConnectionString, storageContainer);
// Create and add conversation state.
var conversationState = new ConversationState(dataStore);
services.AddSingleton(conversationState);
var userState = new UserState(dataStore);
services.AddSingleton(userState);
services.AddBot<BasicBot>(options =>
{
options.CredentialProvider = new SimpleCredentialProvider(endpointService.AppId, endpointService.AppPassword);
// Catches any errors that occur during a conversation turn and logs them to currently
// configured ILogger.
ILogger logger = _loggerFactory.CreateLogger<BasicBot>();
options.OnTurnError = async (context, exception) =>
{
logger.LogError($"Exception caught : {exception}");
await context.SendActivityAsync("Sorry, it looks like something went wrong.");
};
});
}
/// <summary>
/// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
/// </summary>
/// <param name="app">Application Builder.</param>
/// <param name="env">Hosting Environment.</param>
/// <param name="loggerFactory">The <see cref="ILoggerFactory"/> to create logger object for tracing.</param>
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
_loggerFactory = loggerFactory;
app.UseDefaultFiles()
.UseStaticFiles()
.UseBotFramework();
}
}
}
This file contains methods that are invoked at runtime and doesn’t require you to explicitly call them. This is where the .bot configuration file for your bot is loaded and any services listed in the configurations are set up. Additionally, at the end of the setup is where the bot is instantiated.
BotServices.cs
The BotServices.cs file is available at https://github.com/st2092/BasicBot/blob/master/BotServices.cs and I’ll be referring to this file throughout this post.
// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License
using System;
using System.Collections.Generic;
using Microsoft.Bot.Builder.AI.Luis;
using Microsoft.Bot.Configuration;
namespace Microsoft.BotBuilderSamples
{
/// <summary>
/// Represents references to external services.
///
/// For example, LUIS services are kept here as a singleton. This external service is configured
/// using the <see cref="BotConfiguration"/> class.
/// </summary>
/// <seealso cref="https://docs.microsoft.com/en-us/aspnet/core/fundamentals/dependency-injection?view=aspnetcore-2.1"/>
/// <seealso cref="https://www.luis.ai/home"/>
public class BotServices
{
/// <summary>
/// Initializes a new instance of the <see cref="BotServices"/> class.
/// </summary>
/// <param name="luisServices">A dictionary of named <see cref="LuisRecognizer"/> instances for usage within the bot.</param>
public BotServices(BotConfiguration botConfiguration)
{
foreach (var service in botConfiguration.Services)
{
switch (service.Type)
{
case ServiceTypes.Luis:
{
var luis = (LuisService)service;
if (luis == null)
{
throw new InvalidOperationException("The LUIS service is not configured correctly in your '.bot' file.");
}
var app = new LuisApplication(luis.AppId, luis.AuthoringKey, luis.GetEndpoint());
var recognizer = new LuisRecognizer(app);
this.LuisServices.Add(luis.Name, recognizer);
break;
}
}
}
}
/// <summary>
/// Gets the set of LUIS Services used.
/// Given there can be multiple <see cref="LuisRecognizer"/> services used in a single bot,
/// LuisServices is represented as a dictionary. This is also modeled in the
/// ".bot" file since the elements are named.
/// </summary>
/// <remarks>The LUIS services collection should not be modified while the bot is running.</remarks>
/// <value>
/// A <see cref="LuisRecognizer"/> client instance created based on configuration in the .bot file.
/// </value>
public Dictionary<string, LuisRecognizer> LuisServices { get; } = new Dictionary<string, LuisRecognizer>();
}
}
This class is where a singleton instance of each service in the .bot configuration is instantiated and initialized. The basic bot only has LUIS (Language Understanding) service, but if in the future you want to add QnA (Question and Answer) service and or a Dispatcher service this is where you’ll make the modifications.
It is important to note that you can have multiple services of the same type for your bot. For example, you can have two LUIS and two QnA services with each containing different content. This is the reason why the services are represented as a Dictionary.
BasicBot.cs
The BasicBot.cs file is available at https://github.com/st2092/BasicBot/blob/master/BasicBot.cs and I’ll be referring to this file throughout this post.
// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Bot.Builder;
using Microsoft.Bot.Builder.Dialogs;
using Microsoft.Bot.Schema;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;
namespace Microsoft.BotBuilderSamples
{
/// <summary>
/// Main entry point and orchestration for bot.
/// </summary>
public class BasicBot : IBot
{
// Supported LUIS Intents
public const string GreetingIntent = "Greeting";
public const string CancelIntent = "Cancel";
public const string HelpIntent = "Help";
public const string NoneIntent = "None";
/// <summary>
/// Key in the bot config (.bot file) for the LUIS instance.
/// In the .bot file, multiple instances of LUIS can be configured.
/// </summary>
public static readonly string LuisConfiguration = "YOUR_LUIS_SERVICE_NAME";
private readonly IStatePropertyAccessor<GreetingState> _greetingStateAccessor;
private readonly IStatePropertyAccessor<DialogState> _dialogStateAccessor;
private readonly UserState _userState;
private readonly ConversationState _conversationState;
private readonly BotServices _services;
/// <summary>
/// Initializes a new instance of the <see cref="BasicBot"/> class.
/// </summary>
/// <param name="botServices">Bot services.</param>
/// <param name="accessors">Bot State Accessors.</param>
public BasicBot(BotServices services, UserState userState, ConversationState conversationState, ILoggerFactory loggerFactory)
{
_services = services ?? throw new ArgumentNullException(nameof(services));
_userState = userState ?? throw new ArgumentNullException(nameof(userState));
_conversationState = conversationState ?? throw new ArgumentNullException(nameof(conversationState));
_greetingStateAccessor = _userState.CreateProperty<GreetingState>(nameof(GreetingState));
_dialogStateAccessor = _conversationState.CreateProperty<DialogState>(nameof(DialogState));
// Verify LUIS configuration.
if (!_services.LuisServices.ContainsKey(LuisConfiguration))
{
throw new InvalidOperationException($"The bot configuration does not contain a service type of `luis` with the id `{LuisConfiguration}`.");
}
Dialogs = new DialogSet(_dialogStateAccessor);
Dialogs.Add(new GreetingDialog(_greetingStateAccessor, loggerFactory));
}
private DialogSet Dialogs { get; set; }
/// <summary>
/// Run every turn of the conversation. Handles orchestration of messages.
/// </summary>
/// <param name="turnContext">Bot Turn Context.</param>
/// <param name="cancellationToken">Task CancellationToken.</param>
/// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
public async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken)
{
var activity = turnContext.Activity;
// Create a dialog context
var dc = await Dialogs.CreateContextAsync(turnContext);
if (activity.Type == ActivityTypes.Message)
{
// Perform a call to LUIS to retrieve results for the current activity message.
var luisResults = await _services.LuisServices[LuisConfiguration].RecognizeAsync(dc.Context, cancellationToken).ConfigureAwait(false);
// If any entities were updated, treat as interruption.
// For example, "no my name is tony" will manifest as an update of the name to be "tony".
var topScoringIntent = luisResults?.GetTopScoringIntent();
var topIntent = topScoringIntent.Value.intent;
// update greeting state with any entities captured
await UpdateGreetingState(luisResults, dc.Context);
// Handle conversation interrupts first.
var interrupted = await IsTurnInterruptedAsync(dc, topIntent);
if (interrupted)
{
// Bypass the dialog.
// Save state before the next turn.
await _conversationState.SaveChangesAsync(turnContext);
await _userState.SaveChangesAsync(turnContext);
return;
}
// Continue the current dialog
var dialogResult = await dc.ContinueDialogAsync();
// if no one has responded,
if (!dc.Context.Responded)
{
// examine results from active dialog
switch (dialogResult.Status)
{
case DialogTurnStatus.Empty:
switch (topIntent)
{
case GreetingIntent:
await dc.BeginDialogAsync(nameof(GreetingDialog));
break;
case NoneIntent:
default:
// Help or no intent identified, either way, let's provide some help.
// to the user
await dc.Context.SendActivityAsync("I didn't understand what you just said to me.");
break;
}
break;
case DialogTurnStatus.Waiting:
// The active dialog is waiting for a response from the user, so do nothing.
break;
case DialogTurnStatus.Complete:
await dc.EndDialogAsync();
break;
default:
await dc.CancelAllDialogsAsync();
break;
}
}
}
else if (activity.Type == ActivityTypes.ConversationUpdate)
{
if (activity.MembersAdded != null)
{
// Iterate over all new members added to the conversation.
foreach (var member in activity.MembersAdded)
{
// Greet anyone that was not the target (recipient) of this message.
// To learn more about Adaptive Cards, see https://aka.ms/msbot-adaptivecards for more details.
if (member.Id != activity.Recipient.Id)
{
var welcomeCard = CreateAdaptiveCardAttachment();
var response = CreateResponse(activity, welcomeCard);
await dc.Context.SendActivityAsync(response).ConfigureAwait(false);
}
}
}
}
await _conversationState.SaveChangesAsync(turnContext);
await _userState.SaveChangesAsync(turnContext);
}
// Determine if an interruption has occurred before we dispatch to any active dialog.
private async Task<bool> IsTurnInterruptedAsync(DialogContext dc, string topIntent)
{
// See if there are any conversation interrupts we need to handle.
if (topIntent.Equals(CancelIntent))
{
if (dc.ActiveDialog != null)
{
await dc.CancelAllDialogsAsync();
await dc.Context.SendActivityAsync("Ok. I've canceled our last activity.");
}
else
{
await dc.Context.SendActivityAsync("I don't have anything to cancel.");
}
return true; // Handled the interrupt.
}
if (topIntent.Equals(HelpIntent))
{
await dc.Context.SendActivityAsync("Let me try to provide some help.");
await dc.Context.SendActivityAsync("I understand greetings, being asked for help, or being asked to cancel what I am doing.");
if (dc.ActiveDialog != null)
{
await dc.RepromptDialogAsync();
}
return true; // Handled the interrupt.
}
return false; // Did not handle the interrupt.
}
// Create an attachment message response.
private Activity CreateResponse(Activity activity, Attachment attachment)
{
var response = activity.CreateReply();
response.Attachments = new List<Attachment>() { attachment };
return response;
}
// Load attachment from file.
private Attachment CreateAdaptiveCardAttachment()
{
var adaptiveCard = File.ReadAllText(@".\Dialogs\Welcome\Resources\welcomeCard.json");
return new Attachment()
{
ContentType = "application/vnd.microsoft.card.adaptive",
Content = JsonConvert.DeserializeObject(adaptiveCard),
};
}
/// <summary>
/// Helper function to update greeting state with entities returned by LUIS.
/// </summary>
/// <param name="luisResult">LUIS recognizer <see cref="RecognizerResult"/>.</param>
/// <param name="turnContext">A <see cref="ITurnContext"/> containing all the data needed
/// for processing this conversation turn.</param>
/// <returns>A task that represents the work queued to execute.</returns>
private async Task UpdateGreetingState(RecognizerResult luisResult, ITurnContext turnContext)
{
if (luisResult.Entities != null && luisResult.Entities.HasValues)
{
// Get latest GreetingState
var greetingState = await _greetingStateAccessor.GetAsync(turnContext, () => new GreetingState());
var entities = luisResult.Entities;
// Supported LUIS Entities
string[] userNameEntities = { "userName", "userName_patternAny" };
string[] userLocationEntities = { "userLocation", "userLocation_patternAny" };
// Update any entities
// Note: Consider a confirm dialog, instead of just updating.
foreach (var name in userNameEntities)
{
// Check if we found valid slot values in entities returned from LUIS.
if (entities[name] != null)
{
// Capitalize and set new user name.
var newName = (string)entities[name][0];
greetingState.Name = char.ToUpper(newName[0]) + newName.Substring(1);
break;
}
}
foreach (var city in userLocationEntities)
{
if (entities[city] != null)
{
// Capitalize and set new city.
var newCity = (string)entities[city][0];
greetingState.City = char.ToUpper(newCity[0]) + newCity.Substring(1);
break;
}
}
// Set the new values into state.
await _greetingStateAccessor.SetAsync(turnContext, greetingState);
}
}
}
}
This is the class representation of your bot. It is where the majority of the action takes place once your bot runs. It is in this class where you define the logic to create a conversation with the user and process all the responses from them.
How the Bot Gets Instantiated and Run
First, let’s get the constructor out of the way. If you were trying to follow the code, something that might have confused you is that the constructor was never directly called in the code. This is because the constructor gets invoke implicitly in the Startup.cs file. When the “AddBot” method was invoked, the constructor got implicitly called and the singleton objects added beforehand are passed in as parameters to the bot’s constructor.
The Main Component of Conversation
The main part of the bot that handles conversation is the method “OnTurnAsync”. This method is invoked every turn of the conversation and is where you would process the responses to create a conversation. The high-level idea of what this method does is to check if a message was received (case 1) or if a new user began a chat with the bot (case 2). If a message was received then analyze the response and creates a corresponding response. If a new user connects to the bot, then greet them — it’s important to greet a new user!
Case 1: Activity Is a Message
In this scenario, what the user said is sent to the LUIS (language understanding) app and then it gives back the result. From the result, you can extract the intent of what the user said.
// ...
if (activity.Type == ActivityTypes.Message)
{
// Perform a call to LUIS to retrieve results for the current activity message.
var luisResults = await _services.LuisServices[LuisConfiguration].RecognizeAsync(dc.Context, cancellationToken).ConfigureAwait(false);
// If any entities were updated, treat as interruption.
// For example, "no my name is tony" will manifest as an update of the name to be "tony".
var topScoringIntent = luisResults?.GetTopScoringIntent();
var topIntent = topScoringIntent.Value.intent;
// update greeting state with any entities captured
await UpdateGreetingState(luisResults, dc.Context);
// Handle conversation interrupts first.
var interrupted = await IsTurnInterruptedAsync(dc, topIntent);
if (interrupted)
{
// Bypass the dialog.
// Save state before the next turn.
await _conversationState.SaveChangesAsync(turnContext);
await _userState.SaveChangesAsync(turnContext);
return;
}
// Continue the current dialog
var dialogResult = await dc.ContinueDialogAsync();
// if no one has responded,
if (!dc.Context.Responded)
{
// examine results from active dialog
switch (dialogResult.Status)
{
case DialogTurnStatus.Empty:
switch (topIntent)
{
case GreetingIntent:
await dc.BeginDialogAsync(nameof(GreetingDialog));
break;
case NoneIntent:
default:
// Help or no intent identified, either way, let's provide some help.
// to the user
await dc.Context.SendActivityAsync("I didn't understand what you just said to me.");
break;
}
break;
case DialogTurnStatus.Waiting:
// The active dialog is waiting for a response from the user, so do nothing.
break;
case DialogTurnStatus.Complete:
await dc.EndDialogAsync();
break;
default:
await dc.CancelAllDialogsAsync();
break;
}
}
}
// ...
For this example the bot only handles greetings. When LUIS recognizes a greeting intent, the bot will start the dialog for greeting. The bot will ask for the user’s name and what city they are from. Once the user has answered both questions the bot will greet the user by their name and the city they are from.
Case 2: Someone New Chats with the Bot
In this scenario, the bot greets the user after they connect to the bot. Remember it is important to greet your user.
// ...
else if (activity.Type == ActivityTypes.ConversationUpdate)
{
if (activity.MembersAdded != null)
{
// Iterate over all new members added to the conversation.
foreach (var member in activity.MembersAdded)
{
// Greet anyone that was not the target (recipient) of this message.
// To learn more about Adaptive Cards, see https://aka.ms/msbot-adaptivecards for more details.
if (member.Id != activity.Recipient.Id)
{
var welcomeCard = CreateAdaptiveCardAttachment();
var response = CreateResponse(activity, welcomeCard);
await dc.Context.SendActivityAsync(response).ConfigureAwait(false);
}
}
}
}
// ...
In this example, an adaptive card is created to welcome the user and let them know what the bot can do. To learn more about adaptive cards visit the adaptive cards documentation.
I hope this post was helpful to you. If you found this post helpful, share it with others so they can benefit too.
What are your experiences working with the bot framework?
To get in touch, you can follow me on Twitter, leave a comment, or send me an email at steven@brightdevelopers.com.