GrammarBuilder Constructors
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Initializes a new instance of the GrammarBuilder class.
Overloads
| GrammarBuilder() |
Initializes a new, empty instance of the GrammarBuilder class. |
| GrammarBuilder(Choices) |
Initializes a new instance of the GrammarBuilder class from a set of alternatives. |
| GrammarBuilder(SemanticResultKey) |
Initializes a new instance of the GrammarBuilder class from a semantic key. |
| GrammarBuilder(SemanticResultValue) |
Initializes a new instance of the GrammarBuilder class from a semantic value. |
| GrammarBuilder(String) |
Initializes a new instance of the GrammarBuilder class from a sequence of words. |
| GrammarBuilder(String, SubsetMatchingMode) |
Initializes a new instance of the GrammarBuilder class for a subset of a sequence of words. |
| GrammarBuilder(GrammarBuilder, Int32, Int32) |
Initializes a new instance of the GrammarBuilder class from a repeated element. |
| GrammarBuilder(String, Int32, Int32) |
Initializes a new instance of the GrammarBuilder class from the sequence of words in a String and specifies how many times the String can be repeated. |
Remarks
Instances of this class can also be obtained by implicit conversions from other classes or by combining a GrammarBuilder object with a second object to from a new GrammarBuilder. For more information, see the Implicit and Addition methods.
To add constraints to an existing GrammarBuilder, use the Add, Append, AppendDictation, AppendRuleReference, and AppendWildcard methods, and the Addition operator.
Important
The speech recognizer can throw an exception when using a speech recognition grammar that contains duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the value of the same semantic element.
For more information about building and using speech recognition grammars, see Speech Recognition.
GrammarBuilder()
- Source:
- GrammarBuilder.cs
- Source:
- GrammarBuilder.cs
Initializes a new, empty instance of the GrammarBuilder class.
public:
GrammarBuilder();public GrammarBuilder ();Public Sub New ()Examples
The following example uses GrammarBuilder and Choices objects to construct a grammar that can recognize either of the two phrases, "Make background colorChoice" or "Set background to colorChoice".
The example uses a Choices object to create a list of acceptable values for colorChoice from an array of String objects. A Choices object is analogous to the one-of element in the SRGS specification, and contains a set of alternate phrases, any one of which can be recognized when spoken. The example also uses a Choices object to group an array of two GrammarBuilder objects into a pair of alternative phrases that the resultant grammar can recognize. Alternate words or phrases are a component of most grammars, and the Choices object provides this functionality for grammars constructed with GrammarBuilder.
The example finally creates a Grammar object from a GrammarBuilder constructed from a Choices object.
private Grammar CreateColorGrammar()
{
// Create a set of color choices.
Choices colorChoice = new Choices(new string[] {"red", "green", "blue"});
GrammarBuilder colorElement = new GrammarBuilder(colorChoice);
// Create grammar builders for the two versions of the phrase.
GrammarBuilder makePhrase = new GrammarBuilder("Make background");
makePhrase.Append(colorElement);
GrammarBuilder setPhrase = new GrammarBuilder("Set background to");
setPhrase.Append(colorElement);
// Create a Choices for the two alternative phrases, convert the Choices
// to a GrammarBuilder, and construct the Grammar object from the result.
GrammarBuilder bothPhrases = new GrammarBuilder();
Choices bothChoices = new Choices(new GrammarBuilder[] {makePhrase, setPhrase});
bothPhrases.Append(bothChoices);
Grammar grammar = new Grammar(bothPhrases);
grammar.Name = "backgroundColor";
return grammar;
}
Remarks
To add rules to an existing GrammarBuilder object, use the Add, Append, AppendDictation, AppendRuleReference, and AppendWildcard methods, and the Addition operator.
Important
The speech recognizer can throw an exception when using a speech recognition grammar that contains duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the value of the same semantic element.
See also
Applies to
GrammarBuilder(Choices)
- Source:
- GrammarBuilder.cs
- Source:
- GrammarBuilder.cs
Initializes a new instance of the GrammarBuilder class from a set of alternatives.
public:
GrammarBuilder(System::Speech::Recognition::Choices ^ alternateChoices);public GrammarBuilder (System.Speech.Recognition.Choices alternateChoices);new System.Speech.Recognition.GrammarBuilder : System.Speech.Recognition.Choices -> System.Speech.Recognition.GrammarBuilderPublic Sub New (alternateChoices As Choices)Parameters
- alternateChoices
- Choices
The set of alternatives.
Examples
The following example uses GrammarBuilder and Choices objects to construct a grammar that can recognize either of the two phrases, "Make background colorChoice" or "Set background to colorChoice".
The example uses a Choices object to create a list of acceptable values for colorChoice from an array of String objects. A Choices object is analogous to the one-of element in the SRGS specification, and contains a set of alternate phrases, any of which can be recognized when spoken. The example also uses a Choices object to group an array of two GrammarBuilder objects into a pair of alternative phrases that the resultant grammar can recognize. Alternate words or phrases are a component of most grammars, and the Choices object provides this functionality for grammars constructed with GrammarBuilder.
The example finally creates a Grammar object from a GrammarBuilder constructed from a Choices object.
private Grammar CreateColorGrammar()
{
// Create a set of color choices.
Choices colorChoice = new Choices(new string[] {"red", "green", "blue"});
GrammarBuilder colorElement = new GrammarBuilder(colorChoice);
// Create grammar builders for the two versions of the phrase.
GrammarBuilder makePhrase = new GrammarBuilder("Make background");
makePhrase.Append(colorElement);
GrammarBuilder setPhrase = new GrammarBuilder("Set background to");
setPhrase.Append(colorElement);
// Create a Choices for the two alternative phrases, convert the Choices
// to a GrammarBuilder, and construct the grammar from the result.
Choices bothChoices = new Choices(new GrammarBuilder[] {makePhrase, setPhrase});
Grammar grammar = new Grammar((GrammarBuilder)bothChoices);
grammar.Name = "backgroundColor";
return grammar;
}
Remarks
For more information about building a speech recognition grammar that contains alternatives, see Using Choices to Create a GrammarBuilder Grammar.
See also
Applies to
GrammarBuilder(SemanticResultKey)
- Source:
- GrammarBuilder.cs
- Source:
- GrammarBuilder.cs
Initializes a new instance of the GrammarBuilder class from a semantic key.
public:
GrammarBuilder(System::Speech::Recognition::SemanticResultKey ^ key);public GrammarBuilder (System.Speech.Recognition.SemanticResultKey key);new System.Speech.Recognition.GrammarBuilder : System.Speech.Recognition.SemanticResultKey -> System.Speech.Recognition.GrammarBuilderPublic Sub New (key As SemanticResultKey)Parameters
The semantic key.
Examples
The following example creates a speech recognition grammar that can recognize the two phrases, "Make background colorChoice" and "Set background to colorChoice", where colorChoice is selected from a set of colors. The grammar lets a user speak any of several color names, and returns semantic information about the recognized color name to the application.
The example uses a single SemanticResultKey with which you can retrieve the SemanticValue that is associated with the color spoken by the user. For example, if the input contains the phrase, "Set background to red", the recognition result contains the semantic value of "#FF0000", which you can retrieve using a handler for the SpeechRecognized event.
The example uses String, Choices, SemanticResultKey, SemanticResultValue, and GrammarBuilder objects to build the constraints that are all contained in the last GrammarBuilder object, bothPhrases. Finally, the example constructs a Grammar object from the completed GrammarBuilder.
private Grammar CreateColorGrammar()
{
// Create a set of color choices.
// Include semantic information about each of the colors.
Choices colorChoice = new Choices();
GrammarBuilder colorBuilder = new GrammarBuilder("red");
SemanticResultValue colorValue =
new SemanticResultValue(colorBuilder, "#FF0000");
colorChoice.Add(new GrammarBuilder(colorValue));
colorBuilder = new GrammarBuilder("green");
colorValue = new SemanticResultValue(colorBuilder, "#00FF00");
colorChoice.Add(new GrammarBuilder(colorValue));
colorBuilder = new GrammarBuilder("blue");
colorValue = new SemanticResultValue(colorBuilder, "#0000FF");
colorChoice.Add(new GrammarBuilder(colorValue));
GrammarBuilder colorElement = new GrammarBuilder(colorChoice);
// Create grammar builders for the two versions of the phrase.
GrammarBuilder makePhrase = new GrammarBuilder("Make background");
makePhrase.Append(colorElement);
GrammarBuilder setPhrase = new GrammarBuilder("Set background to");
setPhrase.Append(colorElement);
// Create a Choices object for the two alternative phrases.
Choices bothChoices = new Choices(new GrammarBuilder[] {makePhrase, setPhrase});
GrammarBuilder bothPhrases = new GrammarBuilder(bothChoices);
// Create the semantic key for referencing the color information.
SemanticResultKey colorKey =
new SemanticResultKey("ColorCode", bothPhrases);
bothPhrases = new GrammarBuilder(colorKey);
// Construct the Grammar object from the GrammarBuilder.
Grammar grammar = new Grammar(bothPhrases);
grammar.Name = "backgroundColor";
return grammar;
}
Remarks
When you create a GrammarBuilder instance from a SemanticResultValue object, you add semantic information to the grammar that can be returned in the recognition result. You can access the semantic information in the recognition result using the Semantics property of RecognizedPhrase, which is available in the handler for the SpeechRecognized event. If the GrammarBuilder defines a SemanticResultKey, this can be used to retrieve the semantic information in a recognition result that is associated with the key. See the example for Append(SemanticResultKey), and also see SemanticResultValue and SemanticResultKey.
Important
When you construct GrammarBuilder objects that contain SemanticResultValue or SemanticResultKey instances, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the Value property of a SemanticValue object. The speech recognizer can throw an exception if it encounters these circumstances.
See also
Applies to
GrammarBuilder(SemanticResultValue)
- Source:
- GrammarBuilder.cs
- Source:
- GrammarBuilder.cs
Initializes a new instance of the GrammarBuilder class from a semantic value.
public:
GrammarBuilder(System::Speech::Recognition::SemanticResultValue ^ value);public GrammarBuilder (System.Speech.Recognition.SemanticResultValue value);new System.Speech.Recognition.GrammarBuilder : System.Speech.Recognition.SemanticResultValue -> System.Speech.Recognition.GrammarBuilderPublic Sub New (value As SemanticResultValue)Parameters
- value
- SemanticResultValue
The semantic value or name/value pair.
Examples
The following example creates a speech recognition grammar that can recognize the two phrases, "Make background colorChoice" and "Set background to colorChoice", where colorChoice is selected from a set of colors. The grammar lets a user speak any of several color names, and returns semantic information about the recognized color name to the application.
The example uses a single SemanticResultKey with which you can retrieve the SemanticValue that is associated with the color spoken by the user. For example, if the input contains the phrase, "Set background to red", the recognition result contains the semantic value of "#FF0000", which you can retrieve using a handler for the SpeechRecognized event.
The example uses String, Choices, SemanticResultKey, SemanticResultValue, and GrammarBuilder objects to build the constraints that are all contained in the last GrammarBuilder object, bothPhrases. Finally, the example constructs a Grammar object from the completed GrammarBuilder.
private Grammar CreateColorGrammar()
{
// Create a set of color choices.
// Include semantic information about each of the colors.
Choices colorChoice = new Choices();
GrammarBuilder colorBuilder = new GrammarBuilder("red");
SemanticResultValue colorValue =
new SemanticResultValue(colorBuilder, "#FF0000");
colorChoice.Add(new GrammarBuilder(colorValue));
colorBuilder = new GrammarBuilder("green");
colorValue = new SemanticResultValue(colorBuilder, "#00FF00");
colorChoice.Add(new GrammarBuilder(colorValue));
colorBuilder = new GrammarBuilder("blue");
colorValue = new SemanticResultValue(colorBuilder, "#0000FF");
colorChoice.Add(new GrammarBuilder(colorValue));
GrammarBuilder colorElement = new GrammarBuilder(colorChoice);
// Create grammar builders for the two versions of the phrase.
GrammarBuilder makePhrase = new GrammarBuilder("Make background");
makePhrase.Append(colorElement);
GrammarBuilder setPhrase = new GrammarBuilder("Set background to");
setPhrase.Append(colorElement);
// Create a Choices for the two alternative phrases.
Choices bothChoices = new Choices(new GrammarBuilder[] {makePhrase, setPhrase});
GrammarBuilder bothPhrases = new GrammarBuilder(bothChoices);
// Create the semantic key for referencing the color information.
SemanticResultKey colorKey =
new SemanticResultKey("ColorCode", bothPhrases);
bothPhrases = new GrammarBuilder(colorKey);
// Construct the grammar from the grammar builder.
Grammar grammar = new Grammar(bothPhrases);
grammar.Name = "backgroundColor";
return grammar;
}
Remarks
When you create a GrammarBuilder instance from a SemanticResultValue object, you add semantic information to the grammar that can be returned in the recognition result. You can access the semantic information in the recognition result using the Semantics property of RecognizedPhrase, which is available in the handler for the SpeechRecognized event. If the GrammarBuilder defines a SemanticResultKey, this can be used to retrieve the semantic information in a recognition result that is associated with the key. See the example for Append(SemanticResultKey), and also see SemanticResultValue and SemanticResultKey.
Important
When you construct GrammarBuilder objects that contain SemanticResultValue or SemanticResultKey instances, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the Value property of a SemanticValue object. The speech recognizer can throw an exception if it encounters these circumstances.
See also
Applies to
GrammarBuilder(String)
- Source:
- GrammarBuilder.cs
- Source:
- GrammarBuilder.cs
Initializes a new instance of the GrammarBuilder class from a sequence of words.
public:
GrammarBuilder(System::String ^ phrase);public GrammarBuilder (string phrase);new System.Speech.Recognition.GrammarBuilder : string -> System.Speech.Recognition.GrammarBuilderPublic Sub New (phrase As String)Parameters
- phrase
- String
The sequence of words.
Examples
The following example uses GrammarBuilder and Choices objects to construct a grammar that can recognize either of the two phrases, "Make background colorChoice" or "Set background to colorChoice".
After creating a list of acceptable values for colorChoice using a Choices object, the example initializes two GrammarBuilder objects, makePhrase and setPhrase, using a string as an argument.
The example finally creates a Grammar object from a Choices object cast to a GrammarBuilder object.
private Grammar CreateColorGrammar()
{
// Create a set of color choices.
Choices colorChoice = new Choices(new string[] {"red", "green", "blue"});
GrammarBuilder colorElement = new GrammarBuilder(colorChoice);
// Create grammar builders for the two versions of the phrase.
GrammarBuilder makePhrase = new GrammarBuilder("Make background");
makePhrase.Append(colorElement);
GrammarBuilder setPhrase = new GrammarBuilder("Set background to");
setPhrase.Append(colorElement);
// Create a Choices for the two alternative phrases, convert the Choices
// to a GrammarBuilder, and construct the Grammar object from the result.
Choices bothChoices = new Choices(new GrammarBuilder[] {makePhrase, setPhrase});
Grammar grammar = new Grammar((GrammarBuilder)bothChoices);
grammar.Name = "backgroundColor";
return grammar;
}
Remarks
The phrase represents an exact spoken phrase that the speech recognition grammar can recognize. For more information about building a speech recognition grammar that contains strings, see Using Strings to Create a GrammarBuilder Grammar.
See also
Applies to
GrammarBuilder(String, SubsetMatchingMode)
- Source:
- GrammarBuilder.cs
- Source:
- GrammarBuilder.cs
Initializes a new instance of the GrammarBuilder class for a subset of a sequence of words.
public:
GrammarBuilder(System::String ^ phrase, System::Speech::Recognition::SubsetMatchingMode subsetMatchingCriteria);public GrammarBuilder (string phrase, System.Speech.Recognition.SubsetMatchingMode subsetMatchingCriteria);new System.Speech.Recognition.GrammarBuilder : string * System.Speech.Recognition.SubsetMatchingMode -> System.Speech.Recognition.GrammarBuilderPublic Sub New (phrase As String, subsetMatchingCriteria As SubsetMatchingMode)Parameters
- phrase
- String
The sequence of words.
- subsetMatchingCriteria
- SubsetMatchingMode
The matching mode the speech recognition grammar uses to recognize the phrase.
Examples
The following example creates a speech recognition grammar for each SubsetMatchingMode value and a grammar for choosing between the matching mode grammars. If the value of phrase is "one two three four five six seven", then the Subsequence grammar recognizes the input "two three four", but not the input "one three five". However, the Ordered Subset grammar recognizes both of these inputs.
private static IEnumerable<Grammar>
CreateMatchingModeGrammars(string phrase)
{
List<Grammar> grammars = new List<Grammar>(5);
Choices modeChoice = new Choices();
Type enumType = typeof(SubsetMatchingMode);
foreach (SubsetMatchingMode mode in Enum.GetValues(enumType))
{
string modeName = Enum.GetName(enumType, mode);
modeName = BreakAtCaps(modeName);
GrammarBuilder builder = new GrammarBuilder(phrase, mode);
Grammar modeGrammar = new Grammar(builder);
modeGrammar.Name = modeName;
modeGrammar.Enabled = false;
grammars.Add(modeGrammar);
modeChoice.Add(modeName);
}
Grammar choiceGrammar = new Grammar(modeChoice);
choiceGrammar.Name = "choice";
grammars.Add(choiceGrammar);
return grammars;
}
// Insert spaces preceding each uppercase letter in a string.
private static string BreakAtCaps(string item)
{
if (item == null || item.Length == 0)
{
return item;
}
StringBuilder sb = new StringBuilder(item[0].ToString());
for (int i = 1; i < item.Length; i++)
{
char c = item[i];
if (char.IsUpper(c))
{
sb.Append(" ");
}
sb.Append(c);
}
return sb.ToString();
}
Remarks
The phrase parameter represents the phrase that the speech recognition grammar can recognize. The subsetMatchingMode parameter specifies a subset of the phrase that can be spoken to achieve successful recognition of the entire phrase. You can use this to create a grammar with a list of entries that have long names, without requiring users to speak an entire name to match an item.
For more information about the matching modes, see SubsetMatchingMode. For more information about building a speech recognition grammar that contains strings, see Using Strings to Create a GrammarBuilder Grammar.
See also
Applies to
GrammarBuilder(GrammarBuilder, Int32, Int32)
- Source:
- GrammarBuilder.cs
- Source:
- GrammarBuilder.cs
Initializes a new instance of the GrammarBuilder class from a repeated element.
public:
GrammarBuilder(System::Speech::Recognition::GrammarBuilder ^ builder, int minRepeat, int maxRepeat);public GrammarBuilder (System.Speech.Recognition.GrammarBuilder builder, int minRepeat, int maxRepeat);new System.Speech.Recognition.GrammarBuilder : System.Speech.Recognition.GrammarBuilder * int * int -> System.Speech.Recognition.GrammarBuilderPublic Sub New (builder As GrammarBuilder, minRepeat As Integer, maxRepeat As Integer)Parameters
- builder
- GrammarBuilder
The repeated element.
- minRepeat
- Int32
The minimum number of times that input matching the element defined by builder must occur to constitute a match.
- maxRepeat
- Int32
The maximum number of times that input matching the element defined by builder can occur to constitute a match.
Examples
The following example creates a speech recognition grammar for ordering a pizza. It starts with an optional, opening phrase, followed by one to four toppings, and closes with the word "pizza".
private static Grammar CreatePizzaGrammar()
{
// Create a Choices object from a string array of alternative toppings.
Choices toppings = new Choices(new string[] {
"cheese", "mushroom", "tomato", "onion",
"anchovy", "chicken", "pepperoni"});
// Create a GrammarBuilder and append the Choices object.
GrammarBuilder andToppings = new GrammarBuilder("and", 0, 1);
andToppings.Append(toppings);
// Construct the phrase.
GrammarBuilder gb = new GrammarBuilder("I would like a", 0, 1);
gb.Append(toppings);
gb.Append(new GrammarBuilder(andToppings, 0, 3));
gb.Append("pizza");
// Create the Grammar from the GrammarBuilder.
Grammar grammar = new Grammar(gb);
grammar.Name = "Pizza Order";
return grammar;
}
Remarks
If the value of minRepeat is 0, then the new GrammarBuilder represents an optional element.
The value of minRepeat must be greater than or equal to 0 and less than or equal to the value of maxRepeat.
Important
When you specify repeats for GrammarBuilder objects that contain SemanticResultValue or SemanticResultKey instances, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the Value property of a SemanticValue object. The speech recognizer can throw an exception if it encounters these circumstances.
See also
Applies to
GrammarBuilder(String, Int32, Int32)
- Source:
- GrammarBuilder.cs
- Source:
- GrammarBuilder.cs
Initializes a new instance of the GrammarBuilder class from the sequence of words in a String and specifies how many times the String can be repeated.
public:
GrammarBuilder(System::String ^ phrase, int minRepeat, int maxRepeat);public GrammarBuilder (string phrase, int minRepeat, int maxRepeat);new System.Speech.Recognition.GrammarBuilder : string * int * int -> System.Speech.Recognition.GrammarBuilderPublic Sub New (phrase As String, minRepeat As Integer, maxRepeat As Integer)Parameters
- phrase
- String
The repeated sequence of words.
- minRepeat
- Int32
The minimum number of times that input matching the phrase must occur to constitute a match.
- maxRepeat
- Int32
The maximum number of times that input matching the phrase can occur to constitute a match.
Examples
The following example creates a speech recognition grammar for ordering a pizza. It starts with an optional, opening phrase, followed by one to four toppings, and closes with the word "pizza".
private static Grammar CreatePizzaGrammar()
{
// Create a Choices object with alternatives for toppings.
Choices toppings = new Choices(new string[] {
"cheese", "mushroom", "tomato", "onion",
"anchovy", "chicken", "pepperoni"});
// Create a GrammarBuilder and append the Choices object.
GrammarBuilder andToppings = new GrammarBuilder("and", 0, 1);
andToppings.Append(toppings);
// Construct the phrase.
GrammarBuilder gb = new GrammarBuilder("I would like a", 0, 1);
gb.Append(toppings);
gb.Append(new GrammarBuilder(andToppings, 0, 3));
gb.Append("pizza");
// Create the Grammar from the GrammarBuilder.
Grammar grammar = new Grammar(gb);
grammar.Name = "Pizza Order";
return grammar;
}
Remarks
If the value of minRepeat is 0, then the new GrammarBuilder represents an optional element.
The value of minRepeat must be greater than or equal to 0 and less than or equal to the value of maxRepeat. For more information about building a speech recognition grammar that contains strings, see Using Strings to Create a GrammarBuilder Grammar.
