GrammarBuilder Constructors

Definition

Namespace:

System.Speech.Recognition

Assembly:

System.Speech.dll

Package:

System.Speech v9.0.0-rc.2.24473.5

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()

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

• Choices
• Grammar
• SemanticResultKey
• SemanticResultValue

GrammarBuilder(Choices)

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.GrammarBuilder

Public 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

• Choices
• Grammar
• SemanticResultKey
• SemanticResultValue

GrammarBuilder(SemanticResultKey)

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.GrammarBuilder

Public Sub New (key As SemanticResultKey)

Parameters

key

SemanticResultKey

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

• Choices
• Grammar
• SemanticResultKey
• SemanticResultValue

GrammarBuilder(SemanticResultValue)

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.GrammarBuilder

Public 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

• Choices
• Grammar
• SemanticResultKey
• SemanticResultValue

GrammarBuilder(String)

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.GrammarBuilder

Public 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

• Choices
• Grammar
• SemanticResultKey
• SemanticResultValue

GrammarBuilder(String, SubsetMatchingMode)

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.GrammarBuilder

Public 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

• SubsetMatchingMode

GrammarBuilder(GrammarBuilder, Int32, Int32)

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.GrammarBuilder

Public 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

• Choices
• Grammar

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.

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.GrammarBuilder

Public 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.

See also

• Choices
• Grammar