Creating Extensions

Follow these steps to create a Vocola extension project using the code in the simple example.

1. Create a "Class Library" project in Visual C# 2008 Express:
   • Start Visual C# 2008 Express
   • From the File menu choose "New Project..."
   • In the dialog that appears:
   • Choose "Class Library"
   • Type the project name, "Simple"
   • Click OK
2. Save the project:
   • From the File menu choose "Save Simple As..."
   • Choose a folder to contain the project folder
   • Uncheck "Create directory for solution"
   • Click OK
3. Add a reference to VocolaExtension.dll:
   • From the Project menu choose "Add Reference..."
   • In the dialog that appears:
   • Choose the "Browse" tab
   • Navigate to "Bin\VocolaExtension.dll" in the Vocola installation folder
   • Click OK
4. Change the class name in Solution Explorer:
   • Select the file "Class1.cs"
   • Say "Press F2" and rename the file to "Simple.cs"
   • Click "Yes" when it asks if you want to rename references in the code
5. Replace the code in Simple.cs with the example code.
6. Say "Press F6" to build the project.

Installing

Follow these instructions to install and test an extension:

1. Say "Vocola Log" to open the Vocola log window, and set the log level to "Activity Details" or "Full Trace".
2. Say "Exit Vocola".
3. Copy the extension DLL (or its containing folder) to the Vocola extensions folder. (The default extensions folder location is C:\Users\username\Documents\Vocola3\Extensions, though it may be changed via the Options Panel.)
4. Say "Start Vocola".
5. Say "Vocola Log" to open the Vocola log window. You should see messages about loading your extension, such as:
       Loading extension file 'Simple.dll':
         Class 'Library.Simple' has 2 functions

Note that if an extension uses a third-party DLL you must currently copy that DLL to the Vocola Bin installation folder.

Testing and debugging

Now you're ready to create voice commands which call your extension functions. For example, the following commands could be used to test the functions in the Simple extension:

Hello World = Simple.LogHelloWorld(); Subtract One From 1..9 = Simple.Subtract($1, 1);

Saying "Hello World" writes the phrase "Hello, world!" to the Vocola log window. Saying "Subtract One From 7" sends the keystroke "6".

You can set breakpoints and examine variable values in extension code using the Visual Studio debugger. To launch the debugger choose Debug > Attach to Process... and select the Vocola.exe process. Or, another option is to call the .NET function System.Diagnostics.Debug.Break from the function you want to debug.

Documentation

If you want to share your extension you can build beautiful documentation automatically using XML comments in your code, the Sandcastle Help File Builder, and the VocolaFunctions Sandcastle presentation style installed with Vocola. The function library documentation was built this way, and you can see the XML documentation comments in the function library source code. Further details available on request.