|
| 1 | +# generator-botbuilder-java |
| 2 | + |
| 3 | +Yeoman generator for [Bot Framework v4](https://dev.botframework.com). Will let you quickly set up a conversational AI bot |
| 4 | +using core AI capabilities. |
| 5 | + |
| 6 | +## About |
| 7 | + |
| 8 | +`generator-botbuilder-java` will help you build new conversational AI bots using the [Bot Framework v4](https://dev.botframework.com). |
| 9 | + |
| 10 | +## Templates |
| 11 | + |
| 12 | +The generator supports three different template options. The table below can help guide which template is right for you. |
| 13 | + |
| 14 | +| Template | Description | |
| 15 | +| ---------- | --------- | |
| 16 | +| Echo Bot | A good template if you want a little more than "Hello World!", but not much more. This template handles the very basics of sending messages to a bot, and having the bot process the messages by repeating them back to the user. This template produces a bot that simply "echoes" back to the user anything the user says to the bot. | |
| 17 | +| Empty Bot | A good template if you are familiar with Bot Framework v4, and simply want a basic skeleton project. Also a good option if you want to take sample code from the documentation and paste it into a minimal bot in order to learn. | |
| 18 | +| Core Bot | A good template if you want to create advanced bots, as it uses multi-turn dialogs and [LUIS](https://www.luis.ai), an AI based cognitive service, to implement language understanding. This template creates a bot that can extract places and dates to book a flight. | |
| 19 | + |
| 20 | +### How to Choose a Template |
| 21 | + |
| 22 | +| Template | When This Template is a Good Choice | |
| 23 | +| -------- | -------- | |
| 24 | +| Echo Bot | You are new to Bot Framework v4 and want a working bot with minimal features. | |
| 25 | +| Empty Bot | You are a seasoned Bot Framework v4 developer. You've built bots before, and want the minimum skeleton of a bot. | |
| 26 | +| Core Bot | You are a medium to advanced user of Bot Framework v4 and want to start integrating language understanding as well as multi-turn dialogs in your bots. | |
| 27 | + |
| 28 | +### Template Overview |
| 29 | + |
| 30 | +#### Echo Bot Template |
| 31 | + |
| 32 | +The Echo Bot template is slightly more than the a classic "Hello World!" example, but not by much. This template shows the basic structure of a bot, how a bot receives messages from a user, and how a bot sends messages to a user. The bot will "echo" back to the user, what the user says to the bot. It is a good choice for first time, new to Bot Framework v4 developers. |
| 33 | + |
| 34 | +#### Empty Bot Template |
| 35 | + |
| 36 | +The Empty Bot template is the minimal skeleton code for a bot. It provides a stub `onTurn` handler but does not perform any actions. If you are experienced writing bots with Bot Framework v4 and want the minimum scaffolding, the Empty template is for you. |
| 37 | + |
| 38 | +#### Core Bot Template |
| 39 | + |
| 40 | +The Core Bot template uses [LUIS](https://www.luis.ai) to implement core AI capabilities, a multi-turn conversation using Dialogs, handles user interruptions, and prompts for and validate requests for information from the user. This template implements a basic three-step waterfall dialog, where the first step asks the user for an input to book a flight, then asks the user if the information is correct, and finally confirms the booking with the user. Choose this template if want to create an advanced bot that can extract information from the user's input. |
| 41 | + |
| 42 | +## Installation |
| 43 | + |
| 44 | +1. Install [Yeoman](http://yeoman.io) using [npm](https://www.npmjs.com) (we assume you have pre-installed [node.js](https://nodejs.org/)). |
| 45 | + |
| 46 | + ```bash |
| 47 | + # Make sure both are installed globally |
| 48 | + npm install -g yo |
| 49 | + ``` |
| 50 | + |
| 51 | +2. Install generator-botbuilder-java by typing the following in your console: |
| 52 | + |
| 53 | + ```bash |
| 54 | + # Make sure both are installed globally |
| 55 | + npm install -g generator-botbuilder-java |
| 56 | + ``` |
| 57 | + |
| 58 | +3. Verify that Yeoman and generator-botbuilder-java have been installed correctly by typing the following into your console: |
| 59 | + |
| 60 | + ```bash |
| 61 | + yo botbuilder-java --help |
| 62 | + ``` |
| 63 | + |
| 64 | +## Usage |
| 65 | + |
| 66 | +### Creating a New Bot Project |
| 67 | + |
| 68 | +When the generator is launched, it will prompt for the information required to create a new bot. |
| 69 | + |
| 70 | +```bash |
| 71 | +# Run the generator in interactive mode |
| 72 | +yo botbuilder-java |
| 73 | +``` |
| 74 | + |
| 75 | +### Generator Command Line Options |
| 76 | + |
| 77 | +The generator supports a number of command line options that can be used to change the generator's default options or to pre-seed a prompt. |
| 78 | +
|
| 79 | +| Command line Option | Description | |
| 80 | +| ------------------- | ----------- | |
| 81 | +| --help, -h | List help text for all supported command-line options | |
| 82 | +| --botName, -N | The name given to the bot project | |
| 83 | +| --packageName, -P | The Java package name to use for the bot | |
| 84 | +| --template, -T | The template used to generate the project. Options are `empty`, or `echo`. See [https://aka.ms/botbuilder-generator](https://aka.ms/botbuilder-generator) for additional information regarding the different template option and their functional differences. | |
| 85 | +| --noprompt | The generator will not prompt for confirmation before creating a new bot. Any requirement options not passed on the command line will use a reasonable default value. This option is intended to enable automated bot generation for testing purposes. | |
| 86 | +
|
| 87 | +#### Example Using Command Line Options |
| 88 | +
|
| 89 | +This example shows how to pass command line options to the generator, setting the default language to TypeScript and the default template to Core. |
| 90 | +
|
| 91 | +```bash |
| 92 | +# Run the generator defaulting the pacakge name and the template |
| 93 | +yo botbuilder-java --P "com.mycompany.bot" --T "echo" |
| 94 | +``` |
| 95 | +
|
| 96 | +### Generating a Bot Using --noprompt |
| 97 | +
|
| 98 | +The generator can be run in `--noprompt` mode, which can be used for automated bot creation. When run in `--noprompt` mode, the generator can be configured using command line options as documented above. If a command line option is ommitted a reasonable default will be used. In addition, passing the `--noprompt` option will cause the generator to create a new bot project without prompting for confirmation before generating the bot. |
| 99 | +
|
| 100 | +#### Default Options |
| 101 | +
|
| 102 | +| Command line Option | Default Value | |
| 103 | +| ------------------- | ----------- | |
| 104 | +| --botname, -N | `echo` | |
| 105 | +| --packageName, -p | `echo` | |
| 106 | +| --template, -T | `echo` | |
| 107 | +
|
| 108 | +#### Examples Using --noprompt |
| 109 | +
|
| 110 | +This example shows how to run the generator in --noprompt mode, setting all required options on the command line. |
| 111 | +
|
| 112 | +```bash |
| 113 | +# Run the generator, setting all command line options |
| 114 | +yo botbuilder-java --noprompt -N "MyEchoBot" -P "com.mycompany.bot.echo" -T "echo" |
| 115 | +``` |
| 116 | +
|
| 117 | +This example shows how to run the generator in --noprompt mode, using all the default command line options. The generator will create a bot project using all the default values specified in the **Default Options** table above. |
| 118 | +
|
| 119 | +```bash |
| 120 | +# Run the generator using all default options |
| 121 | +yo botbuilder-java --noprompt |
| 122 | +``` |
| 123 | +
|
| 124 | +## Logging Issues and Providing Feedback |
| 125 | +
|
| 126 | +Issues and feedback about the botbuilder generator can be submitted through the project's [GitHub Issues](https://github.com/Microsoft/botbuilder-java/issues) page. |
0 commit comments