DialogContext class
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 method 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.
Constructors
| Dialog |
Creates an new instance of the DialogContext class. |
| Dialog |
Creates an new instance of the DialogContext class. |
Properties
| active |
|
| child | |
| context | Gets the context object for the turn. |
| dialog |
|
| dialogs | Gets the dialogs that can be called directly from this context. |
| parent | The parent dialog context for this dialog context, or |
| 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
| begin |
Starts a dialog instance and pushes it onto the dialog stack. Creates a new instance of the dialog and pushes it onto the stack. |
| cancel |
Cancels all dialogs on the dialog stack, and clears stack. |
| continue |
Continues execution of the active dialog, if there is one, by passing this dialog context to its continueDialog method. |
| emit |
Searches for a dialog with a given ID. |
| end |
Ends a dialog and pops it off the stack. Returns an optional result to the dialog's parent. |
| find |
Searches for a dialog with a given ID. |
| get |
Obtain the CultureInfo in DialogContext. |
| prompt(string, string | Partial<Activity> | Prompt |
Helper function to simplify formatting the options for calling a prompt dialog. |
| prompt(string, string | Partial<Activity> | Prompt |
Helper function to simplify formatting the options for calling a prompt dialog. |
| replace |
Ends the active dialog and starts a new dialog in its place. |
| reprompt |
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, contextOrDialogContext: DialogContext, state: DialogState)Parameters
- dialogs
- DialogSet
The DialogSet for which to create the dialog context.
- contextOrDialogContext
- DialogContext
The DialogContext object for the current turn.
- 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, contextOrDialogContext: TurnContext, state: DialogState)Parameters
- dialogs
- DialogSet
The DialogSet for which to create the dialog context.
- contextOrDialogContext
- TurnContext
The TurnContext object for the current turn.
- 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
undefined | DialogInstance<any> activeDialogProperty Value
undefined | DialogInstance<any>
The state information for the dialog on the top of the dialog stack, or undefined if
the stack is empty.
child
undefined | DialogContext childProperty Value
undefined | DialogContext
Dialog context for child if the active dialog is a container.
context
dialogManager
dialogs
Gets the dialogs that can be called directly from this context.
dialogs: DialogSetProperty Value
parent
The parent dialog context for this dialog context, or undefined if this context doesn't have a parent.
parent: undefined | DialogContextProperty Value
undefined | DialogContext
Remarks
When it attempts to start a dialog, the dialog context searches for the 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: TurnContextStateCollectionProperty Value
stack
state
Gets the DialogStateManager which manages view of all memory scopes.
state: DialogStateManagerProperty Value
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<any>>Parameters
- dialogId
-
string
ID of the dialog to start.
- options
-
object
Optional. Arguments to pass into the dialog when it starts.
Returns
Promise<DialogTurnResult<any>>
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.
cancelAllDialogs(boolean, string, any)
Cancels all dialogs on the dialog stack, and clears stack.
function cancelAllDialogs(cancelParents?: boolean, eventName?: string, eventValue?: any): Promise<DialogTurnResult<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 DialogEvents.cancelDialog.
- eventValue
-
any
Optional. Value to pass along with custom cancellation event.
Returns
Promise<DialogTurnResult<any>>
a promise resolving to the dialog turn result.
Remarks
This calls each dialog's endDialog method before removing the dialog from the stack.
If there were any dialogs on the stack initially, the DialogTurnResult.status of the return value is cancelled; otherwise, it's empty.
continueDialog()
Continues execution of the active dialog, if there is one, by passing this dialog context to its continueDialog method.
function continueDialog(): Promise<DialogTurnResult<any>>Returns
Promise<DialogTurnResult<any>>
a promise resolving to the dialog turn result.
Remarks
After the call completes, you can check the turn context's | TurnContext.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 agent's turn handler.
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<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 agent's turn handler.
Returns
Promise<DialogTurnResult<any>>
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 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 agent 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.
findDialog(string)
Searches for a dialog with a given ID.
function findDialog(dialogId: string): undefined | Dialog<{}>Parameters
- dialogId
-
string
ID of the dialog to search for.
Returns
undefined | Dialog<{}>
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.
getLocale()
Obtain the CultureInfo in DialogContext.
function getLocale(): stringReturns
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<any>>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<any>>
Remarks
This helper method formats the object to use as the options parameter, and then calls
beginDialog to start the specified prompt dialog.
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<any>>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<any>>
Remarks
This helper method formats the object to use as the options parameter, and then calls
beginDialog to start the specified prompt dialog.
replaceDialog(string, object)
Ends the active dialog and starts a new dialog in its place.
function replaceDialog(dialogId: string, options?: object): Promise<DialogTurnResult<any>>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<any>>
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.
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.