Build a Microsoft Bot Framework bot with the Bot Builder SDK v4

Posted on by The Bot Framework Team

The Microsoft Bot Framework provides just what you need to build and connect intelligent bots that interact naturally wherever your users are talking, from text/SMS to Skype, Slack, Office 365 mail and other popular services. The new version 4 SDK provides a new, rich, multi-language SDK for building bots using C#, JavaScript, Python, or Java.

Bot Builder v4 helps you with your digital transformation enabling Conversational AI. You can build bots that start simple yet grow in complexity. Bot Builder V4 provides a set of AI-services-aware tools that support a rich E2E developer workflow to help you create, build, test, deploy, and manage your bots.

In preview now, the Bot Builder v4 SDK is an open source project on GitHub that is an evolution of the V3  SDK. It simplifies your first bot experience and is modular to allow you to pick the components and services you need in your bots. The v4 SDK is extensible with a pluggable middleware model and offers a unified programming modal across all languages.

This walkthrough will show you how you can create, build, test, deploy, and manage a bot using C#, ASP.NET, and the preview version of the Bot Builder v4 SDK.

What you Need

  • Visual Studio 2017 15.6.7 (any edition) with the following workloads:
  • ASP.NET and web development
  • Azure development
  • .NET Core cross-platform development
  • Bot Framework Emulator
  • A Microsoft Azure Subscription
  • Access to the Internet (specifically NuGet.org and Azure)

Create Your Bot

You’ll create your bot using Visual Studio 2017. You’ll access the Bot Builder v4 SDK runtime bits via NuGet.org.

Create Your Bot in Visual Studio 2017

First, create the project.

  1. Start Visual Studio 2017.
  2. Choose File | New | Project.
  3.  In the New Project dialog, under Visual C#, choose Web, followed by ASP.NET Core Web Application in the center pane.
  4.  Provide a Name (such as MyBot) and Location and click OK.

5. In the New ASP.NET Core Web Application dialog, make sure you’ve selected the following options: NET Core 2.0, Empty, and No Authentication.

6. Click OK.

7. Select Build | Rebuild Solution.

8. In the Solution Explorer, right-click on the wwwroot node, and select Add | New Item.

9. In the Add New Item dialog, locate the HTML Page template, and name it default.html.

10. Click Add when ready.

11. Replace the existing HTML with the following, changing the value of the title element if you desire:

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8" />
        <title>Your Bot Name Here</title>
    </head>
    <body>
        <p>
        <p>Welcome to your Bot.</p>
        <p>You can access your bot locally via 
<pre><b>http://localhost:your port/api/messages</b></pre></p>
        </p>
    </body>
</html>

12. Open Startup.cs.

13. Delete lines 28 to 31 (listed below):

app.Run(async (context) =>
{
         await context.Response.WriteAsync("Hello World!");
});

14. Add the following two lines at line 28:

app.UseDefaultFiles();

app.UseStaticFiles();

15. Save your work via File | Save All.

16. Press F5 to compile and start a debug session, launching a browser, to make sure everything is working correctly and you see your html page.

17. When done, close your browser and stop debugging (Debug | Stop Debugging).

18. Select Windows | Close All Documents to tidy up Visual Studio.

Add NuGet Packages

You will now add references to the Bot Builder SDK v4 prerelease.

  1. In the Solution Explorer, right-click on the Solution node and choose Manage NuGet Packages for Solution.
  2. In the NuGet window, if Updates is showing a number next to it, like the screen shot below, select the Updates link

3. Place a check next to Microsoft.AspNetCore.All (ensure Include prerelease is NOT checked at this moment) and then click the Update button.

4. If necessary, click OK to close the Preview Changes

5. Click I Accept when the License Agreement dialog appears.

6. Click the Browse

7. Check Include prerelease.

8. In the Search field, type Microsoft.Bot.Builder.Integration.AspNet.Core and press Enter.

9. Select the preview component that appears.

10. Select your project on the right side of the window and then click Install.

11. If necessary, click OK to close the Preview Changes dialog.

12. Click I Accept when the License Agreement dialog appears.

13. Close the NuGet window when Visual Studio finishes.

14. Select Build | Rebuild Solution.

Add Your Bot’s Main Class and Modify Startup.cs

Now you’re ready to add your bot’s main class and modify the Startup.cs to turn this web project into a bot project.

  1. In the Solution Explorer, right click on your project’s node, and select Add Class.
  2. In the Add New Item dialog, enter a Name for the class like MyBot and click Add.
  3. Replace the existing using statements with the following:
using Microsoft.Bot;
using Microsoft.Bot.Builder;
using Microsoft.Bot.Schema;
using System.Threading.Tasks;

4. Change the class so that it inherits from IBot and implement the interface like so:

public class MyBot : IBot
{
    public Task OnTurn(ITurnContext turnContext)
    {
        throw new System.NotImplementedException();
    }
    
}

5. Open Startup.cs.

6. Replace the existing using statements with the following:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Bot.Builder.BotFramework;
using Microsoft.Bot.Builder.Integration.AspNet.Core;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

7. Next add the following private field:

private IConfiguration configuration;

8. Below the field you just added, add the following constructor to your class:

public Startup(IHostingEnvironment env)
{
    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();
}

9. Inside the ConfigureServices method, add the following code:

services.AddSingleton(configuration);
services.AddBot<MyBot>(options =>
{
    options.CredentialProvider = new ConfigurationCredentialProvider(configuration);
});

Note:If you didn’t name your bot class MyBot in the earlier step, fix up the second line of code to use the correct class name.

10. Lastly in this class, add the following line of code in the Configure method after the existing line

app.UseStaticFiles():
app.UseBotFramework();

11. Return to your bot class.

12. Modify the OnTurn method to be async:

public async Task OnTurn(ITurnContext turnContext)

13. Replace the existing body in OnTurn with the following:

if (turnContext.Activity.Type is ActivityTypes.Message)
{
    string userInput = turnContext.Activity.Text;
    await turnContext.SendActivity($"You wrote {userInput}");
}

14. Select Build | Rebuild Solution.

15. Fix any compile errors if necessary.

Test your bot locally using the Emulator

Now that you’ve created and built your bot, you’ll test it.

  1. Start the Bot Framework Emulator.
  2. Back in Visual Studio, select Debug | Start Debugging.
  3. In the web browser that opens, make a note of the port.
  4. Switch to the emulator and type your bot’s URL in the box Enter your endpoint URL.

5. On the New bot configuration Enter the bot name and the endpoint you saved from the browser when you started debugging. Leave the MSA app ID and MSA app password blank.

6. Click Save and connect. Save the MyBot.bot file in the project folder for you bot.

7. In the Type your message field, enter a message like Hello, World and press Enter. You should see what you typed followed by the bot’s reply like the following:

8. Switch to your web browser and close it (or at least the tab used by your bot).

9. In Visual Studio, select Debug | Stop Debugging.

10. Select Windows | Close All Documents to tidy up Visual Studio.

Deploy your bot to Azure

First you will deploy the bot to Azure in an App Service. Then you’ll configure your bot with the Azure Bot Service using the Bot Channels Registration item.

Publish from Visual Studio

Use Visual Studio to create your resources in Azure and publish your code.

  1. In the Solution Explorer window, right click on your project’s node and select Publish.
  2. In the Pick a publish target dialog, ensure App Service is selected on the left and Create New is selected on the left.

3. Click the Publish button.

4. In upper right of the dialog, ensure the dialog is showing the correct user ID for your Azure subscription.

5. Fill out the dialog.

  • App Name
  • Subscription
  • Resource Group – Click New to change the name.
  • Hosting Plan –Click New to change the name, plan type, and region.

6. When ready, click Create. It can take a few minutes to complete the process.

7. Once complete, a web browser will open showing your bot’s public URL.

8. Make a copy of this URL (it will be something like https://yourbotname.azurewebsites.net/).

Note:You’ll need to use the HTTPS version of the URL when registering your bot. Azure provides SSL support with Azure App Service.

Create your bot channels registration

With your bot deployed in Azure you need to register it with the Azure Bot Service.

  1. Access the Azure Portal at https://portal.azure.com.
  2. Log in using the same identity you used earlier from Visual Studio to publish your bot.
  3. Click Create a resource.
  4. In the Search the Marketplace field type Bot Channels Registration and press Enter.
  5. In the returned list, choose Bot Channels Registration:

6. Click create in the blade that opens.

7. Provide a Name for your bot.

8. Choose the same Subscription where you deployed your bot’s code.

9. Pick your existing Resource group which will set the location.

10. You can choose the F0 Pricing tier for development and testing.

11. Enter your bot’s URL. Make sure you start with HTTPS and that you add the /api/messages For example

https://yourbotname.azurewebsites.net/api/messages

12. Turn off Application Insights for now.

13. Click the Microsoft App ID and password

14. In the new blade click Create New.

15. In the new blade that opens to the right, click the Create App ID in the App Registration Portal A new browser tab opens.

16. In the new tab, make a copy of the App ID.

17. Click the Generate an app password to continue button.

18. A browser dialog opens and provides you with your app’s password.
Copy and save this secret somewhere you can get to later.

19. Click OK once you’ve got the password.

20. Just close the browser tab and return to the Azure Portal tab.

21. Paste in your App ID and Password in the correct fields and click OK.

22. Now click Create to set up your channel registration. This can take a few seconds to a few minutes.

Update your bot’s Application Settings

In order for your bot to authenticate with the Azure Bot Service, you need to add two settings to your Bot’s Application Settings in Azure App Service.

  1. In the Azure Portal, open your Resource group and locate your App Service for your bot.
  2. In the list of options on the right, locate Application Settings in the Settings section and click it.

3. Scroll until you find the Application settings section.

4. Click Add new setting.

5. Type MicrosoftAppId for the name and your App ID for the value.

6. Click Add new setting

7. Type MicrosoftAppPassword for the name and your password for the value.

8. Click the Save button up top.

Test Your Bot in Production

At this point, you can test your bot from Azure using the built-in Web Chat client.

  1. Go back to your Resource group in the portal
  2. Open your bot.
  3. Under Bot management, select Test in Web Chat.

4. Type a message like Hello, Web Chat! and press Enter.

5. If all goes well you should see your message echoed back.

Posted in .NET, Bot Framework, v4