BotBuilder v4 Preview Template For “dotnet new”
When experimenting with the new BotBuilder v4 Preview, the one thing that struck me was that all of the C# documentation required you to install a Visual Studio template. One of the major changes with v4 of the BotBuilder is that .Net Core is now supported! It seemed strange to have to rely on Visual Studio when we’re all going to be writing our bots using VS Code or even Rider
Delving into the VS template (I just unarchived it using The Unarchiver on my Mac), I quickly realised that it was actually just the Echo Bot sample packaged at a template. To carry on my xplat .Net journey, I decided to create a template that could be used to get going with making bots quickly.
Creating the template
Some/many/all readers of this post may not actually be interested in how templates are made and that’s ok. If you just want the installation and usage instructions, go here. The official documentation that I mostly followed to turn my project into a template can be found here
The nice thing about dotnet new templates is that you can turn any existing project into a template with minimal changes. All that’s required is to add a configuration file and to make your project distributable as a NuGet package. Below is the structure of my .Net Core project using the v4 preview BotBuilder package.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
└── botbuilder-v4preview-template ├── Bot │ ├── ApplicationConfiguration.cs │ ├── Bot.cs │ ├── Bot.csproj │ ├── BotState.cs │ ├── Pages │ │ ├── Index.cshtml │ │ └── Index.cshtml.cs │ ├── Program.cs │ ├── Startup.cs │ └── appsettings.json └── Bot.sln |
To turn this into a template, it first needs a template.json config file which will live in a folder named .template.config at the solution root. With the new directory and file added, the structure looks like this:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
└── botbuilder-v4preview-template ├── .template.config │ └── template.json ├── Bot │ ├── ApplicationConfiguration.cs │ ├── Bot.cs │ ├── Bot.csproj │ ├── BotState.cs │ ├── Pages │ │ ├── Index.cshtml │ │ └── Index.cshtml.cs │ ├── Program.cs │ ├── Startup.cs │ └── appsettings.json └── Bot.sln |
The contents of the template.json file for this simple bot project looks like this:
|
1 2 3 4 5 6 7 8 |
{ "$schema": "http://json.schemastore.org/template", "author": "Kristian Brimble", "classifications": [ "Bot", "Bot Framework", "v4 Bot", "Bot Builder", "Bot Builder v4" ], "identity": "v4-preview bot", "name": "Bot Builder v4 Preview", "shortName": "v4bot-pre" } |
This config has some basic about the template such as author and the name. The most important thing here is the shortName property as this is what users will use to invoke your template. For example, the shortName of the ASP.NET WebApi project is webapi. This project uses something slightly more verbose and I know that it’s not going to be useful forever due to it being a template for a framework version that’s currently in preview.
The next stage is to move everything into a folder named content and at the new top level directory to add a nuspec file. After moving things around and adding the nuspec file, the file structure will look like this:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
└── botbuilder-v4preview-template ├── botbuilder-v4preview-template.nuspec └── content ├── .template.config │ └── template.json ├── Bot │ ├── ApplicationConfiguration.cs │ ├── Bot.cs │ ├── Bot.csproj │ ├── BotState.cs │ ├── Pages │ │ ├── Index.cshtml │ │ └── Index.cshtml.cs │ ├── Program.cs │ ├── Startup.cs │ └── appsettings.json └── Bot.sln |
If you’ve ever seen a nuspec file before, this one will be much of a surprise but here it is anyway:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
<?xml version="1.0" encoding="utf-8"?> <package xmlns="http://schemas.microsoft.com/packaging/2012/06/nuspec.xsd"> <metadata> <id>BotBuilder.V4PreviewTemplate.CSharp</id> <title>BotBuilder v4 Preview dotnet new template</title> <version>1.0.1</version> <description> Creates a starter solution for building bots with the Bot Builder v4 preview </description> <authors>Kristian Brimble</authors> <projectUrl>https://github.com/kbrimble/botbuilder-v4preview-template</projectUrl> <packageTypes> <packageType name="Template" /> </packageTypes> </metadata> </package> |
The last stage is to pack and publish to [https://nuget.org]. Instructions for this are well documented elsewhere. To carry on with the dotnet CLI adventure, take a look at the official documentation here (Windows only).
Installing the template
Installing new templates is super simple. The command to use is dotnet new -i. In the case of my BotBuilder template, the command would be dotnet new -i BotBuilder.V4PreviewTemplate.CSharp. Entering dotnet new -l will list all of your installed templates as well as their short names. You can use the full name if you wish, but the short name is a lot quicker.
Creating a new project from the template
If you’ve ever created a project using the dotnet CLI before, this bit will feel the most familiar. The command is dotnet new. For the BotBuilder template, that would be dotnet new v4bot-pre.
Voila!
Some things will need renaming but a lot of the boilerplate set up code in Startup.cs and the basic code to handle bot activity is already there!