Using declarative assets in adaptive dialogs

APPLIES TO: SDK v4

This article explains the concepts behind declarative assets and bots that incorporate adaptive dialogs using the declarative approach. Declarative adaptive dialogs consist of JSON-based files that describe all of the attributes of adaptive dialogs, including their triggers and actions. These declarative files are loaded at run time using the resource manager to create the adaptive dialogs.

Prerequisites

Declarative files

Declarative files currently consist of .dialog files that describe all of the attributes of an adaptive dialog and .lg files that consist of LG templates that define the language generation (LG) aspects of your bot.

.dialog files

Adaptive dialog declarative files that have the .dialog extension contain the following elements:

  • The $schema value contains a URI pointing to the Schema that describes the format of this declarative file. That schema is a Bot Framework component schema, which adheres to draft 7 of the JSON schema vocabulary. This schema file enables IntelliSense to work for your declarative elements. For information on how to create this file, see the section on The merge command below. The name of the schema file can be any valid filename, but is typically named app.schema.
  • The $kind field identifies the type of component described in this file. For an adaptive dialog, $kind must be Microsoft.AdaptiveDialog. In sub-objects, $kind identifies a trigger or action that is part of the dialog. This field correlates with the [JsonProperty("$kind")] class attribute that is associated with every class in the Bot Framework SDK that is designed to work using the declarative approach.
  • The recognizer value contains a recognizer type and an array of one or more intents and optionally an array of one or more entities.
  • The generator value contains a link to the .lg file associated with the adaptive dialog that this .dialog file defines.
  • The triggers value contains an array of one or more triggers. The type of trigger is declared using the $kind keyword. Each trigger contains an array of one or more actions.
  • The actions value contains an array of one or more actions, each action can have properties associated with it.

An example of a simple .dialog file:

{
  "$schema": "../app.schema",
  "$kind": "Microsoft.AdaptiveDialog",
  "generator": "multiTurnPrompt.lg",
  "recognizer": {
      "$kind": "Microsoft.RegexRecognizer",
      "intents": [
          {
              "intent": "CancelIntent",
              "pattern": "(?i)cancel"
          }
      ]
  },
  "triggers": [
    {
      "$kind": "Microsoft.OnUnknownIntent",
      "actions": [
        {
          "$kind": "Microsoft.SendActivity",
          "activity":  "You said '${turn.activity.text}'"
        }
      ]
    }
  ]
}

Note

The $schema file is what enables IntelliSense to work. No warning or error will occur if $schema keyword is missing or the $schema value references a schema file that cannot be found and everything except IntelliSense will still work as expected.

The elements of the .dialog file defined:

Create Get Weather Dialog

For information on how .dialog files can be generated automatically using the CLI luis:build command when creating a LUIS application see The dialog file section of the Deploy LUIS resources using the Bot Framework LUIS CLI commands article.

For information on how .dialog files can be generated automatically using the CLI qnamaker:build command when creating a QnA Maker knowledge base see The dialog file section of the Deploy QnA Maker knowledge base using the Bot Framework qnamaker CLI commands article.

.lg files

Adaptive dialog declarative files that have the .lg extension are described in detail in the .lg file format article.

The resource explorer

The resource explorer provides the tools you need to import declarative adaptive dialog files into your bot and use them as if they were adaptive dialogs defined directly in your bot source code.

With the resource explorer, you can create resource objects that contain all of the relevant information about the declarative files required to create adaptive dialogs at run time, which is done using the resource explorer's type loader that imports files with the .dialog and .lg extensions.

The resource object

The resource explorer's get resource method reads the declarative file into a resource object. The resource object contains the information about the declarative file and can be used by any process that needs to reference it, such as the type loader.

var resource = this.resourceExplorer.GetResource("main.dialog");

The type loader

Once the resource explorer's _get resource_ method reads the declarative file into a resource object, the _load type_method casts the resource to an AdaptiveDialog object. The AdaptiveDialog object can be used the same as any other non-declarative adaptive dialog is used when creating a dialog manager.

dialogManager = new DialogManager(resourceExplorer.LoadType<AdaptiveDialog>(resource));

Auto reload dialogs when file changes

Any time a declarative file changes when your bot is running, a changed event fires. You can capture that event and reload your declarative files, that way when any adaptive dialog needs updated you do not need to update your code and recompile your source code or restart your bot. This can be especially useful in a production environment.

// auto reload the root dialog when it changes
this.resourceExplorer.Changed += (e, resources) =>
{
    if (resources.Any(resource => resource.Id == "main.dialog"))
    {
        Task.Run(() => this.LoadRootDialogAsync());
    }
};

private void LoadRootDialogAsync()
{
    var resource = this.resourceExplorer.GetResource("main.dialog");
    dialogManager = new DialogManager(resourceExplorer.LoadType<AdaptiveDialog>(resource));
}

The VersionChanged event

When your declarative assets have been reloaded to accommodate the changes made to a .dialog file, you may need to reevaluate the state of any current conversations to account of any changes to the logic of your dialog. The changes to your logic may be as simple as to clear your conversation stack and restart. More sophisticated logic would enable you to do things like restart a dialog keeping the data you have, allowing you to pick up new properties and or paths that didn't exist before.

The DialogEvents.VersionChanged event is captured using the OnDialogEvent trigger.

Triggers = new List<OnCondition>()
{
    new OnDialogEvent(DialogEvents.VersionChanged)
    {
        Actions = new List<Dialog>()
        {
            new SendActivity("The VersionChanged event fired.")
        }
    }
}

Declarative assets

The Bot Framework SDK has various declarative assets available, each will be listed below. These assets can be used in your .dialog files as the $kind value.

Triggers

This section contains all triggers, grouped by type:

Base trigger

$kind value Trigger Name What this trigger does
Microsoft.OnCondition OnCondition The OnCondition trigger is the base trigger that all triggers derive from. When defining triggers in an adaptive dialog they are defined as a list of OnCondition triggers.

Recognizer event triggers

$kind value Trigger name Description
Microsoft.OnChooseIntent OnChooseIntent This trigger is run when ambiguity has been detected between intents from multiple recognizers in a CrossTrainedRecognizerSet.
Microsoft.OnIntent OnIntent Actions to perform when specified intent is recognized.
Microsoft.OnQnAMatch OnQnAMatch This trigger is run when the QnAMakerRecognizer has returned a QnAMatch intent. The entity @answer will have the QnAMaker answer.
Microsoft.OnUnknownIntent OnUnknownIntent Actions to perform when user input is unrecognized or no match is found in any of the OnIntent triggers.

Dialog event triggers

$kind value Trigger name Description
Microsoft.OnBeginDialog OnBeginDialog Actions to perform when this dialog begins. For use with child dialogs only.
Microsoft.OnCancelDialog OnCancelDialog This event allows you to prevent the current dialog from being cancelled due to a child dialog executing a CancelAllDialogs action.
Microsoft.OnEndOfActions OnEndOfActions This event occurs once all actions and ambiguity events have been processed.
Microsoft.OnError OnError Action to perform when an Error dialog event occurs. This event is similar to OnCancelDialog in that you are preventing the current dialog from ending, in this case due to an error in a child dialog.
Microsoft.OnRepromptDialog OnRepromptDialog Actions to perform when RepromptDialog event occurs.

Important

Do not use the OnBeginDialog trigger in your root dialog as it can potentially cause problems. You can instead use the OnUnknownIntent trigger which will fire when your root dialog runs.

Tip

Most child dialogs include an OnBeginDialog trigger that responds to the BeginDialog event. This trigger automatically fires when the dialog begins, which can allow the bot to respond immediately with a welcome message or a prompt for user input.

Dialog event trigger example using declarative
{
    "$schema": "../app.schema",
    "$kind": "Microsoft.AdaptiveDialog",
    "triggers": [
        {
            "$kind": "Microsoft.OnBeginDialog",
            "actions": [
                {
                    "$kind": "Microsoft.SendActivity",
                    "activity": "Hello world!"
                }
            ]
        }
    ]
}

Activity event triggers

Activity triggers enable you to associate actions to any incoming activity from the client such as when a new user joins and the bot begins a new conversation. Additional information on activities can be found in Bot Framework Activity schema.

$kind value Trigger name Description
Microsoft.OnConversationUpdateActivity OnConversationUpdateActivity Handle the events fired when a user begins a new conversation with the bot.
Microsoft.OnEndOfConversationActivity OnEndOfConversationActivity Actions to perform on receipt of an activity with type EndOfConversation.
Microsoft.OnEventActivity OnEventActivity Actions to perform on receipt of an activity with type Event.
Microsoft.OnHandoffActivity OnHandoffActivity Actions to perform on receipt of an activity with type HandOff.
Microsoft.OnInvokeActivity OnInvokeActivity Actions to perform on receipt of an activity with type Invoke.
Microsoft.OnTypingActivity OnTypingActivity Actions to perform on receipt of an activity with type Typing.

Message event triggers

Message event triggers allow you to react to any message event such as when a message is updated (MessageUpdate) or deleted (MessageDeletion) or when someone reacts (MessageReaction) to a message (for example, some of the common message reactions include a Like, Heart, Laugh, Surprised, Sad and Angry reactions).

Message events are a type of activity event and as such, all message events have a base event of ActivityReceived and are further refined by ActivityType. The Base class that all message triggers derive from is OnActivity.

$kind value Trigger name Description
Microsoft.OnMessageActivity OnMessageActivity Actions to perform on receipt of an activity with type MessageReceived.
Microsoft.OnMessageDeleteActivity OnMessageDeleteActivity Actions to perform on receipt of an activity with type MessageDelete.
Microsoft.OnMessageReactionActivity OnMessageReactionActivity Actions to perform on receipt of an activity with type MessageReaction.
Microsoft.OnMessageUpdateActivity OnMessageUpdateActivity Actions to perform on receipt of an activity with type MessageUpdate.

Custom event triggers

You can emit your own events by adding the EmitEvent action to any trigger, then you can handle that custom event in any trigger in any dialog in your bot by defining a custom event trigger. A custom event trigger is a type of OnDialogEvent trigger, where its event property to the same value as the emit event's event name property.

Tip

You can allow other dialogs in your bot to handle your custom event by setting the emit event's bubble event property to true.

$kind value Trigger name Description
Microsoft.OnDialogEvent OnDialogEvent Actions to perform when a custom event is detected. Use Emit a custom event' action to raise a custom event.

Actions

This section contains all actions, grouped by type:

Send a response

$kind value Action Name What this action does
Microsoft.SendActivity SendActivity Enables you send any type of activity such as responding to users.

Requesting user input

$kind value Input class Description Returns
Microsoft.AttachmentInput AttachmentInput Used to request/enable a user to upload a file. A collection of attachment objects.
Microsoft.ChoiceInput ChoiceInput Used to asks for a choice from a set of options. The value or index of the selection.
Microsoft.ConfirmInput ConfirmInput Used to request a confirmation from the user. A Boolean value.
Microsoft.DateTimeInput DateTimeInput Used to ask your users for a date and or time. A collection of date-time objects.
Microsoft.InputDialog InputDialog This is the base class that all of the input classes derive from. It defines all shared properties.
Microsoft.NumberInput NumberInput Used to ask your users for a number. A numeric value.
Microsoft.OAuthInput OAuthInput Used to enable your users to sign into a secure site. A token response.
Microsoft.TextInput TextInput Used to ask your users for a word or sentence. A string.

Create a condition

Activity to accomplish $kind value Action Name What this action does
Branch: if/else Microsoft.IfCondition IfCondition Used to create If and If-Else statements which are used to execute code only if a condition is true.
Branch: Switch (Multiple options) Microsoft.SwitchCondition SwitchCondition Used to build a multiple-choice menu.
Loop: for each item Microsoft.Foreach ForEach Loop through a set of values stored in an array.
Loop: for each page (multiple items) Microsoft.ForeachPage ForEachPage Loop through a large set of values stored in an array one page at a time.
Exit a loop Microsoft.BreakLoop BreakLoop Break out of a loop.
Continue a loop Microsoft.ContinueLoop ContinueLoop Continue the loop.
Goto a different Action Microsoft.GotoAction GotoAction Immediately goes to the specified action and continues execution. Determined by actionId.

Dialog management

$kind value Action Name What this action does
Microsoft.BeginDialog BeginDialog Begins executing another dialog. When that dialog finishes, the execution of the current trigger will resume.
Microsoft.CancelDialog CancelDialog Cancels the active dialog. Use when you want the dialog to close immediately, even if that means stopping mid-process.
Microsoft.CancelAllDialogs CancelAllDialogs Cancels all active dialogs including any active parent dialogs. Use this if you want to pop all dialogs off the stack, you can clear the dialog stack by calling the dialog context's cancel all dialogs method. Emits the CancelAllDialogs event.
Microsoft.EndDialog EndDialog Ends the active dialog. Use when you want the dialog to complete and return results before ending. Emits the EndDialog event.
Microsoft.EndTurn EndTurn Ends the current turn of conversation without ending the dialog.
Microsoft.RepeatDialog RepeatDialog Used to restart the parent dialog.
Microsoft.ReplaceDialog ReplaceDialog Replaces the current dialog with a new dialog
Microsoft.UpdateActivity UpdateActivity This enables you to update an activity that was sent.
Microsoft.DeleteActivity DeleteActivity Enables you to delete an activity that was sent.
Microsoft.GetActivityMembers GetActivityMembers Enables you to get a list of activity members and save it to a property in memory.
Microsoft.GetConversationMembers GetConversationMembers Enables you to get a list of the conversation members and save it to a property in memory.
Microsoft.EditActions EditActions Enables you to edit the current action sequence on the fly based on user input. Especially useful when handling interruptions.

Manage properties

$kind value Action Name What this action does
Microsoft.EditArray EditArray This enables you to perform edit operations on an array.
Microsoft.DeleteProperty DeleteProperty This enables you to remove a property from memory.
Microsoft.DeleteProperties DeleteProperties This enables you to delete more than one property in a single action.
Microsoft.SetProperty SetProperty This enables you to set a property's value in memory.
Microsoft.SetProperties SetProperties This enables you to initialize one or more properties in a single action.

Access external resources

$kind value Action Name What this action does
Microsoft.BeginSkill BeginSkill Use the adaptive skill dialog to run a skill.
Microsoft.HttpRequest HttpRequest Enables you to make HTTP requests to any endpoint.
Microsoft.EmitEvent EmitEvent Enables you to raise a custom event that your bot can respond to using a custom trigger.
Microsoft.SignOutUser SignOutUser Enables you to sign out the currently signed in user.

Debugging options

$kind value Action Name What this action does
Microsoft.LogAction LogAction Writes to the console and optionally sends the message as a trace activity.
Microsoft.TraceActivity TraceActivity Sends a trace activity with whatever payload you specify.

Recognizers

The Bot Framework SDK provides over a half dozen different recognizers, you specify which recognizer to use in the .dialog file, for example:

{
    "$schema": "../app.schema",
    "$kind": "Microsoft.AdaptiveDialog",
    "recognizer": {
        "$kind": "Microsoft.RegexRecognizer",
        "intents": [
            {
                "intent": "JokeIntent",
                "pattern": "(?i)joke"
            },
            {
                "intent": "FortuneTellerIntent",
                "pattern": "(?i)fortune|future"
            },
            {
                "intent": "CancelIntent",
                "pattern": "(?i)cancel"
            }
        ]
    },
    ...
}

Adaptive dialogs support the following recognizers:

Generators

The generator value contains a link to the .lg file associated with the adaptive dialog that this .dialog file defines. For example:

{
    "$schema": "../app.schema",
    "$kind": "Microsoft.AdaptiveDialog",
    "generator": "MyBotGeneratorFile.lg",
    ...
}

The Bot Framework Command-Line Interface

Several new Bot Framework Command-Line Interface (BF CLI) commands were added with the release of adaptive dialogs in the Bot Framework SDK. This includes two dialog related commands for working with .dialog and .schema files that are very useful when using the declarative approach to adaptive dialog development.

The new CLI dialog group has the following two commands: dialog:merge and dialog:verify.

The merge command

The root schema file contains the schemas of all the components that are consumed by your bot. Every consumer of declarative files, including Composer, needs a schema file.

The dialog:merge command is used to generate your project's schema file. You will need to run this command anytime you add a new package or create or modify your own components.

This creates a file named app.schema in the current directory, unless specified otherwise using the -o option. This file is referenced by the "$schema keyword in each of the .dialog files in your project.

Note

A valid app.schema file is required for Intelligent code completion tools such as IntelliSense to work with any of the declarative assets.

To use the merge command, enter the following at the command prompt, while in the root directory of your project:

bf dialog:merge <filename.csproj>

For additional information on using this command, see bf dialog:merge in the BF CLI LUIS readme.

For an example see Creating the schema file in the Create a bot using declarative adaptive dialogs article.

The verify command

The dialog:verify command will check .dialog files to verify that they are compatible with the schema.

To use the verify command, enter the following at the command prompt, while in the root directory of your project:

bf dialog:verify <filename.csproj>

For additional information on using this command, see bf dialog:verify in the BF CLI LUIS readme.

Note

Composer creates a merged .schema file and valid .dialog files; however, the verify command can be very useful if you are creating these files by hand.

Install the Bot Framework CLI

Bot Framework CLI requires Node.js.

  1. Make sure you have the latest version of npm installed:

    npm i -g npm
    
  2. Using Node.js, install the latest version of Bot Framework CLI from the command line.

    npm i -g @microsoft/botframework-cli
    

For more information, see Bot Framework CLI tool.

Relevant information

Additional information