ChoicePrompt class

Prompts a user to select from a list of choices.

Extends

Remarks

By default the prompt will return to the calling dialog a FoundChoice object containing the choice that was selected.

Constructors

ChoicePrompt(string, PromptValidator<FoundChoice>, string, ChoiceDefaultsChoicePrompt)

Creates a new ChoicePrompt instance.

Properties

choiceOptions

Additional options passed to the ChoiceFactory and used to tweak the style of choices rendered to the user.

defaultLocale

The prompts default locale that should be recognized.

EndOfTurn

Gets a default end-of-turn result.

id

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

recognizerOptions

Additional options passed to the underlying recognizeChoices() function.

style

Style of the "yes" and "no" choices rendered to the user when prompting.

telemetryClient

Gets the telemetry client for this dialog. Sets the telemetry client for this dialog.

Methods

beginDialog(DialogContext, PromptOptions)

Called when a prompt dialog is pushed onto the dialog stack and is being activated.

configure(Record<string, unknown>)

Fluent method for configuring the object.

continueDialog(DialogContext)

Called when a prompt dialog is the active dialog and the user replied with a new activity.

endDialog(TurnContext, DialogInstance, DialogReason)

When overridden in a derived class, performs clean up for the dialog before it ends.

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.

repromptDialog(TurnContext, DialogInstance)

Called when a prompt dialog has been requested to re-prompt the user for input.

resumeDialog(DialogContext, DialogReason, any)

Called when a prompt dialog resumes being the active dialog on the dialog stack, such as when the previous active dialog on the stack completes.

Constructor Details

ChoicePrompt(string, PromptValidator<FoundChoice>, string, ChoiceDefaultsChoicePrompt)

Creates a new ChoicePrompt instance.

new ChoicePrompt(dialogId: string, validator?: PromptValidator<FoundChoice>, defaultLocale?: string, choiceDefaults?: ChoiceDefaultsChoicePrompt)

Parameters

dialogId

string

Unique ID of the dialog within its parent DialogSet.

validator

PromptValidator<FoundChoice>

(Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent.

defaultLocale

string

(Optional) locale to use if dc.context.activity.locale not specified. Defaults to a value of en-us.

choiceDefaults
ChoiceDefaultsChoicePrompt

(Optional) Overrides the dictionary of Bot Framework SDK-supported _choiceDefaults (for prompt localization). Must be passed in to each ConfirmPrompt that needs the custom choice defaults.

Property Details

choiceOptions

Additional options passed to the ChoiceFactory and used to tweak the style of choices rendered to the user.

choiceOptions: ChoiceFactoryOptions | undefined

Property Value

ChoiceFactoryOptions | undefined

defaultLocale

The prompts default locale that should be recognized.

defaultLocale: string | undefined

Property Value

string | undefined

EndOfTurn

Gets a default end-of-turn result.

static EndOfTurn: DialogTurnResult

Property Value

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.

id

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

string id

Property Value

string

Remarks

This will be automatically generated if not specified.

recognizerOptions

Additional options passed to the underlying recognizeChoices() function.

recognizerOptions: FindChoicesOptions | undefined

Property Value

FindChoicesOptions | undefined

style

Style of the "yes" and "no" choices rendered to the user when prompting.

style: ListStyle

Property Value

Remarks

Defaults to ListStyle.auto.

telemetryClient

Gets the telemetry client for this dialog. Sets the telemetry client for this dialog.

BotTelemetryClient telemetryClient

Property Value

BotTelemetryClient

Method Details

beginDialog(DialogContext, PromptOptions)

Called when a prompt dialog is pushed onto the dialog stack and is being activated.

function beginDialog(dc: DialogContext, options: PromptOptions)

Parameters

dc
DialogContext

The DialogContext for the current turn of the conversation.

options
PromptOptions

Optional. PromptOptions, additional information to pass to the prompt being started.

Returns

Promise<DialogTurnResult>

A Promise representing the asynchronous operation.

Remarks

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

configure(Record<string, unknown>)

Fluent method for configuring the object.

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

Parameters

config

Record<string, unknown>

Configuration settings to apply.

Returns

this

continueDialog(DialogContext)

Called when a prompt dialog is the active dialog and the user replied with a new activity.

function continueDialog(dc: DialogContext)

Parameters

dc
DialogContext

The 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 prompt generally continues to receive the user's replies until it accepts the user's reply as valid input for the prompt.

endDialog(TurnContext, DialogInstance, DialogReason)

When overridden in a derived class, performs clean up for the dialog before it ends.

function endDialog(context: TurnContext, instance: DialogInstance, reason: DialogReason)

Parameters

context

TurnContext

The context object for the turn.

instance
DialogInstance

Current state information for this dialog.

reason
DialogReason

The reason the dialog is ending.

Returns

Promise<void>

Remarks

Derived dialogs that need to perform logging or cleanup before ending should override this method. By default, this method has no effect.

The DialogContext calls this method when the current dialog is ending.

See also

getConverter(string)

function getConverter(_property: string)

Parameters

_property

string

Returns

getVersion()

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

function getVersion()

Returns

string

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.

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)

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.

repromptDialog(TurnContext, DialogInstance)

Called when a prompt dialog has been requested to re-prompt the user for input.

function repromptDialog(context: TurnContext, instance: DialogInstance)

Parameters

context

TurnContext

(xref:botbuilder-core.TurnContext), context for the current turn of conversation with the user.

instance
DialogInstance

(xref:botbuilder-dialogs.DialogInstance), the instance of the dialog on the stack.

Returns

Promise<void>

A Promise representing the asynchronous operation.

resumeDialog(DialogContext, DialogReason, any)

Called when a prompt dialog resumes being the active dialog on the dialog stack, such as when the previous active dialog on the stack completes.

function resumeDialog(dc: DialogContext, reason: DialogReason, result?: any)

Parameters

dc
DialogContext

The DialogContext for the current turn of the conversation.

reason
DialogReason

An enum indicating why the dialog resumed.

result

any

Optional, value returned from the previous dialog on the stack. The type of the value returned is dependent on the previous 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.