SemanticResultValue Class

Sets values to SemanticValue objects created in Grammar using GrammarBuilder instances.

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

public class SemanticResultValue
public class SemanticResultValue
public class SemanticResultValue
Not applicable.

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 and instance of SemanticValue, through the Semantics property on RecognizedPhrase.


Value managed by SemanticResultValue objects are defined by instances passed to their constructors. This can only have an underlying type only of bool, int, float, or string. Any other type will prevent construction of a Grammar instance with the

Typical use of SemanticResultValue instances associates the instance with a recognizable Grammar grammar element, such as a phrase, rule, or Choices. If the associated element is used as part of the 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 the constructor used to create the SemanticResultValue.

  • If only the value, as specified by an instance of Object, is used in constructing a SemanticResultValue object, the SemanticResultValue is be associated with the grammar element which 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 given string value phrase or specific GrammarBuilder instance is used, along with a that specifies a SemanticResultValue value, that value is automatically associated with that string value phrase or 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 code fragment below illustrates this, and is functionally equivalent to the fragment above, which used the explicit calls to GrammarBuilder.Append and SemanticResultValue(Object): if the recognition logic using 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 explicitly attached to a SemanticResultValue, using an SemanticResultKey object. SemanticResultValue instances not explicitly attached to a key, are attached to the root key of the default SemanticValue

Once an SemanticResultValue has been used to set the SemanticValue.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.

For example:

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

would cause an exception as it sets and then modified the root SemanticValue.Value of a Grammar.

On the other hand:

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

Is permitted, because although multiple instances of SemanticResultValue are defined, they are included in a Choices object, and only one will ever be used to set the value of the key BgOrFgText.

The example below returns a Grammar for recognizing the command "Set/Change/Alter Foreground/Background … [color list]". SemanticResultValue, and SemanticResultKey instances (along with Choices and GrammarBuilder objects) are used to define a semantics that can be parsed on recognition to determine what color was request, and whether the foreground or background is to be modified.

private Grammar FgBgColorGrammar() {
    Grammar grammar = null;
    //Allow 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);
    //Now define the arguments to the command for Foreground or background and color as sementic 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))) {
                                        (new SemanticResultValue(colorName, (Color.FromName(colorName)).Name)));
        //Uses implicit conversion of SemanticResultValue to GrammarBuilder    

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

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


Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Windows 98, Windows Server 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.

.NET Framework

Supported in: 3.0

Community Additions