OSCOVA Plugin Interface
The plugin system in Oscova enables loading of external libraries that interface with Oscova bot system by implementing the OscovaPlugin
class. The plugin system is designed to inject further modularity for large scale projects addressing multiple domains or departments and enables developers to update the knowledge of their bot without having to recompile their entire project.
A few important things to note before writing a plugin for OSCOVA:
- Ensure that both the Bot project and the plugin target the same version of Syn Bot Framework.
- The .NET platform targetted by both the bot project and the plugin should also be the same.
- When loading plugins into OSCOVA ensure that only the plugin library is loaded and no other library is accidently loaded.
- Only classes with
public
modifiers implementing theOscovaPlugin
abstract classes will be loaded.
Creating a Plugin
In this section we will be creating an OSCOVA bot plugin targeting the same version.
To create a Class Library in Visual Studio following the steps given below.
- Start Visual Studio 2019 or above
- Select Create a new project and choose Class Library
- Click Next
:video videos/create-class-library.mp4
- Name the project SampleBotPlugin and choose Create.
Once the project is created, you will have to reference the same version of Syn Bot Framework that is used by your actual Bot project.
To do so, ensure that you specify Syn Bot Framework version when importing Syn.Bot
package from NuGet.org.
- In Visual Studio click on Tools
- Choose NuGet Package Manager
- Select Package Manager Console
- Type
install-package Syn.Bot -version [VERSION]
and press Enter
Your plugin project has now successfully imported the right version of Syn.Bot
framework. You can now write the plugin system as per your requirement.
Create a SampleDialog
class within this class library as shown below.
using Syn.Bot.Oscova;
using Syn.Bot.Oscova.Attributes;
namespace SampleBotPlugin
{
public class SampleDialog : Dialog
{
[Expression("test oscova plugin")]
public void TestIntent(Result result)
{
result.SendResponse("oscova plugin test response.");
}
}
}
Main Plugin Class
using Syn.Bot.Oscova;
namespace SampleBotPlugin
{
public class SampleOscovaPlugin : OscovaPlugin
{
public SampleOscovaPlugin(OscovaBot bot) : base(bot)
{
bot.Dialogs.Add(new SampleDialog());
}
}
}
As seen in the code above Oscova Plugins must have a constructor with 1 parameter taking an OscovaBot
instance. This instance is passed as a parameter to the base abstract class.
Note
By convention the names of all Oscova Bot plugin class libraries should end with BotPlugin
.
Loading a Plugin
Once the plugin project is compiled, a SampleBotPlugin.dll
file will be generated within the bin
or release
directory of the project. You may copy the generated file to any specify directory of your choice.
var bot = new OscovaBot();
bot.Plugins.LoadFromFile("PATH_TO_PLUGIN_FILE");
bot.Trainer.StartTraining(); //Training should only start after plugins are loaded.
Important
Oscova plugins should never initiate bot training. The training part must always be left to the main bot project.
Loading plugins from Directory
Multiple plugins residing in the same directory can be loaded at once without having to explicitly specifying their location individually by using the LoadFromDirectory()
method. However, when doing so Oscova requires that you specify a predicate that defines a condition if a particular file in the directory must be loaded as a plugin.
The code below ensures that only files with names ending with botplugin.dll
are loaded as Oscova plugins.
var bot = new OscovaBot();
bot.Plugins.LoadFromDirectory("PLUGIN_DIRECTORY_PATH", fileInfo =>
{
return fileInfo.Name.ToLower().EndsWith("botplugin.dll");
});
bot.Trainer.StartTraining();
Important
Oscova plugin system is designed to be a fail-safe plugin interface. If you are loading multiple plugins from a directory and if any plugin fails to load, the system will continue to load other plugins. However, to check if any exceptions were raised while loading plugins add an event handler to OscovaBot.Logger.LogReceived
or OscovaBot.Logger.ErrorLogReceived
.