writeplugin

how to write a plugin

A plugin is a task a task that can be executed in a kosi package. The Plugins are selsected in the tasks tree in the batch.yaml. The plugin gets passed a parameter tree, which can be read in the plugin.

classes in the plugin

There are two important classes: the version class and the info class. An overview of the versions of the plugins is in the info class. The class must inherit from the iplugininfo class. a forwarding to the individual version classes is important: Also there is a function which returns a list with all versions of the plugin.

The Logic of the plugin lies in run method in the version class.
The run method gets a sandbox and the parameter-tree passed.

public void Run(ISandbox sandbox, ITree parameter) {

the lint function of the version class checks the tree for the plugin if the parameter-tree is correct. A function for returning the name and version of The plugin is also obligatory.

Sandbox is a class which contains data for the plugin. An example would be the storage space of the package.yaml, which defines the kosi package. You can also set variables in the sandbox.

ITree config = sandbox.GetVariable("config");

You can also get an instance of the logger from the sandbox. with the getlogginmanager() method you can access the logger.

sandbox.GetLoggingManager().Debug1("plugin-template", $"run template plugin");

The method after get logging menager determines the logging level. There are four logging levels:

info
debug1
debug2
debug3

The first parameter determines the channel. It is recommended that you name it after your plugin. The message for the logging is the second parameter.

The sandbox can create a instance of a fio file, which can be written on hard disk. This fio file has a Tree, which can be modified with the fio-tool.

IFile templateYaml = sandbox.NewFio();

the element of the tree can be accessed with the fio-tool. Fio is included in the toolchain.dll. These Tree have elements and/or subtrees. A element in Fio has only one key and an associated value.

string kosiFileName = (string)templateyaml.GetElement($"apiversion").Value;

when you want to access a subtree, you can use a point structure.

string kosiFileName = (string)templateyaml.GetElement($"import.files.{fileElement}").Value;

In contrast, a subtree can have multiple elements with associated values. “Value” is the keyword for using the value of the element-key.

ITree mergeduservalues = config.GetSubTree("mergedFioFiles");

You have to possibility to use other plugins, the sandbox has also the runPLugin() function. In this example we use the print plugin with a tree as a parameter for the print plugin. The tree have to be the same as the tree you use within the run tree in the batch.yaml for the plugin.

sandbox.RunPlugin("print", parameter);

the parameter-tree can be created with fio. the name of the plguin does not have to be within the parameter-tree. Fio has the option to set parameters, so for example the creation of the parameter-tree for the print-plugin can be like that:

Itree parameter = new Tree();
parameter.setElement("message","now the print plugin can be run!");
sandbox.RunPlugin("print", parameter);