WaterfallStepContext class

Package:

botbuilder-dialogs

Context object passed in to a WaterfallStep.

Extends

DialogContext

Constructors

WaterfallStepContext(DialogContext, WaterfallStepInfo<O>)

Creates a new WaterfallStepContext instance.

Properties

activeDialog
child
dialogManager
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().
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.
values	A dictionary of values which will be persisted across all waterfall steps.

Inherited Properties

context	Gets the context object for the turn.
dialogs	Gets the dialogs that can be called directly from this context.
parent	The parent dialog context for this dialog context, or undefined if this context doesn't have a parent.
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.

Methods

next(any)

Skips to the next waterfall step.

Inherited 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.
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

DialogInstance | undefined activeDialog

Property Value

DialogInstance | undefined

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

child

DialogContext | undefined child

Property Value

DialogContext | undefined

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

dialogManager

Warning

This API is now deprecated.

This property serves no function.

DialogManager dialogManager

Property Value

DialogManager

The current dialog manager instance. This property is deprecated.

index

The index of the current waterfall step being executed.

number index

Property Value

number

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().

O options

Property Value

O

Any options the waterfall dialog was called with.

reason

The reason the waterfall step is being executed.

DialogReason reason

Property Value

DialogReason

The reason the waterfall step is being executed.

result

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

any result

Property Value

any

The result from the previous waterfall step.

values

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

object values

Property Value

object

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

Inherited Property Details

context

Gets the context object for the turn.

context: TurnContext

Property Value

TurnContext

Inherited From DialogContext.context

dialogs

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

dialogs: DialogSet

Property Value

DialogSet

Inherited From DialogContext.dialogs

parent

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

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.

Inherited From DialogContext.parent

services

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

services: TurnContextStateCollection

Property Value

TurnContextStateCollection

Inherited From DialogContext.services

stack

Gets the current dialog stack.

stack: DialogInstance[]

Property Value

DialogInstance[]

Inherited From DialogContext.stack

state

Gets the DialogStateManager which manages view of all memory scopes.

state: DialogStateManager

Property Value

DialogStateManager

Inherited From DialogContext.state

Method Details

next(any)

Skips to the next waterfall step.

function next(result?: any): Promise<DialogTurnResult>

Parameters

result

any

(Optional) result to pass to the next step.

Returns

Promise<DialogTurnResult>

A promise with the DialogTurnResult.

Remarks

return await step.skip();

Inherited 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): Promise<DialogTurnResult>

Parameters

dialogId

string

ID of the dialog to start.

options

object

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

Returns

Promise<DialogTurnResult>

a promise resolving to the dialog turn result.

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

• endDialog
• prompt
• replaceDialog
• Dialog.beginDialog

Inherited From DialogContext.beginDialog

cancelAllDialogs(boolean, string, any)

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

function cancelAllDialogs(cancelParents?: boolean, eventName?: string, eventValue?: any): Promise<DialogTurnResult>

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>

a promise resolving to the dialog turn result.

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

• endDialog

Inherited From DialogContext.cancelAllDialogs

continueDialog()

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

function continueDialog(): Promise<DialogTurnResult>

Returns

Promise<DialogTurnResult>

a promise resolving to the dialog turn result.

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.`);
}

Inherited From DialogContext.continueDialog

emitEvent(string, any, boolean, boolean)

Searches for a dialog with a given ID.

function emitEvent(name: string, value?: any, bubble?: boolean, fromLeaf?: boolean): Promise<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.

Inherited From DialogContext.emitEvent

endDialog(any)

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

function endDialog(result?: any): Promise<DialogTurnResult>

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>

a promise resolving to the dialog turn result.

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

• beginDialog
• replaceDialog
• Dialog.endDialog

Inherited From DialogContext.endDialog

findDialog(string)

Searches for a dialog with a given ID.

function findDialog(dialogId: string): Dialog | undefined

Parameters

dialogId

string

ID of the dialog to search for.

Returns

Dialog | undefined

The dialog for the provided ID.

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

• dialogs
• parent

Inherited From DialogContext.findDialog

getLocale()

Obtain the CultureInfo in DialogContext.

function getLocale(): string

Returns

string

a locale string.

Inherited From DialogContext.getLocale

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): Promise<DialogTurnResult>

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, the activity to send as the initial prompt, or the object with which to format the prompt dialog.

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?`);

Inherited From DialogContext.prompt

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[]): Promise<DialogTurnResult>

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, the Activity to send as the initial prompt, or the object with which to format the prompt dialog.

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?`);

Inherited From DialogContext.prompt

replaceDialog(string, object)

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

function replaceDialog(dialogId: string, options?: object): Promise<DialogTurnResult>

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>

a promise resolving to the dialog turn result.

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

• beginDialog
• endDialog

Inherited From DialogContext.replaceDialog

repromptDialog()

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

function repromptDialog(): Promise<void>

Returns

Promise<void>

Remarks

This calls the active dialog's repromptDialog method.

For example:

await dc.repromptDialog();

Inherited From DialogContext.repromptDialog