Extension Basics

This page describes the fundamentals of Vocola extensions, using a simple C# example.

Source code for this example extension may be found in the Vocola installation folder ExtensionSamples\Simple. A Visual Basic .NET version is also available, in ExtensionSamples\SimpleVB.

A simple example

The following C# extension class Simple has two functions—LogHelloWorld writes the phrase "Hello, world!" to the Vocola log window, and Subtract subtracts two integers:

using Vocola; 

namespace Library
{
    public class Simple : VocolaExtension
    {
        [VocolaFunction]
        static public void LogHelloWorld()
        {
            VocolaApi.LogMessage(LogLevel.Medium, "Hello, world!");
        }

        [VocolaFunction]
        static public int Subtract(int a, int b)
        {
            return a - b;
        }
    }
}

Namespace and class

Every extension class needs a namespace declaration. Using the Library namespace as in line 3 above is simplest for development; because the default Vocola 3 base using set contains Library you can omit the Library namespace prefix when calling your extension functions from voice commands. If you share your extension with other Vocola users, consider using a different namespace to avoid possible class name conflicts with extensions developed by others or with future function library classes.

An extension class must be public, and must be a subclass of VocolaExtension, as shown in line 5 above.

The statement using Vocola on line 1 above allows referencing Vocola API objects like VocolaExtension and LogLevel without the ‘Vocola.’ namespace prefix.

(Note for Visual Basic .NET developers—VB.NET projects have a default "Root namespace" initialized to the project name. If you open the project properties in Visual Studio you can delete the Root namespace or change it to "Library".)

Functions

Each extension function is declared as a static and public .NET method and preceded by the attribute declaration [VocolaFunction], as shown in lines 8 and 14 above.

(Feel free to define private helper methods in your extension classes as well; without the [VocolaFunction] attribute such methods are not visible to Vocola commands.)

An extension function may take arguments and may return a value. Supported types are:

    string
    int
    double
    bool

For example, Subtract (declared on line 14 above) takes two arguments of type int and returns a value of type int.

When an extension function is called in a Vocola command, each argument value is converted from its Vocola string representation to the declared .NET type of the associated function argument. (If the string cannot be converted, Vocola aborts the calling command and displays an error message in the Vocola log window.) When the function returns, the return value is converted to a string.

The Vocola API

Vocola provides an application programming interface (API), exposing methods and properties which extensions may invoke to interact with the running Vocola application. The VocolaExtension class (which all extensions inherit from) has static members named VocolaApi and VocolaDictation. Extensions may use these inherited members to invoke API methods; for example, LogHelloWorld calls VocolaApi.LogMessage on line 10 above to send a message to the Vocola log window.

See Vocola API for a summary of available methods and properties.

Exceptions

An extension function may abort execution by throwing a VocolaExtensionException, which aborts the calling command and displays an error message in the Vocola log window. If other exceptions arise while executing an extension function, Vocola aborts the calling command and displays a message and stack trace in the Vocola log window.