Wizlink® Plugins Manual
Introduction – what are plugins and why do we need them?
Wizlink® software runs scenarios which are built of blocks named activities. They allow to perform most operations that are required to automate a process. Yet sometimes process requires performing some action that is not supported by any of available activities. Wizlink® contains special activity called Plugin which can run third-party .NET code supplied in form of DLL (Dynamic-link library). Plugin activity allows to choose class method, pass input arguments, execute and extract values from output parameters.
Screenshot above depicts part of a scenario with Plugin activity which runs method Add from class TestClass from library SampleWizlinkPlugin.wll. Method Add has two Int32 input parameters and as a result returns one Int32 value which will be assigned to variable sum defined in the scenario.
How to create simple plugin and use it in Wizlink®
Easier way to start coding a plugin is to use Wizlink® Plugin project template for Visual Studio. It is available for Wizlink® clients in a form of .vsix installer and currently supports VS 2019 and VS 2022 in community/pro/enterprise versions.
When project is created using this template it contains two files. PluginBase.cs contains base class for plugin classes which enables writing logs to Wizlink® log system and also Hide attribute which can be used to prevent some public class or method from being visible on user interface of Plugin activity. In HelloWizlinkPlugin.cs file there is a sample plugin class with 5 methods and verbose comments which help to understand how different parameters will interact with Wizlink® software. When project is built a .wll file is created as a result. If project is not created with Wizlink® template and produces .dll file as a result, it is recommended to change extensions name to .wll, because it is a default extension intepreted by Wizlink® as a Plugin library. That file needs to be placed in one of the following directories to be visible by Wizlink® software:
- C:\ProgramData\WizLinkPlugins,
- C:\Users\[user_name]\AppData\Local\WizLink\Plugins,
- within Wizlink® install directory (not recommended).
After library file is placed in proper directory it will be visible in Wizlink® Designer in Plugin activity. If plugin library uses other libraries, their .dll files needs to be copied along with plugin.
Important remarks
This section describes important remarks about creation and usage of plugins.
⇒ Cancellation mechanism
If a method from plugin performs long-running operation it should support cancellation mechanism. Method parameter of type CancellationToken will not be visible on user interface in Wizlink® software. Wizlink® will use it to pass its internal cancellation token which will be used if user requests to cancel scenario during execution.
⇒ Methods returning Task or Task<T>
User of Wizlink® is oblivious to the fact that a method is asynchronous. Method returning Task will not have any output parameters visible for Wizlink® user and method returning Task<T> will have T as a result parameter.
⇒ Hide attribute
If any public class or public method of a class is decorated with attribute named Hide it will not be visible and available for user of Wizlink®. Use that attribute to hide public classes or methods that you do not intend to be used by Wizlink® user.
⇒ Description attribute
If a method is decorated with Description attribute (System.ComponentModel. DescriptionAttribute) their description will be visible for Wizlink® user on Plugin activity when mouse cursor hovers over information icon by the method signature.
⇒ Class instance
First parameter of Plugin activity is an Instance Name. It is used to name instance of a class that will be created when activity is executed. Activity from screenshot above will create instance of class HelloWizlinkPlugin and will name it ClassInstanceName. That instance will be preserved to the end of scenario execution. Next call to Plugin activity with same class and instance name will not create new instance of that class. Instead, it will use instance created before. For example, if class HelloWizlinkPlugin initializes internal counter to 0 in a constructor and increments counter by one during execution of DoAsync method, this counter will maintain its changed value and during next execution of Plugin activity will be incremented again by one changing its value to 2.
⇒ Logs mechanism
If plugin code wants to log some events to Wizlink® log mechanism, plugin class should declare LoggerHandler event with proper EventArgs. Easiest way is to inherit from PluginBase class generated by Wizlink® Plugin template. In case using template is impossible below code can be used similar to one generated by template.
⇒ Requirements and unsupported options
- Plugin class has to declare public parameterless constructor. Only that constructor will be used by Wizlink® to instantiate class.
- Static methods are not available to be used in Plugin activity.
- Only types from Microsoft Common Object Runtime Library (mscorlib) are supported as parameters of methods.
⇒ Working directory
In versions before 1.4.16.20 all plugins run with a working directory set to the directory where Wizlink® is installed. In later versions, the working directory of a plugin is the directory where it is stored. This changes only for the lifetime of Plugin activity in Wizlink®, not for the lifetime of the plugin instance. More precisely: the path changes when the constructor executes and during each method call performed by the activity. Then the original path is restored, even if the user changes it in the plugin's code.
You can download a sample plugin here: