DialogContext class

Package:

botbuilder-dialogs

The context for the current dialog turn with respect to a specific DialogSet.

Remarks

This includes the turn context, information about the dialog set, and the state of the dialog stack.

From code outside of a dialog in the set, use DialogSet.createContext to create the dialog context. Then use the methods of the dialog context to manage the progression of dialogs in the set.

When you implement a dialog, the dialog context is a parameter available to the various methods you override or implement.

For example:

const dc = await dialogs.createContext(turnContext);
const result = await dc.continueDialog();

Constructors

DialogContext(DialogSet, DialogContext, DialogState)	Creates an new instance of the DialogContext class.
DialogContext(DialogSet, TurnContext, DialogState)	Creates an new instance of the DialogContext class.

Properties

activeDialog
child
context	Gets the context object for the turn.
dialogManager
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

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

DialogContext(DialogSet, DialogContext, DialogState)

Creates an new instance of the DialogContext class.

new DialogContext(dialogs: DialogSet, contextOrDC: DialogContext, state: DialogState)

Parameters

dialogs

DialogSet

The DialogSet for which to create the dialog context.

contextOrDC

DialogContext

The TurnContext object for the current turn of the bot.

state

DialogState

The state object to use to read and write DialogState to storage.

Remarks

Passing in a DialogContext instance will clone the dialog context.

DialogContext(DialogSet, TurnContext, DialogState)

Creates an new instance of the DialogContext class.

new DialogContext(dialogs: DialogSet, contextOrDC: TurnContext, state: DialogState)

Parameters

dialogs

DialogSet

The DialogSet for which to create the dialog context.

contextOrDC

TurnContext

The TurnContext object for the current turn of the bot.

state

DialogState

The state object to use to read and write DialogState to storage.

Remarks

Passing in a DialogContext instance will clone the dialog context.

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.

context

Gets the context object for the turn.

context: TurnContext

Property Value

TurnContext

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.

dialogs

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

dialogs: DialogSet

Property Value

DialogSet

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.

services

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

services: TurnContextStateCollection

Property Value

TurnContextStateCollection

stack

Gets the current dialog stack.

stack: DialogInstance[]

Property Value

DialogInstance[]

state

Gets the DialogStateManager which manages view of all memory scopes.

state: DialogStateManager

Property Value

DialogStateManager

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

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

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

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.

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

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

getLocale()

Obtain the CultureInfo in DialogContext.

function getLocale(): string

Returns

string

a locale string.

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

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

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

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