v2.37
 
How to implement a plugin

Overview

This page describes the design of Renga's plugin system and contains the instructions to help you author Renga extensions. Please see the sample plugin implementations in [RengaCOMSDK dir]/Samples.

Plugin system overview

A basic Renga plugin consists of:

  • the plugin's binary file, which is a regular Windows dynamic-link library or a .NET assembly.
  • the description file - an XML file named with the .rndesc extension, which contains plugin description and loading instructions.

Each description file should be placed into its own subdirectory in the ‘Plugins’ subdirectory of Renga's installation folder. Names of the description file should match the plugin's folder name. For example, for a plugin located in [RengaInstallation]/Plugins/Sample folder, the description file should be [RengaInstallation]/Plugins/Sample/Sample.rndesc.

All plugins are loaded into the Renga process on application start and are unloaded on exit.

Description file contents

The plugin description file contents are as follows:

<RengaPlugin>
<Name>Sample Plugin</Name> <!-- Displayed plugin name -->
<Version>1.0</Version> <!-- Plugin version -->
<Copyright>Copyright text</Copyright> <!-- Copyright information -->
<RequiredAPIVersion>2.30</RequiredAPIVersion> <!-- Minimum required version of Renga API -->
<PluginType>net</PluginType> <!-- Plugin type (can be in any case) -->
<!-- "net" or ".net" for plugins written on .NET Framework (C#, C++/CLI) -->
<!-- "net8" or ".net8" for plugins written on .NET 8 (C#, C++/CLI) -->
<!-- "cpp", "vcpp" or "c++" for plugins written on Visual C++. Optional, defaults to "cpp" -->
<PluginFilename>Sample.dll</PluginFilename> <!-- Path to the plugin's binary file, either relative to the folder containing the .rndesc file or an absolute one -->
<Vendor>Renga</Vendor> <!-- Vendor of the plugin -->
</RengaPlugin>

What do I need to use the Renga API?

The requirements to start using the API are as follows:

  • Installed Renga;
  • Renga Software Development Kit (download);
  • Microsoft Visual Studio 2015 or newer.

How to create a new plugin in C#

In order to create your own plugin in C# create a new class library project in Microsoft Visual Studio.

Then you need to add to your project a reference to RengaCOMAPI.tlb from [RengaCOMSDK dir]/tlb folder.

If you are creating a .Net Framework plugin, you need to add to your project a reference to Renga.NET.PluginUtility.dll and if you are creating a .Net 8 plugin, you need to add a reference to Renga.NET8.PluginUtility.dll from [RengaCOMSDK dir]/Net folder.

In the library add a class implementing the Renga.IPlugin interface (both explicit and implicit implementations are supported).

The interface has two methods to implement in the plugin:

  • bool Renga.IPlugin.Initialize(string pluginFolder), which is called on plugin initialization;
  • void Renga.IPlugin.Stop(), which is called when the plugin is being unloaded.

How to create a new plugin in C++

In order to create your own plugin in Visual C++ create a new dynamic-link library (DLL) project in Microsoft Visual Studio.

In the library add a class implementing plugins::IPlugin. It has two methods to implement in the plugin:

Then place the EXPORT_PLUGIN(YourPluginClassName); macro after the plugin class declaration.

How to install a plugin

You need to place the plugin's description file into the corresponding directory of Renga's installation (see the Plugin system overview section above). Any other files, including the plugin binary itself, may be placed arbitrarily. Renga locates the binary file depending on the path stated in the PluginFilename tag of the description file. Remember to deploy the Renga.NET.PluginUtility.dll assembly (for .NET Framework plugins) or Renga.NET8.PluginUtility.dll assembly (for .NET 8 plugins) and any other resources your plugin might depend on.

You may also want to create your own installer for the plugin. In this case you should determine the location of the Renga installation. You can determine it using the "InstallLocation" attribute in the following registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\{5129DC7E-FC1E-45DD-B9C9-82940798C85E} for Renga Standard HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\{AD5DA106-F1CF-453A-9E44-510164E2F932} for Renga Professional

If the plugin doesn't load

If some errors prevent the plugin from loading successfully, you can check the application log for details. The log is stored in %localappdata%/Renga Software/Renga/AecApp.log.