Grammar Constructor (SrgsDocument, String, Uri)

Initializes a new instance of a Grammar class from an SrgsDocument object, specifies a root rule, and defines a base Uniform Resource Identifier (URI) to resolve relative rule references.

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

Syntax

'Declaration
Public Sub New ( _
    srgsDocument As SrgsDocument, _
    ruleName As String, _
    baseUri As Uri _
)
'Usage
Dim srgsDocument As SrgsDocument
Dim ruleName As String
Dim baseUri As Uri

Dim instance As New Grammar(srgsDocument, _
    ruleName, baseUri)

public Grammar(
    SrgsDocument srgsDocument,
    string ruleName,
    Uri baseUri
)

Parameters

srgsDocument
Type: Microsoft.Speech.Recognition.SrgsGrammar.SrgsDocument
The constraints for the speech recognition grammar.

ruleName
Type: System.String
The identifier of the rule to use as the entry point of the speech recognition grammar, or a null reference (Nothing in Visual Basic) to use the default root rule of the SrgsDocument.
This parameter may be a null reference (Nothing in Visual Basic).

baseUri
Type: System.Uri
[System.Uri] object defining base path that any relative rule references, for example to other grammars, within the grammar are resolved against.
This parameter may be a null reference (Nothing in Visual Basic).

Exceptions

Exception	Condition
ArgumentException	ruleName cannot be resolved or is not public, or ruleName is a null reference (Nothing in Visual Basic) and srgsDocument does not contain a root rule.
ArgumentNullException	srgsDocument is a null reference (Nothing in Visual Basic).
FormatException	srgsDocument contains a rule reference that cannot be resolved.

Remarks

The srgsDocument argument

Must never be a null reference (Nothing in Visual Basic).
Must contain the rule specified by ruleName, if ruleName is not a null reference (Nothing in Visual Basic), and a root rule if ruleName is a null reference (Nothing in Visual Basic).

The ruleName argument:

May be a null reference (Nothing in Visual Basic) or Empty.
If ruleName is not a null reference (Nothing in Visual Basic) and the rule specified is not found in the grammar being loaded, an exception is generated.
If ruleName is a null reference (Nothing in Visual Basic), and the grammar contained in the file specified does not declare a root rule, an exception is generated.

The baseUri argument:

The value of baseUri should be an absolute URI, and can be a path or a file.
If the value of baseUri is a path, be sure to append a trailing slash.
The URI provided by baseUri is not validated when the Grammar object is constructed.

Instead, if the URI is invalid or any relative references are inaccessible, the SpeechRecognitionEngine generates and exception when it loads the grammar.

The recognition engine performs the following checks on Grammar objects it is loading:
- Resolves all references with absolute URIs.
- Checks the XML of Grammar being loaded for correct syntax.
- Resolves references used to create the instance of srgsDocument from which the Grammar was created. If the srgsDocument has been created from a file, this typically includes the directory where that file was located.
- Resolves references with the value of baseUri if it is non-null.

Examples

The following example creates a speech recognition grammar in an SrgsDocument that contains a relative rule reference to the cities.xml file, and specifies a URI to use to resolve the rule reference. The content of the cities.xml file appears in the XML example that follows the C# example.

private static Grammar CreateSrgsDocumentGrammar3()
{
  // Create the SrgsDocument.
  SrgsDocument document = new SrgsDocument();

  // Create the Main rule and add it to the document.
  SrgsRule mainRule = new SrgsRule("Main");
  mainRule.Scope = SrgsRuleScope.Public;

  SrgsItem item = new SrgsItem(" Can I get a shuttle in ");

  // Create a relative URI for the cities rule.
  Uri ruleUri = new Uri("cities.xml#Cities", UriKind.Relative);

  item.Add(new SrgsRuleRef(ruleUri));

  mainRule.Add(item);
  document.Rules.Add(mainRule);

  // Set the root rule.
  document.Root = mainRule;

  // Create the grammar.
  Uri baseUri = new Uri(@"file://c:\temp\");
  Grammar citiesGrammar = new Grammar(document, null, baseUri);
  citiesGrammar.Name = "SrgsDocument Cities Grammar 3";

  return citiesGrammar;
}

<?xml version="1.0" encoding="UTF-8" ?>
<grammar version="1.0" xml:lang="en-US"
         xmlns="http://www.w3.org/2001/06/grammar"
         tag-format="semantics/1.0" root="Main">
  
  <!-- cities.xml: 
    Defines an SRGS grammar for requesting a flight. This grammar includes
    a Cities rule that lists the cities that can be used for departures
    and destinations. -->
  
  <rule id="Main">
    <item>
      I would like to fly from <ruleref uri="#Cities"/>
      to <ruleref uri="#Cities"/>
    </item>
  </rule>

  <rule id="Cities" scope="public">
    <one-of>
      <item> Seattle </item>
      <item> Los Angeles </item>
      <item> New York </item>
      <item> Miami </item>
    </one-of>
  </rule>
</grammar>

Grammar Constructor (SrgsDocument, String, Uri)

Syntax

Parameters

Exceptions

Remarks

Examples

See Also

Reference

Other Resources

Additional resources