SemanticResultValue Class

Represents a semantic value and optionally associates the value with a component of a speech recognition grammar.


Namespace:  System.Speech.Recognition
Assembly:  System.Speech (in System.Speech.dll)

<DebuggerDisplayAttribute("{_tag.DebugSummary}")> _
Public Class SemanticResultValue

The SemanticResultValue type exposes the following members.

Public methodSemanticResultValue(Object)Initializes a new instance of the SemanticResultValue class and specifies a semantic value.
Public methodSemanticResultValue(GrammarBuilder, Object)Initializes a new instance of the SemanticResultValue class and associates a semantic value with a GrammarBuilder object.
Public methodSemanticResultValue(String, Object)Initializes a new instance of the SemanticResultValue class and associates a semantic value with a String object.

Public methodEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodGetHashCodeServes as the default hash function. (Inherited from Object.)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodToGrammarBuilderReturns an instance of GrammarBuilder constructed from the current SemanticResultValue instance.
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)

Use of SemanticResultValue and SemanticResultKey objects, in conjunction with GrammarBuilder and Choices, is the easiest way to design a semantic structure for a Grammar. Semantic information for a phrase is accessed by obtaining an instance of SemanticValue, through the Semantics property on RecognizedPhrase.


Values managed by SemanticResultValue objects are defined by Object instances passed to their constructors. The underlying type of this Object must be bool, int, float, or string. Any other type will prevent construction of a Grammar instance with the SemanticResultValue.

The typical use of a SemanticResultValue instance associates the instance with a recognizable component of a Grammar, such as a phrase, a rule, or a Choices object. If the associated component is used as part of a recognition operation, the SemanticResultValue is used to define a value in the semantics of the returned phrase.

There are two basic methods for associating a SemanticResultValue instance with a grammar element, depending on the constructor used to create the SemanticResultValue.

  • If only the value (specified by an instance of Object) is used to construct a SemanticResultValue object, the SemanticResultValue is associated with the grammar component that preceded it, in addition to a GrammarBuilder object.

    For instance, in the code fragment below, if a Grammar constructed using this GrammarBuilder instance recognizes the word "background", a value of true is set in the recognized phrase semantics.

    GrammarBuilder backgroundGB=new GrammarBuilder("background");
    backgroundGB.Append(new SemanticResultValue(true));

    For more information, see the description of SemanticResultValue(Object).

  • If a string value phrase or specific GrammarBuilder instance is used, together with a Object that specifies a SemanticResultValue value, that value is automatically associated with the string value phrase or the GrammarBuilder instance. If the phrase or GrammarBuilder object is used in the process of recognition, the value will be assigned to the semantics of the recognized phrase.

    The following example illustrates this, and is functionally equivalent to the preceding example, which used explicit calls to Append and SemanticResultValue(Object). If the recognition logic uses the word "background", the value true will be added to the recognized semantics.

    fgOrbgChoice.Add((GrammarBuilder)new SemanticResultValue("background", true));

    For more information, see the description of SemanticResultValue(GrammarBuilder, Object) and SemanticResultValue(String, Object).

To be used by a Grammar in recognition, all SemanticResultValue instances must be associated with one of the SemanticValue objects used by that Grammar. This is done by associating a semantic key with the SemanticResultValue.

Semantic keys can be explicitly attached to a SemanticResultValue, using a SemanticResultKey object. SemanticResultValue instances not explicitly attached to a key are attached to the root key of the default SemanticValue.

After a SemanticResultValue has been used to set the Value, whether it is tagged with the default root key or by any particular SemanticResultKey, that value must not be modified or an exception will occur during recognition operations.

The following example will cause an exception because it sets and then modifies the root Value of a Grammar.

GrammarBuilder gb=new GrammarBuilder();
gb.Append(new SemanticResultValue("One"));
gb.Append(new SemanticResultValue("Two"));

On the other hand, the code in the following example is permitted. Although it defines multiple instances of SemanticResultValue, they are included in a Choices object, and only one will ever be used to set the value of the key bgOrfgText.

Choices fgOrbgChoice = new Choices();
fgOrbgChoice.Add((GrammarBuilder)new SemanticResultValue("background"));
fgOrbgChoice.Add((GrammarBuilder)new SemanticResultValue("foreground"));
SemanticResultKey fgOrbgChoiceKey = new SemanticResultKey("BgOrFgText", fgOrbgChoice);

For more information about using SemanticResultValue and SemanticResultKey objects, see Understanding SemanticResultValue and SemanticResultKey Objects and Using a SemanticResultKey to Extract a SemanticResultValue in the System Speech Programming Guide for .NET Framework 4.0.

The following example returns a Grammar that recognizes the command "Set/Change/Alter Foreground/Background … [color list]". SemanticResultValue and SemanticResultKey instances (in conjunction with Choices and GrammarBuilder objects) are used to define semantics that can be parsed on recognition. The parsed semantics will determine which color was requested and whether the foreground or background is to be modified.

private Grammar FgBgColorGrammar() 
  Grammar grammar = null;
  // Allow the command to begin with set, alter, change.
  Choices introChoices = new Choices();
  foreach (string introString in new string[] { "Change", "Set", "Alter" }) 
    GrammarBuilder introGB = new GrammarBuilder(introString);
    introChoices.Add(new SemanticResultValue(introGB, String.Format("Command: {0}", introString)));
  GrammarBuilder cmdIntro = new GrammarBuilder(introChoices);

  // Define the arguments for the command to select foreground or background 
  // and to change their color as semantic values.
  Choices fgOrbgChoice = new Choices();
  GrammarBuilder backgroundGB=new GrammarBuilder("background");
  backgroundGB.Append(new SemanticResultValue(true));
  fgOrbgChoice.Add((GrammarBuilder)new SemanticResultValue("foreground", false));
  SemanticResultKey fgOrbgChoiceKey = new SemanticResultKey("BgOrFgBool", fgOrbgChoice);
  Choices colorChoice = new Choices();
  foreach (string colorName in System.Enum.GetNames(typeof(KnownColor))) 

    // Use implicit conversion of SemanticResultValue to GrammarBuilder.    
        (GrammarBuilder) (new SemanticResultValue(colorName, (Color.FromName(colorName)).Name)));

  // Create a GrammarBuilder for CmdArgs to be appended to CmdIntro using
  // semantic keys.
  GrammarBuilder cmdArgs = new GrammarBuilder();
  cmdArgs.Append(new SemanticResultKey("BgOrFgBool", fgOrbgChoice));
  cmdArgs.Append(new SemanticResultKey("colorStringList", colorChoice));

  GrammarBuilder cmds = 
                       new GrammarBuilder(new SemanticResultKey("Cmd Args", cmdArgs)));
  grammar = new Grammar(cmds);
  grammar.Name = "Tree [Set,change,alter] [foreground,background] * color";
  return grammar;

.NET Framework

Supported in: 4.6, 4.5, 4, 3.5, 3.0

.NET Framework Client Profile

Supported in: 4

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
© 2015 Microsoft