Introducing BotBuilder Config for the Bot Framework

by Michael Szul on

The problem with open source software is that if you see something that isn't quite working the way you think it should, you have no excuse to sit there and complain about it. You can do something about it instead.

Last weekend, I was minding my own business, working on the Bot Framework book that I've been writing for over a year now. I'm at the beginning of a chapter where I'm building a chatbot from end-to-end, from conception, to mock-up, to code, to completion and deployment. I wanted to make sure that I incorporated every command line utility that Microsoft has been building out with the BotBuilder tools, including Chatdown, LUDown, and MSBot. MSBot, of course, gives you the ability to attach all of your services, including encrypted keys, and keep things stored in a single place for later usage.

I write up the MSBot work. I write up the LUDown and the Chatdown. I write the QnaMaker CLI code, and get all the services setup and attached to the *.bot file. I then start the preliminary work on setting up the bot code, deciding to start with the QnA Maker interface, since that doesn't require any dialog management. I read up on the sample code, see how it differs from SDK v3, and then plug it into my sample. While doing so, I noticed that the sample wasn't accessing the bot file, so I searched around a little more. Then I came across an issue on one of Microsoft's GitHub repositories, basically saying that they really ought to have a way to consume this… Head? Meet table.

Okay, so this isn't so bad. I'm a programmer most of the time. Let's do this.

The bot file is just JSON, so I can just consume it like any JSON, but I've encrypted some of my service properties. I'll need to be able to decrypt them. I did some research, went through the MSBot CLI code, and found the appropriate decryption utility and properties. The result? In order to write 5 lines of code as an example in my book, I spent the entire weekend--and three iterations--building out BotBuilder Config--a utility for consuming and decrypting your bot file services, properties, etc.

To install:

npm install botbuilder-config --save

To import the module in JavaScript:

let { BotConfig } = require("botbuilder-config");

To instantiate the configuration:

let c = new BotConfig({ botFilePath: "PATH_TO_BOT_FILE", secret: "SECRET" });

What about TypeScript? Oh, you know we have TypeScript covered. The module was written in TypeScript, after all.

To import the module:

import { BotConfig } from "botbuilder-config";

To instantiate the configuration:

let c = new BotConfig({ botFilePath: "PATH_TO_BOT_FILE", secret: "SECRET" });

One important thing to note is that the BotConfigurationOptions parameter is optional, as is its properties. If you leave off the secret, it assumes that you did not encrypt any of your bot file properties. If you leave off the path, it assumes the bot file is in the current working directory.

Accessing a bot service (and bot service properties) from the configuration object is pretty simple.

let qna = c.QnAMaker();
      qna.endpoint;

You can access any of your connected services, using the following methods:

  • Endpoint()
  • AzureBotService()
  • QnAMaker()
  • LUIS()
  • Dispatch()

If you have more than a single service of the same type, you can specify an optional name parameter to the service method such as c.QnAMaker("MY_SERVICE_NAME") that matches the name property of the service in your bot file. If not, it will return the first service of that type that it finds.

The biggest reason I created this module was because not only did I have a bot file, but also had used the encryption capabilities of MSBot in order to encrypt certain properties and check that bot file into GitHub. The advantage of this library is that it will decrypt your properties, if you have encrypted them with a secret.

let c = new BotConfig({ botFilePath: "PATH_TO_BOT_FILE", secret: "SECRET" });
      let s = c.decrypt(c.QnAMaker().subscriptionKey);
      console.log(s);

As of right now, this module sits at version 0.4.0, so it isn't even close to release caliber. I'm sure there will be a ton of changes between now and a 1.0 version release, and Microsoft is liable to introduce changes that break this module, since the other BotBuilder tools are in preview. On top of that, I have to imagine that Microsoft will release its own built-in way to work with the bot file, rendering this library obsolete, but as of right now, I needed this in order to continue with the chapter in my book. I'll keep maintaining it, and when Microsoft finally does render it obsolete, I'll add additional functionality to it, so it can serve as an alternative.

Until then, feel free to file issues on GitHub, and submit pull requests as you see fit.