Getting Started


Microsoft Bot Builder is a powerful framework for constructing bots that can handle both freeform interactions and more guided ones where the possibilities are explicitly shown to the user. It is easy to use and leverages C# to provide a natural way to write bots.

High Level Features:

  • Powerful dialog system with dialogs that are isolated and composable.
  • Built-in dialogs for simple things like Yes/No, strings, numbers, enumerations.
  • Built-in dialogs that utilize powerful AI frameworks like LUIS.
  • Bots are stateless which helps them scale.
  • FormFlow for automatically generating a bot from a C# class for filling in the class and that supports help, navigation, clarification and confirmation.
  • SDK source code is found on


In order to use the Microsoft Bot Builder you should first follow the install steps in the Getting started with the Connector page to setup your bot. In order to use the framework you need to:

  1. Right-click on your project and select "Manage NuGet Packages".
  2. In the "Browse" tab, type "Microsoft.Bot.Builder".
  3. Click the "Install" button and accept the changes.

At this point your project has the builder installed and is ready to use it. If you want to understand how to create and use dialogs, see Dialogs or if you would like to have a dialog automatically constructed see FormFlow.


In order to debug your bot, you can either use the Bot Framework Emulator as described in Getting Started with Bot Connector or you can create a console app with a command loop like this:

static async Task Interactive<T>(IDialog<T> form) where T : class
// NOTE: I use the DejaVuSansMono fonts as described here:
// But you don't have to reboot.
// If you don't want the multi-lingual support just comment this out
Console.OutputEncoding = Encoding.GetEncoding(65001);
var message = new Activity()
From = new ChannelAccount { Id = "ConsoleUser" },
Conversation = new ConversationAccount { Id = Guid.NewGuid().ToString() },
Recipient = new ChannelAccount { Id = "FormTest" },
ChannelId = "Console",
ServiceUrl = "http://localhost:9000/",
Text = ""
var builder = new ContainerBuilder();
builder.RegisterModule(new DialogModule_MakeRoot());
builder.Register(c => new CachingBotDataStore(c.Resolve<InMemoryDataStore>(), CachingBotDataStoreConsistencyPolicy.ETagBasedConsistency))
.Register(c => new BotToUserTextWriter(new BotToUserQueue(message, new Queue<IMessageActivity>()), Console.Out))
// Trace activities to debug output
using (var container = builder.Build())
using (var scope = DialogModule.BeginLifetimeScope(container, message))
Func<IDialog<object>> MakeRoot = () => form;
DialogModule_MakeRoot.Register(scope, MakeRoot);
var task = scope.Resolve<IPostToBot>();
await scope.Resolve<IBotData>().LoadAsync(default(CancellationToken));
var stack = scope.Resolve<IDialogStack>();
stack.Call(MakeRoot(), null);
await stack.PollAsync(CancellationToken.None);
while (true)
message.Timestamp = DateTime.UtcNow;
message.Text = await Console.In.ReadLineAsync();
message.Locale = Locale;
await task.PostAsync(message, CancellationToken.None);

To use it your would do something like this:

Interactive(FormDialog.FromForm<AnnotatedSandwichOrder>(() => AnnotatedSandwichOrder.BuildForm())).GetAwaiter().GetResult();

Troubleshooting Q & A

If you have problems or suggestions, please visit our support page.