WaterfallStepContext class

Context object passed in to a WaterfallStep.

Extends

Constructors

WaterfallStepContext(DialogContext, WaterfallStepInfo<O>)

Creates a new WaterfallStepContext instance.

Properties

activeDialog

Returns the state information for the dialog on the top of the dialog stack, or undefined if the stack is empty.

child

Returns dialog context for child if the active dialog is a container.

context

Gets the context object for the turn.

dialogManager

Returns the current dialog manager instance.

dialogs

Gets the dialogs that can be called directly from this context.

index

The index of the current waterfall step being executed.

options

Any options passed to the steps waterfall dialog when it was started with DialogContext.beginDialog().

parent

The parent dialog context for this dialog context, or undefined if this context doesn't have a parent.

reason

The reason the waterfall step is being executed.

result

Results returned by a dialog or prompt that was called in the previous waterfall step.

services

Gets the services collection which is contextual to this dialog context.

stack

Gets the current dialog stack.

state

Gets the DialogStateManager which manages view of all memory scopes.

values

A dictionary of values which will be persisted across all waterfall steps.

Methods

beginDialog(string, object)

Starts a dialog instance and pushes it onto the dialog stack. Creates a new instance of the dialog and pushes it onto the stack.

cancelAllDialogs(boolean, string, any)

Cancels all dialogs on the dialog stack, and clears stack.

continueDialog()

Continues execution of the active dialog, if there is one, by passing this dialog context to its Dialog.continueDialog method.

emitEvent(string, any, boolean, boolean)

Searches for a dialog with a given ID.

endDialog(any)

Ends a dialog and pops it off the stack. Returns an optional result to the dialog's parent.

findDialog(string)

Searches for a dialog with a given ID.

getLocale()

Obtain the CultureInfo in DialogContext.

next(any)

Skips to the next waterfall step.

prompt(string, string | Partial<Activity> | PromptOptions)

Helper function to simplify formatting the options for calling a prompt dialog.

prompt(string, string | Partial<Activity> | PromptOptions, string | Choice[])

Helper function to simplify formatting the options for calling a prompt dialog.

replaceDialog(string, object)

Ends the active dialog and starts a new dialog in its place.

repromptDialog()

Requests the active dialog to re-prompt the user for input.

Constructor Details

WaterfallStepContext(DialogContext, WaterfallStepInfo<O>)

Creates a new WaterfallStepContext instance.

new WaterfallStepContext(dc: DialogContext, info: WaterfallStepInfo<O>)

Parameters

dc
DialogContext

The dialog context for the current turn of conversation.

info

WaterfallStepInfo<O>

Values to initialize the step context with.

Property Details

activeDialog

Returns the state information for the dialog on the top of the dialog stack, or undefined if the stack is empty.

DialogInstance | undefined activeDialog

Property Value

DialogInstance | undefined

child

Returns dialog context for child if the active dialog is a container.

DialogContext | undefined child

Property Value

DialogContext | undefined

context

Gets the context object for the turn.

public context: TurnContext

Property Value

TurnContext

dialogManager

Returns the current dialog manager instance.

DialogManager dialogManager

Property Value

dialogs

Gets the dialogs that can be called directly from this context.

public dialogs: DialogSet

Property Value

index

The index of the current waterfall step being executed.

number index

Property Value

number

options

Any options passed to the steps waterfall dialog when it was started with DialogContext.beginDialog().

O options

Property Value

O

parent

The parent dialog context for this dialog context, or undefined if this context doesn't have a parent.

public parent: DialogContext | undefined

Property Value

DialogContext | undefined

Remarks

When it attempts to start a dialog, the dialog context searches for the Dialog.id in its dialogs. If the dialog to start is not found in this dialog context, it searches in its parent dialog context, and so on.

reason

The reason the waterfall step is being executed.

DialogReason reason

Property Value

result

Results returned by a dialog or prompt that was called in the previous waterfall step.

any result

Property Value

any

services

Gets the services collection which is contextual to this dialog context.

public services: TurnContextStateCollection = new TurnContextStateCollection()

Property Value

TurnContextStateCollection

stack

Gets the current dialog stack.

public stack: DialogInstance[]

Property Value

state

Gets the DialogStateManager which manages view of all memory scopes.

public state: DialogStateManager

Property Value

values

A dictionary of values which will be persisted across all waterfall steps.

object values

Property Value

object

Method Details

beginDialog(string, object)

Starts a dialog instance and pushes it onto the dialog stack. Creates a new instance of the dialog and pushes it onto the stack.

function beginDialog(dialogId: string, options?: object)

Parameters

dialogId

string

ID of the dialog to start.

options

object

Optional. Arguments to pass into the dialog when it starts.

Returns

Promise<DialogTurnResult>

Remarks

If there's already an active dialog on the stack, that dialog will be paused until it is again the top dialog on the stack.

The status of returned object describes the status of the dialog stack after this method completes.

This method throws an exception if the requested dialog can't be found in this dialog context or any of its ancestors.

For example:

const result = await dc.beginDialog('greeting', { name: user.name });

See also

cancelAllDialogs(boolean, string, any)

Cancels all dialogs on the dialog stack, and clears stack.

function cancelAllDialogs(cancelParents: boolean, eventName?: string, eventValue?: any)

Parameters

cancelParents

boolean

Optional. If true all parent dialogs will be cancelled as well.

eventName

string

Optional. Name of a custom event to raise as dialogs are cancelled. This defaults to cancelDialog.

eventValue

any

Optional. Value to pass along with custom cancellation event.

Returns

Promise<DialogTurnResult>

Remarks

This calls each dialog's Dialog.endDialog method before removing the dialog from the stack.

If there were any dialogs on the stack initially, the status of the return value is cancelled; otherwise, it's empty.

This example clears a dialog stack, dc, before starting a 'bookFlight' dialog.

await dc.cancelAllDialogs();
return await dc.beginDialog('bookFlight');

See also

continueDialog()

Continues execution of the active dialog, if there is one, by passing this dialog context to its Dialog.continueDialog method.

function continueDialog()

Returns

Promise<DialogTurnResult>

Remarks

After the call completes, you can check the turn context's responded property to determine if the dialog sent a reply to the user.

The status of returned object describes the status of the dialog stack after this method completes.

Typically, you would call this from within your bot's turn handler.

For example:

const result = await dc.continueDialog();
if (result.status == DialogTurnStatus.empty && dc.context.activity.type == ActivityTypes.message) {
    // Send fallback message
    await dc.context.sendActivity(`I'm sorry. I didn't understand.`);
}

emitEvent(string, any, boolean, boolean)

Searches for a dialog with a given ID.

function emitEvent(name: string, value?: any, bubble: boolean, fromLeaf: boolean)

Parameters

name

string

Name of the event to raise.

value

any

Optional. Value to send along with the event.

bubble

boolean

Optional. Flag to control whether the event should be bubbled to its parent if not handled locally. Defaults to a value of true.

fromLeaf

boolean

Optional. Whether the event is emitted from a leaf node.

Returns

Promise<boolean>

true if the event was handled.

Remarks

Emits a named event for the current dialog, or someone who started it, to handle.

endDialog(any)

Ends a dialog and pops it off the stack. Returns an optional result to the dialog's parent.

function endDialog(result?: any)

Parameters

result

any

Optional. A result to pass to the parent logic. This might be the next dialog on the stack, or if this was the last dialog on the stack, a parent dialog context or the bot's turn handler.

Returns

Promise<DialogTurnResult>

Remarks

The parent dialog is the next dialog on the dialog stack, if there is one. This method calls the parent's Dialog.resumeDialog method, passing the result returned by the ending dialog. If there is no parent dialog, the turn ends and the result is available to the bot through the returned object's result property.

The status of returned object describes the status of the dialog stack after this method completes.

Typically, you would call this from within the logic for a specific dialog to signal back to the dialog context that the dialog has completed, the dialog should be removed from the stack, and the parent dialog should resume.

For example:

return await dc.endDialog(returnValue);

See also

findDialog(string)

Searches for a dialog with a given ID.

function findDialog(dialogId: string)

Parameters

dialogId

string

ID of the dialog to search for.

Returns

Dialog | undefined

Remarks

If the dialog to start is not found in the DialogSet associated with this dialog context, it attempts to find the dialog in its parent dialog context.

See also

getLocale()

Obtain the CultureInfo in DialogContext.

function getLocale()

Returns

string

a locale string.

next(any)

Skips to the next waterfall step.

function next(result?: any)

Parameters

result

any

(Optional) result to pass to the next step.

Returns

Promise<DialogTurnResult>

Remarks

return await step.skip();

prompt(string, string | Partial<Activity> | PromptOptions)

Helper function to simplify formatting the options for calling a prompt dialog.

function prompt(dialogId: string, promptOrOptions: string | Partial<Activity> | PromptOptions)

Parameters

dialogId

string

ID of the prompt dialog to start.

promptOrOptions

string | Partial<Activity> | PromptOptions

The text of the initial prompt to send the user, or the Activity to send as the initial prompt.

Returns

Promise<DialogTurnResult>

Remarks

This helper method formats the object to use as the options parameter, and then calls beginDialog to start the specified prompt dialog.

return await dc.prompt('confirmPrompt', `Are you sure you'd like to quit?`);

prompt(string, string | Partial<Activity> | PromptOptions, string | Choice[])

Helper function to simplify formatting the options for calling a prompt dialog.

function prompt(dialogId: string, promptOrOptions: string | Partial<Activity> | PromptOptions, choices: string | Choice[])

Parameters

dialogId

string

ID of the prompt dialog to start.

promptOrOptions

string | Partial<Activity> | PromptOptions

The text of the initial prompt to send the user, or the Activity to send as the initial prompt.

choices

string | Choice[]

Optional. Array of choices for the user to choose from, for use with a ChoicePrompt.

Returns

Promise<DialogTurnResult>

Remarks

This helper method formats the object to use as the options parameter, and then calls beginDialog to start the specified prompt dialog.

return await dc.prompt('confirmPrompt', `Are you sure you'd like to quit?`);

replaceDialog(string, object)

Ends the active dialog and starts a new dialog in its place.

function replaceDialog(dialogId: string, options?: object)

Parameters

dialogId

string

ID of the dialog to start.

options

object

Optional. Arguments to pass into the new dialog when it starts.

Returns

Promise<DialogTurnResult>

Remarks

This is particularly useful for creating a loop or redirecting to another dialog.

The status of returned object describes the status of the dialog stack after this method completes.

This method is similar to ending the current dialog and immediately beginning the new one. However, the parent dialog is neither resumed nor otherwise notified.

See also

repromptDialog()

Requests the active dialog to re-prompt the user for input.

function repromptDialog()

Returns

Promise<void>

Remarks

This calls the active dialog's repromptDialog method.

For example:

await dc.repromptDialog();