Attributes.cs
1 //
2 // Copyright (c) Microsoft. All rights reserved.
3 // Licensed under the MIT license.
4 //
5 // Microsoft Bot Framework: http://botframework.com
6 //
7 // Bot Builder SDK GitHub:
8 // https://github.com/Microsoft/BotBuilder
9 //
10 // Copyright (c) Microsoft Corporation
11 // All rights reserved.
12 //
13 // MIT License:
14 // Permission is hereby granted, free of charge, to any person obtaining
15 // a copy of this software and associated documentation files (the
16 // "Software"), to deal in the Software without restriction, including
17 // without limitation the rights to use, copy, modify, merge, publish,
18 // distribute, sublicense, and/or sell copies of the Software, and to
19 // permit persons to whom the Software is furnished to do so, subject to
20 // the following conditions:
21 //
22 // The above copyright notice and this permission notice shall be
23 // included in all copies or substantial portions of the Software.
24 //
25 // THE SOFTWARE IS PROVIDED ""AS IS"", WITHOUT WARRANTY OF ANY KIND,
26 // EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
27 // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
28 // NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
29 // LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
30 // OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
31 // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
32 //
33 
34 using System;
35 using System.Linq;
36 
38 
39 namespace Microsoft.Bot.Builder.FormFlow
40 {
44  [Serializable]
45  public abstract class FormFlowAttribute : Attribute
46  {
54  public bool IsLocalizable { get; set; } = true;
55  }
56 
60  [Serializable]
61  [AttributeUsage(AttributeTargets.Field | AttributeTargets.Enum | AttributeTargets.Property)]
63  {
67  public string Description;
68 
72  public string Title;
73 
77  public string SubTitle;
78 
82  public string Image;
83 
87  public string Message;
88 
97  public DescribeAttribute(string description = null, string image = null, string message = null, string title = null, string subTitle = null)
98  {
99  Description = description;
100  Title = title;
101  SubTitle = subTitle;
102  Image = image;
103  Message = message;
104  }
105  }
106 
117  [Serializable]
118  [AttributeUsage(AttributeTargets.Field | AttributeTargets.Property)]
120  {
124  public string[] Alternatives;
125 
126  private int _maxPhrase;
130  public int MaxPhrase
131  {
132  get
133  {
134  return _maxPhrase;
135  }
136  set
137  {
138  _maxPhrase = value;
139  Alternatives = Alternatives.SelectMany(alt => Advanced.Language.GenerateTerms(alt, _maxPhrase)).ToArray();
140  }
141  }
142 
151  public TermsAttribute(params string[] alternatives)
152  {
153  Alternatives = alternatives;
154  }
155  }
156 
160  public enum ChoiceStyleOptions
161  {
165  Default,
166 
170  Auto,
171 
175  AutoText,
176 
180  Inline,
181 
185  PerLine,
186 
189 
193  Buttons,
194 
198  Carousel
199  };
200 
201 
205  public enum CaseNormalization
206  {
207 
211  Default,
212 
216  InitialUpper,
217 
221  Lower,
222 
226  Upper,
227 
231  None
232  };
233 
240  public enum BoolDefault
241  {
245  Default,
246 
250  True,
251 
255  False
256  };
257 
261  public enum FeedbackOptions
262  {
266  Default,
267 
271  Auto,
272 
276  Always,
277 
281  Never
282  };
283 
292  [Serializable]
293  [AttributeUsage(AttributeTargets.Field | AttributeTargets.Property)]
295  {
300  public PromptAttribute(params string[] patterns)
301  : base(patterns)
302  { }
303 
309  : base(pattern)
310  {
311  IsLocalizable = false;
312  }
313  }
314 
321  public enum TemplateUsage
322  {
324  None,
325 
329  Bool,
330 
337  BoolHelp,
338 
343  Clarify,
344 
348  Confirmation,
349 
359 
363  DateTime,
364 
374  DateTimeHelp,
375 
383  Double,
384 
396  DoubleHelp,
397 
405 
413 
421 
429 
434 
439 
446  Feedback,
447 
454  Help,
455 
462  HelpClarify,
463 
470  HelpConfirm,
471 
479 
487  Integer,
488 
495  IntegerHelp,
496 
500  Navigation,
501 
509 
514 
523 
527  NoPreference,
528 
536 
540  StatusFormat,
541 
545  String,
546 
553  StringHelp,
554 
559  };
560 
569  [Serializable]
570  [AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct | AttributeTargets.Field | AttributeTargets.Property, AllowMultiple = true)]
572  {
576  public readonly TemplateUsage Usage;
577 
583  public TemplateAttribute(TemplateUsage usage, params string[] patterns)
584  : base(patterns)
585  {
586  Usage = usage;
587  }
588 
589  #region Documentation
590  #endregion
594  : base(other)
595  {
596  Usage = other.Usage;
597  }
598  }
599 
606  [Serializable]
607  [AttributeUsage(AttributeTargets.Field | AttributeTargets.Property)]
608  public class OptionalAttribute : Attribute
609  {
614  { }
615  }
616 
623  [Serializable]
624  [AttributeUsage(AttributeTargets.Field | AttributeTargets.Property)]
625  public class NumericAttribute : Attribute
626  {
630  public readonly double Min;
631 
635  public readonly double Max;
636 
642  public NumericAttribute(double min, double max)
643  {
644  Min = min;
645  Max = max;
646  }
647  }
648 
655  [Serializable]
656  [AttributeUsage(AttributeTargets.Field | AttributeTargets.Property)]
657  public class PatternAttribute : Attribute
658  {
659  public readonly string Pattern;
660 
665  public PatternAttribute(string pattern)
666  {
667  Pattern = pattern;
668  }
669  }
670 }
671 
672 namespace Microsoft.Bot.Builder.FormFlow.Advanced
673 {
677  public abstract class TemplateBaseAttribute : FormFlowAttribute
678  {
679  private static Random _generator = new Random();
680 
684  public BoolDefault AllowDefault { get; set; }
685 
689  public CaseNormalization ChoiceCase { get; set; }
690 
695  public string ChoiceFormat { get; set; }
696 
700  public string ChoiceLastSeparator { get; set; }
701 
705  public BoolDefault ChoiceParens { get; set; }
706 
710  public string ChoiceSeparator { get; set; }
711 
715  public ChoiceStyleOptions ChoiceStyle { get; set; }
716 
720  public FeedbackOptions Feedback { get; set; }
721 
725  public CaseNormalization FieldCase { get; set; }
726 
730  public string LastSeparator { get; set; }
731 
735  public string Separator { get; set; }
736 
740  public CaseNormalization ValueCase { get; set; }
741 
742  internal bool AllowNumbers
743  {
744  get
745  {
746  // You can match on numbers only if they are included in Choices and choices are shown
747  return ChoiceFormat.Contains("{0}") && Patterns.Any((pattern) => pattern.Contains("{||}"));
748  }
749  }
750 
756  public string Pattern()
757  {
758  var choice = 0;
759  if (Patterns.Length > 1)
760  {
761  lock (_generator)
762  {
763  choice = _generator.Next(Patterns.Length);
764  }
765  }
766  return Patterns[choice];
767  }
768 
773  public string[] Patterns { get; set; }
774 
779  public void ApplyDefaults(TemplateBaseAttribute defaultTemplate)
780  {
781  if (AllowDefault == BoolDefault.Default) AllowDefault = defaultTemplate.AllowDefault;
782  if (ChoiceCase == CaseNormalization.Default) ChoiceCase = defaultTemplate.ChoiceCase;
783  if (ChoiceFormat == null) ChoiceFormat = defaultTemplate.ChoiceFormat;
784  if (ChoiceLastSeparator == null) ChoiceLastSeparator = defaultTemplate.ChoiceLastSeparator;
785  if (ChoiceParens == BoolDefault.Default) ChoiceParens = defaultTemplate.ChoiceParens;
786  if (ChoiceSeparator == null) ChoiceSeparator = defaultTemplate.ChoiceSeparator;
787  if (ChoiceStyle == ChoiceStyleOptions.Default) ChoiceStyle = defaultTemplate.ChoiceStyle;
788  if (FieldCase == CaseNormalization.Default) FieldCase = defaultTemplate.FieldCase;
789  if (Feedback == FeedbackOptions.Default) Feedback = defaultTemplate.Feedback;
790  if (LastSeparator == null) LastSeparator = defaultTemplate.LastSeparator;
791  if (Separator == null) Separator = defaultTemplate.Separator;
792  if (ValueCase == CaseNormalization.Default) ValueCase = defaultTemplate.ValueCase;
793  }
794 
799  public TemplateBaseAttribute(params string[] patterns)
800  {
801  Patterns = patterns;
802  Initialize();
803  }
804 
810  {
811  Patterns = other.Patterns;
812  AllowDefault = other.AllowDefault;
813  ChoiceCase = other.ChoiceCase;
814  ChoiceFormat = other.ChoiceFormat;
815  ChoiceLastSeparator = other.ChoiceLastSeparator;
816  ChoiceParens = other.ChoiceParens;
817  ChoiceSeparator = other.ChoiceSeparator;
818  ChoiceStyle = other.ChoiceStyle;
819  FieldCase = other.FieldCase;
820  Feedback = other.Feedback;
821  LastSeparator = other.LastSeparator;
822  Separator = other.Separator;
823  ValueCase = other.ValueCase;
824  }
825 
826  private void Initialize()
827  {
828  AllowDefault = BoolDefault.Default;
829  ChoiceCase = CaseNormalization.Default;
830  ChoiceFormat = null;
831  ChoiceLastSeparator = null;
832  ChoiceParens = BoolDefault.Default;
833  ChoiceSeparator = null;
834  ChoiceStyle = ChoiceStyleOptions.Default;
835  FieldCase = CaseNormalization.Default;
836  Feedback = FeedbackOptions.Default;
837  LastSeparator = null;
838  Separator = null;
839  ValueCase = CaseNormalization.Default;
840  }
841  }
842 }
Core namespace for FormFlow and associated infrastructure.
Definition: Attributes.cs:39
string LastSeparator
When constructing lists using {[]} in a Pattern Language string, the string used before the last valu...
Definition: Attributes.cs:730
PatternAttribute(string pattern)
Regular expression for validating the content of a string field.
Definition: Attributes.cs:665
readonly double Max
Max possible value.
Definition: Attributes.cs:635
How to show no preference in an optional field.
CaseNormalization ValueCase
Control case when showing {} value references in a Pattern Language string.
Definition: Attributes.cs:740
FeedbackOptions Feedback
Control what kind of feedback the user gets after each input.
Definition: Attributes.cs:720
Define a template for generating strings.
Definition: Attributes.cs:571
How to show feedback after user input.
DescribeAttribute(string description=null, string image=null, string message=null, string title=null, string subTitle=null)
Description for field, property or enum value.
Definition: Attributes.cs:97
BoolDefault ChoiceParens
When constructing inline choice lists for {||} in a Pattern Language string controls whether to inclu...
Definition: Attributes.cs:705
void ApplyDefaults(TemplateBaseAttribute defaultTemplate)
Any default values in this template will be overridden by the supplied defaultTemplate ...
Definition: Attributes.cs:779
Define the prompt used when asking about a field.
Definition: Attributes.cs:294
readonly double Min
Min possible value.
Definition: Attributes.cs:630
string SubTitle
SubTitle when a card is generated from description.
Definition: Attributes.cs:77
TemplateAttribute(TemplateUsage usage, params string[] patterns)
Specify a set of templates to randomly choose between for a particular usage.
Definition: Attributes.cs:583
TemplateUsage
All of the built-in templates.
Definition: Attributes.cs:321
string ChoiceFormat
Format string used for presenting each choice when showing {||} choices in a Pattern Language string...
Definition: Attributes.cs:695
string Image
URL of image to use when creating cards or buttons.
Definition: Attributes.cs:82
What to display when asked for help.
readonly TemplateUsage Usage
What kind of template this is.
Definition: Attributes.cs:576
What to display when asked for help while navigating.
What you can enter when selecting multiple values from a numbered enumeration.
TemplateBaseAttribute(TemplateBaseAttribute other)
Initialize from another template.
Definition: Attributes.cs:809
Provide limits on the possible values in a numeric field or property.
Definition: Attributes.cs:625
FeedbackOptions
Control how the user gets feedback after each entry.
Definition: Attributes.cs:261
ChoiceStyleOptions
Specifies how to show choices generated by {||} in a Pattern Language string.
Definition: Attributes.cs:160
TemplateBaseAttribute(params string[] patterns)
Initialize with multiple patterns that will be chosen from randomly.
Definition: Attributes.cs:799
What you can enter when entering a DateTime.
Attribute to override the default terms used to match a field, property or enum value to user input...
Definition: Attributes.cs:119
string ChoiceLastSeparator
When constructing inline lists of choices using {||} in a Pattern Language string, the string used before the last choice.
Definition: Attributes.cs:700
string ChoiceSeparator
When constructing inline lists using {||} in a Pattern Language string, the string used between all c...
Definition: Attributes.cs:710
ChoiceStyleOptions ChoiceStyle
How to display choices {||} when processed in a Pattern Language string.
Definition: Attributes.cs:715
What you can enter when entering a bool.
string Pattern()
The pattern to use when generating a string using Advanced.IPrompt<T>.
Definition: Attributes.cs:756
BoolDefault
Three state boolean value.
Definition: Attributes.cs:240
Response when an input is not understood.
string Message
Message to return when a button is pressed in a card.
Definition: Attributes.cs:87
Namespace for FormFlow advanced building blocks.
Definition: Attributes.cs:672
PromptAttribute(params string[] patterns)
Define a prompt with one or more Pattern Language patterns to choose from randomly.
Definition: Attributes.cs:300
CaseNormalization
How to normalize the case of words.
Definition: Attributes.cs:205
string Separator
When constructing lists using {[]} in a Pattern Language string, the string used between all values e...
Definition: Attributes.cs:735
Abstract base class used by all attributes that use Pattern Language.
Definition: Attributes.cs:677
What you can enter when selecting mutiple values from an enumeration.
Provide feedback after every user input.
What to display when asked for help while in a confirmation.
Show choices on the same line without surrounding parentheses.
How to ask for multiple values from an enumeration.
TemplateAttribute(TemplateAttribute other)
Initialize from another template.
Definition: Attributes.cs:593
What you can enter when selecting a single value from a numbered enumeration.
Navigation format for one line in navigation choices.
Provide a regular expression to validate a string field.
Definition: Attributes.cs:657
What you can enter while entering an integer.
Use the default TemplateBaseAttribute.ChoiceStyle from the FormConfiguration.DefaultPrompt.
string[] Alternatives
Regular expressions for matching user input.
Definition: Attributes.cs:124
What to display when asked for help while clarifying.
Define a field or property as optional.
Definition: Attributes.cs:608
How to ask for one value from an enumeration.
TermsAttribute(params string[] alternatives)
Regular expressions or terms used when matching user input.
Definition: Attributes.cs:151
OptionalAttribute()
Mark a field or property as optional.
Definition: Attributes.cs:613
What you can enter when selecting one value from an enumeration.
How to represent a value that has not yet been specified.
What to display when asked for help when entering a string.
BoolDefault AllowDefault
When processing choices {||} in a Pattern Language string, provide a choice for the default value if ...
Definition: Attributes.cs:684
What you can enter when entering a double.
Show choices as a carousel if possibe.
PromptAttribute(TemplateAttribute pattern)
Define a prompt based on a TemplateAttribute.
Definition: Attributes.cs:308
string Title
Title when a card is generated from description.
Definition: Attributes.cs:72
CaseNormalization FieldCase
Control case when showing {&} field name references in a Pattern Language string. ...
Definition: Attributes.cs:725
NumericAttribute(double min, double max)
Specify the range of possible values for a number field.
Definition: Attributes.cs:642
CaseNormalization ChoiceCase
Control case when showing choices in {||} references in a Pattern Language string.
Definition: Attributes.cs:689
First letter of each word is capitalized
Abstract base class for FormFlow attributes.
Definition: Attributes.cs:45
string Description
Description of the field, property or enum to use in templates and choices.
Definition: Attributes.cs:67
Root namespace for the Microsoft Bot Builder SDK.
Attribute to override the default description of a field, property or enum value. ...
Definition: Attributes.cs:62