ComponentDialog class

Package:

botbuilder-dialogs

Base class for a dialog that contains other child dialogs.

Extends

DialogContainer<O>

Remarks

Component dialogs let you break your bot's logic up into components that can themselves be added as a dialog to another ComponentDialog or DialogSet. Components can also be exported as part of a node package and used within other bots.

To define a new component derive a class from ComponentDialog and add your child dialogs within the classes constructor:

const { ComponentDialog, WaterfallDialog, TextPrompt, NumberPrompt } = require('botbuilder-dialogs');

class FillProfileDialog extends ComponentDialog {
    constructor(dialogId) {
        super(dialogId);

        // Add control flow dialogs
        this.addDialog(new WaterfallDialog('start', [
            async (step) => {
                // Ask user their name
                return await step.prompt('namePrompt', `What's your name?`);
            },
            async (step) => {
                // Remember the users answer
                step.values['name'] = step.result;

                // Ask user their age.
                return await step.prompt('agePrompt', `Hi ${step.values['name']}. How old are you?`);
            },
            async (step) => {
                // Remember the users answer
                step.values['age'] = step.result;

                // End the component and return the completed profile.
                return await step.endDialog(step.values);
            }
        ]));

        // Add prompts
        this.addDialog(new TextPrompt('namePrompt'));
        this.addDialog(new NumberPrompt('agePrompt'))
    }
}
module.exports.FillProfileDialog = FillProfileDialog;

You can then add new instances of your component to another DialogSet or ComponentDialog:

const dialogs = new DialogSet(dialogState);
dialogs.add(new FillProfileDialog('fillProfile'));

Constructors

ComponentDialog(string)

Creates a new instance of the Dialog class.

Properties

id	Unique ID of the dialog. Sets the unique ID of the dialog.
telemetryClient	Set the telemetry client, and also apply it to all child dialogs. Future dialogs added to the component will also inherit this client. Get the current telemetry client.

Inherited Properties

dialogs	The containers dialog set.
EndOfTurn	Gets a default end-of-turn result.

Methods

addDialog(Dialog)	Adds a child Dialog or prompt to the components internal DialogSet.
beginDialog(DialogContext, O)	Called when the dialog is started and pushed onto the parent's dialog stack. By default, this calls the Dialog.BeginDialogAsync(DialogContext, object, CancellationToken) method of the component dialog's initial dialog, as defined by InitialDialogId. Override this method in a derived class to implement interrupt logic.
continueDialog(DialogContext)	Called when the dialog is continued, where it is the active dialog and the user replies with a new Activity. If this method is not overridden, the dialog automatically ends when the user replies.
createChildContext(DialogContext)	Creates the inner dialog context
endDialog(TurnContext, DialogInstance, DialogReason)	Called when the Dialog is ending.
repromptDialog(TurnContext, DialogInstance)	Called when the dialog should re-prompt the user for input.
resumeDialog(DialogContext, DialogReason, any)	Called when a child dialog on the parent's dialog stack completed this turn, returning control to this dialog component.

Inherited Methods

configure(Record<string, unknown>)	Fluent method for configuring the object.
findDialog(string)	Finds a child dialog that was previously added to the container.
getConverter(string)
getVersion()	An encoded string used to aid in the detection of bot changes on re-deployment.
onDialogEvent(DialogContext, DialogEvent)	Called when an event has been raised, using DialogContext.emitEvent(), by either the current dialog or a dialog that the current dialog started.

Constructor Details

ComponentDialog(string)

Creates a new instance of the Dialog class.

new ComponentDialog(dialogId?: string)

Parameters

dialogId

string

Optional. unique ID of the dialog.

Property Details

id

Unique ID of the dialog. Sets the unique ID of the dialog.

string id

Property Value

string

The Id for the dialog.

Remarks

This will be automatically generated if not specified.

telemetryClient

Set the telemetry client, and also apply it to all child dialogs. Future dialogs added to the component will also inherit this client. Get the current telemetry client.

BotTelemetryClient telemetryClient

Property Value

BotTelemetryClient

The BotTelemetryClient to use for logging.

Inherited Property Details

dialogs

The containers dialog set.

dialogs: DialogSet

Property Value

DialogSet

Inherited From DialogContainer.dialogs

EndOfTurn

Gets a default end-of-turn result.

static EndOfTurn: DialogTurnResult

Property Value

DialogTurnResult

Remarks

This result indicates that a dialog (or a logical step within a dialog) has completed processing for the current turn, is still active, and is waiting for more input.

Inherited From Dialog.EndOfTurn

Method Details

addDialog(Dialog)

Adds a child Dialog or prompt to the components internal DialogSet.

function addDialog(dialog: Dialog): this

Parameters

dialog

Dialog

The child Dialog or prompt to add.

Returns

this

The ComponentDialog after the operation is complete.

Remarks

The Dialog.id of the first child added to the component will be assigned to the initialDialogId property.

beginDialog(DialogContext, O)

Called when the dialog is started and pushed onto the parent's dialog stack. By default, this calls the Dialog.BeginDialogAsync(DialogContext, object, CancellationToken) method of the component dialog's initial dialog, as defined by InitialDialogId. Override this method in a derived class to implement interrupt logic.

function beginDialog(outerDC: DialogContext, options?: O): Promise<DialogTurnResult>

Parameters

outerDC

DialogContext

The parent DialogContext for the current turn of conversation.

options

O

Optional, initial information to pass to the dialog.

Returns

Promise<DialogTurnResult>

A Promise representing the asynchronous operation.

Remarks

If the task is successful, the result indicates whether the dialog is still active after the turn has been processed by the dialog.

continueDialog(DialogContext)

Called when the dialog is continued, where it is the active dialog and the user replies with a new Activity. If this method is not overridden, the dialog automatically ends when the user replies.

function continueDialog(outerDC: DialogContext): Promise<DialogTurnResult>

Parameters

outerDC

DialogContext

The parent DialogContext for the current turn of conversation.

Returns

Promise<DialogTurnResult>

A Promise representing the asynchronous operation.

Remarks

If the task is successful, the result indicates whether the dialog is still active after the turn has been processed by the dialog. The result may also contain a return value.

createChildContext(DialogContext)

Creates the inner dialog context

function createChildContext(outerDC: DialogContext): DialogContext

Parameters

outerDC

DialogContext

the outer dialog context

Returns

DialogContext

The created Dialog Context.

endDialog(TurnContext, DialogInstance, DialogReason)

Called when the Dialog is ending.

function endDialog(context: TurnContext, instance: DialogInstance, reason: DialogReason): Promise<void>

Parameters

context

TurnContext

The TurnContext object for this turn.

instance

DialogInstance

State information associated with the instance of this component Dialog on its parent's dialog stack.

reason

DialogReason

Reason why the Dialog ended.

Returns

Promise<void>

A Promise representing the asynchronous operation.

Remarks

When this method is called from the parent dialog's context, the component Dialog cancels all of the dialogs on its inner dialog stack before ending.

repromptDialog(TurnContext, DialogInstance)

Called when the dialog should re-prompt the user for input.

function repromptDialog(context: TurnContext, instance: DialogInstance): Promise<void>

Parameters

context

TurnContext

The TurnContext object for this turn.

instance

DialogInstance

State information for this dialog.

Returns

Promise<void>

A Promise representing the asynchronous operation.

resumeDialog(DialogContext, DialogReason, any)

Called when a child dialog on the parent's dialog stack completed this turn, returning control to this dialog component.

function resumeDialog(outerDC: DialogContext, _reason: DialogReason, _result?: any): Promise<DialogTurnResult>

Parameters

outerDC

DialogContext

The DialogContext for the current turn of conversation.

_reason

DialogReason

Reason why the dialog resumed.

_result

any

Optional, value returned from the dialog that was called. The type of the value returned is dependent on the child dialog.

Returns

Promise<DialogTurnResult>

A Promise representing the asynchronous operation.

Remarks

If the task is successful, the result indicates whether this dialog is still active after this dialog turn has been processed. Generally, the child dialog was started with a call to beginDialog(DialogContext, object) in the parent's context. However, if the DialogContext.replaceDialog(string, object) method is called, the logical child dialog may be different than the original. If this method is not overridden, the dialog automatically calls its RepromptDialog(ITurnContext, DialogInstance) when the user replies.

Inherited Method Details

configure(Record<string, unknown>)

Fluent method for configuring the object.

function configure(config: Record<string, unknown>): this

Parameters

config

Record<string, unknown>

Configuration settings to apply.

Returns

this

The Configurable after the operation is complete.

Inherited From Configurable.configure

findDialog(string)

Finds a child dialog that was previously added to the container.

function findDialog(dialogId: string): Dialog | undefined

Parameters

dialogId

string

ID of the dialog to lookup.

Returns

Dialog | undefined

The Dialog if found; otherwise null.

Inherited From DialogContainer.findDialog

getConverter(string)

function getConverter(_property: string): Converter | ConverterFactory

Parameters

_property

string

The key of the conditional selector configuration.

Returns

Converter | ConverterFactory

The converter for the selector configuration.

Inherited From Configurable.getConverter

getVersion()

An encoded string used to aid in the detection of bot changes on re-deployment.

function getVersion(): string

Returns

string

Unique string which should only change when dialog has changed in a way that should restart the dialog.

Remarks

This defaults to returning the dialogs id but can be overridden to provide more precise change detection logic. Any dialog on the stack that has its version change will result in a versionChanged event will be raised. If this event is not handled by the bot, an error will be thrown resulting in the bots error handler logic being run.

Returning an empty string will disable version tracking for the component all together.

Inherited From Dialog.getVersion

onDialogEvent(DialogContext, DialogEvent)

Called when an event has been raised, using DialogContext.emitEvent(), by either the current dialog or a dialog that the current dialog started.

function onDialogEvent(dc: DialogContext, e: DialogEvent): Promise<boolean>

Parameters

dc

DialogContext

The dialog context for the current turn of conversation.

e

DialogEvent

The event being raised.

Returns

Promise<boolean>

True if the event is handled by the current dialog and bubbling should stop.

Inherited From DialogContainer.onDialogEvent