Microsoft.Bot.Builder.FormFlow Namespace Reference

Core namespace for FormFlow and associated infrastructure. More...

Namespaces

namespace  Advanced
 Namespace for FormFlow advanced building blocks.
 
namespace  Json
 Namespace for FormFlow declaratively defined with JSON Schema.
 

Classes

class  Choice
 Choice for clarifying an ambiguous value in ValidateResult. More...
 
class  CommandDescription
 Description of all the information needed for a built-in command. More...
 
class  DescribeAttribute
 Attribute to override the default description of a field, property or enum value. More...
 
class  FormBuilder
 Build a form by specifying messages, fields and confirmations via reflection or programatically. More...
 
class  FormBuilderBase
 Abstract base class for Form Builders. More...
 
class  FormCanceledException
 Exception generated when form filling is canceled by user quit or exception. More...
 
class  FormConfiguration
 Default values for the form. More...
 
class  FormDialog
 Static factory methods for creating form dialogs. More...
 
class  FormFlowAttribute
 Abstract base class for FormFlow attributes. More...
 
class  IForm
 Form definition interface. More...
 
interface  IFormBuilder
 Interface for building a form. More...
 
interface  IFormDialog
 Interface for controlling a FormFlow dialog. More...
 
class  NumericAttribute
 Provide limits on the possible values in a numeric field or property. More...
 
class  OptionalAttribute
 Define a field or property as optional. More...
 
class  PatternAttribute
 Provide a regular expression to validate a string field. More...
 
class  PromptAttribute
 Define the prompt used when asking about a field. More...
 
class  TemplateAttribute
 Define a template for generating strings. More...
 
class  TermsAttribute
 Attribute to override the default terms used to match a field, property or enum value to user input. More...
 
class  ValidateResult
 Encapsulates the result of a ValidateAsyncDelegate<T> More...
 

Enumerations

enum  BoolDefault { BoolDefault.Default, BoolDefault.True, BoolDefault.False }
 Three state boolean value. More...
 
enum  CaseNormalization {
  CaseNormalization.Default, CaseNormalization.InitialUpper, CaseNormalization.Lower, CaseNormalization.Upper,
  CaseNormalization.None
}
 How to normalize the case of words. More...
 
enum  ChoiceStyleOptions {
  ChoiceStyleOptions.Default, ChoiceStyleOptions.Auto, ChoiceStyleOptions.AutoText, ChoiceStyleOptions.Inline,
  ChoiceStyleOptions.PerLine, ChoiceStyleOptions.InlineNoParen, ChoiceStyleOptions.Buttons, ChoiceStyleOptions.Carousel
}
 Specifies how to show choices generated by {||} in a Pattern Language string. More...
 
enum  FeedbackOptions { FeedbackOptions.Default, FeedbackOptions.Auto, FeedbackOptions.Always, FeedbackOptions.Never }
 Control how the user gets feedback after each entry. More...
 
enum  FormCommand {
  FormCommand.Backup, FormCommand.Help, FormCommand.Quit, FormCommand.Reset,
  FormCommand.Status
}
 Commands supported in form dialogs. More...
 
enum  FormOptions { FormOptions.None, FormOptions.PromptInStart, FormOptions.PromptFieldsWithValues }
 Options for form execution. More...
 
enum  TemplateUsage {
  TemplateUsage.None, TemplateUsage.Bool, TemplateUsage.BoolHelp, TemplateUsage.Clarify,
  TemplateUsage.Confirmation, TemplateUsage.CurrentChoice, TemplateUsage.DateTime, TemplateUsage.DateTimeHelp,
  TemplateUsage.Double, TemplateUsage.DoubleHelp, TemplateUsage.EnumOneNumberHelp, TemplateUsage.EnumManyNumberHelp,
  TemplateUsage.EnumOneWordHelp, TemplateUsage.EnumManyWordHelp, TemplateUsage.EnumSelectOne, TemplateUsage.EnumSelectMany,
  TemplateUsage.Feedback, TemplateUsage.Help, TemplateUsage.HelpClarify, TemplateUsage.HelpConfirm,
  TemplateUsage.HelpNavigation, TemplateUsage.Integer, TemplateUsage.IntegerHelp, TemplateUsage.Navigation,
  TemplateUsage.NavigationCommandHelp, TemplateUsage.NavigationFormat, TemplateUsage.NavigationHelp, TemplateUsage.NoPreference,
  TemplateUsage.NotUnderstood, TemplateUsage.StatusFormat, TemplateUsage.String, TemplateUsage.StringHelp,
  TemplateUsage.Unspecified
}
 All of the built-in templates. More...
 

Functions

delegate bool ActiveDelegate< T > (T state)
 A delegate for testing a form state to see if a particular step is active. More...
 
delegate IForm< T > BuildFormDelegate< T > ()
 Delegate for building the form. More...
 
delegate Task< PromptAttributeMessageDelegate< T > (T state)
 Given state return a PromptAttribute with a template for the message to display. More...
 
delegate Task OnCompletionAsyncDelegate< T > (IDialogContext context, T state)
 A delegate called when a form is completed. More...
 
delegate Task< ValidateResultValidateAsyncDelegate< T > (T state, object value)
 A delegate for validating a particular response to a prompt. More...
 

Detailed Description

Core namespace for FormFlow and associated infrastructure.

If you want to use FormFlow you should use include both the Microsoft.Bot.Builder.Dialogs namespace and this one.

Enumeration Type Documentation

Three state boolean value.

This is necessary because C# attributes do not support nullable properties.

Enumerator
Default 

Use the default from the FormConfiguration.DefaultPrompt.

True 

Boolean true.

False 

Boolean false.

Definition at line 240 of file Attributes.cs.

How to normalize the case of words.

Enumerator
Default 

Use the default from the FormConfiguration.DefaultPrompt.

InitialUpper 

First letter of each word is capitalized

Lower 

Normalize words to lower case.

Upper 

Normalize words to upper case.

None 

Don't normalize words.

Definition at line 205 of file Attributes.cs.

Specifies how to show choices generated by {||} in a Pattern Language string.

Enumerator
Default 

Use the default TemplateBaseAttribute.ChoiceStyle from the FormConfiguration.DefaultPrompt.

Auto 

Automatically choose how to render choices.

AutoText 

Automatically generate text and switch between the Inline and PerLine styles based on the number of choices.

Inline 

Show choices on the same line.

PerLine 

Show choices with one per line.

InlineNoParen 

Show choices on the same line without surrounding parentheses.

Buttons 

Show choices as buttons if possible.

Carousel 

Show choices as a carousel if possibe.

Definition at line 160 of file Attributes.cs.

Control how the user gets feedback after each entry.

Enumerator
Default 

Use the default from the FormConfiguration.DefaultPrompt.

Auto 

Provide feedback using the TemplateUsage.Feedback template only if part of the user input was not understood.

Always 

Provide feedback after every user input.

Never 

Never provide feedback.

Definition at line 261 of file Attributes.cs.

Commands supported in form dialogs.

Enumerator
Backup 

Move back to the previous step.

Help 

Ask for help on responding to the current field.

Quit 

Quit filling in the current form and return failure to parent dialog.

Reset 

Reset the status of the form dialog.

Status 

Provide feedback to the user on the current form state.

Definition at line 146 of file IFormDialog.cs.

Options for form execution.

Enumerator
None 

No options.

PromptInStart 

Prompt when the dialog starts.

PromptFieldsWithValues 

Prompt for fields that already have a value in the initial state when processing form.

Definition at line 92 of file FormDialog.cs.

All of the built-in templates.

A good way to understand these is to look at the default templates defined in FormConfiguration.Templates

Enumerator
None 

An enum constant representing the none option.

Bool 

How to ask for a boolean.

BoolHelp 

What you can enter when entering a bool.

Within this template {0} is the current choice if any and {1} is no preference if optional.

Clarify 

Clarify an ambiguous choice.

This template can use {0} to capture the term that was ambiguous.

Confirmation 

Default confirmation.

CurrentChoice 

Show the current choice.

This is how the current choice is represented as an option. If you change this, you should also change FormConfiguration.CurrentChoice so that what people can type matches what you show.

DateTime 

How to ask for a DateTime.

DateTimeHelp 

What you can enter when entering a DateTime.

Within this template {0} is the current choice if any and {1} is no preference if optional.

This template can use {0} to get the current choice or {1} for no preference if field is optional.

Double 

How to ask for a double.

Within this template if numerical limits are specified using NumericAttribute, {0} is the minimum possible value and {1} is the maximum possible value.

DoubleHelp 

What you can enter when entering a double.

Within this template {0} is the current choice if any and {1} is no preference if optional. If limits are specified through NumericAttribute, then {2} will be the minimum possible value and {3} the maximum possible value.

Within this template, {0} is current choice if any, {1} is no preference for optional and {1} and {2} are min/max if specified.

EnumOneNumberHelp 

What you can enter when selecting a single value from a numbered enumeration.

Within this template, {0} is the minimum choice. {1} is the maximum choice and {2} is a description of all the possible words.

EnumManyNumberHelp 

What you can enter when selecting multiple values from a numbered enumeration.

Within this template, {0} is the minimum choice. {1} is the maximum choice and {2} is a description of all the possible words.

EnumOneWordHelp 

What you can enter when selecting one value from an enumeration.

Within this template, {2} is a list of the possible values.

EnumManyWordHelp 

What you can enter when selecting mutiple values from an enumeration.

Within this template, {2} is a list of the possible values.

EnumSelectOne 

How to ask for one value from an enumeration.

EnumSelectMany 

How to ask for multiple values from an enumeration.

Feedback 

How to show feedback after user input.

Within this template, unmatched input is available through {0}, but it should be wrapped in an optional {?} in Pattern Language in case everything was matched.

Help 

What to display when asked for help.

This template controls the overall help experience. {0} will be recognizer specific help and {1} will be command help.

HelpClarify 

What to display when asked for help while clarifying.

This template controls the overall help experience. {0} will be recognizer specific help and {1} will be command help.

HelpConfirm 

What to display when asked for help while in a confirmation.

This template controls the overall help experience. {0} will be recognizer specific help and {1} will be command help.

HelpNavigation 

What to display when asked for help while navigating.

This template controls the overall help experience. {0} will be recognizer specific help and {1} will be command help.

Integer 

How to ask for an integer.

Within this template if numerical limits are specified using NumericAttribute, {0} is the minimum possible value and {1} is the maximum possible value.

IntegerHelp 

What you can enter while entering an integer.

Within this template, {0} is current choice if any, {1} is no preference for optional and {1} and {2} are min/max if specified.

Navigation 

How to ask for a navigation.

NavigationCommandHelp 

Help pattern for navigation commands.

Within this template, {0} has the list of possible field names.

NavigationFormat 

Navigation format for one line in navigation choices.

NavigationHelp 

What you can enter when navigating.

Within this template, if numeric choies are allowed {0} is the minimum possible choice and {1} the maximum possible choice.

NoPreference 

How to show no preference in an optional field.

NotUnderstood 

Response when an input is not understood.

When no input is matched this template is used and gets {0} for what the user entered.

StatusFormat 

Format for one entry in status.

String 

How to ask for a string.

StringHelp 

What to display when asked for help when entering a string.

Within this template {0} is the current choice if any and {1} is no preference if optional.

Unspecified 

How to represent a value that has not yet been specified.

Definition at line 321 of file Attributes.cs.

Function Documentation

delegate bool Microsoft.Bot.Builder.FormFlow.ActiveDelegate< T > ( state)

A delegate for testing a form state to see if a particular step is active.

Template Parameters
TForm state type.
Parameters
stateForm state to test.
Returns
True if step is active given the current form state.
delegate IForm<T> Microsoft.Bot.Builder.FormFlow.BuildFormDelegate< T > ( )

Delegate for building the form.

Template Parameters
TThe form state type.
Returns
An IForm<T>.

This is a delegate so that we can rebuild the form and don't have to serialize the form definition with every message.

Type Constraints
T :class 
delegate Task<PromptAttribute> Microsoft.Bot.Builder.FormFlow.MessageDelegate< T > ( state)

Given state return a PromptAttribute with a template for the message to display.

Template Parameters
TForm state type.
Parameters
stateForm state.
Returns
A PromptAttribute describing the message to display.
delegate Task Microsoft.Bot.Builder.FormFlow.OnCompletionAsyncDelegate< T > ( IDialogContext  context,
state 
)

A delegate called when a form is completed.

Template Parameters
TForm state type.
Parameters
contextSession where form dialog is taking place.
stateCompleted form state.

This delegate gives an opportunity to take an action on a completed form such as sending it to your service. It cannot be used to create a new dialog or return a value to the parent dialog.

delegate Task<ValidateResult> Microsoft.Bot.Builder.FormFlow.ValidateAsyncDelegate< T > ( state,
object  value 
)

A delegate for validating a particular response to a prompt.

Template Parameters
TForm state type.
Parameters
stateForm state to test.
valueResponse value to validate.
Returns
ValidateResult describing validity, transformed value, feedback or choices for clarification.