WinForms Host

This is an Article about Hydra

New page awaiting review

Please do not rely on the content. After review, the page will be indexed and may have its name changed.
If you have suggestions for this page, please send them to us: email.

Hydra host is an application that provides an ability to load (host) and use exposed functionality of a plugin. Host applications is able to use all plugins supported by the Hydra (with an exception of RemObjects SDK plugins).

Windows Forms (WinForms) is a Microsoft's visual component-based framework, and Hydra WinForms hosts is second most used host applications for host applications.

In this article we will describe how to create a new WinForms host application, and talk about what features it provides and how they can be used.

Getting Started

Hydra host application, basically, is a common application. Our wizards can create this application for every supported platforms, so in result you can have a WinForms, VCL or FireMonkey HD applications.

By default there is not much changes in these applications is done by wizard, the main one is that it adds a module manager component which allows you to interact with plugins. However for some host project it adds additional items, they will be described in the "Review the resulting project" section.

All this allows you easily convert your existing project into the Hydra host project.

Now we can describe how to create and setup a Hydra host project.

Working with Wizard

Creating a host application is a simple thing, to do this select File -> New -> Project in the Visual Studio menu, choose language you need (we provide templates for C#, VB.NET and Oxygene for .NET) then in the RemObjects Hydra category choose Host Application:

In this dialog you also need to enter project name and destination folder.

And basically this is it, after finishing its work wizard will create a new application that is ready to work with Hydra plugin modules.

Review the resulting project

As we've said previously host application is a common Windows Forms Application, so when wizard work is done you will receive same project as you would with a regular template.

• Program.cs - is an entry point of the application, contains code that runs your application and main form.

• Main.cs - main form of the application, it is a regular WinForm.

For a main form wizard also adds a new component - module manager, this is a key component that allows you to manage your plugins, we will describe it later in this article.

One more thing, in the AssemblyInfo.cs we set following assembly attribute:

[assembly: ComVisible(true)]

Please do not change this attribute, it will allow plugins to access to the interfaces exposed by the host application.

Using the host

By now you will have a complete project that with a little bit of an additional work can be used to work with plugins. A host application can load any plugin module, regardless of what platform it was developed with, allowing you to mix Delphi and .NET functionality in the same application, further in this article we will describe how to do this.

As we've showed host application is a common WinForms application, main form generated by a wizard is inherited from standard System.Windows.Forms.Form and provides exactly the same design surface, so you can work with the host application like you do with any regular WinForms application.

Below we will describe a most common way to use host, but first let us make a note. One of the major part of the Hydra framework is a custom interfaces. Custom interfaces is a user defined interfaces that can be used in the cross-platform environment (for example they can be shared between WinForms host and a Delphi plugin) to receive access to a data or to call host or plugin methods. When we will talk about things like "accessing host methods" we will refer to the custom interfaces, but since this is large topic we can't cover it in this article, so if you feel like you need to use them, please take a look at these two articles:

• Interface based communication - general information about the custom interfaces.
• Passing interfaces between Host and Plugins - describes how to write and use custom interfaces.

For host applications, the ModuleManager component is a key component that allows you to perform the task of managing plugin modules. So, let us start by giving a short description of module manager members.

Module Manager Members

As we've said module manager is the key component of the Hydra host application, here is what he allows you to do:

Methods:

• LoadModule - loads a module with specified file name, optionally can create a new AppDomain for .NET plugins or use a global one. Returns a reference to a LoadedModule. This method will automatically define a plugin module type and will call on the module manager methods to load specific module, however you can do this manually by using methods such as LoadUnmanagedModule, LoadFiremonkeyModule etc.

• CreateInstance - creates an instance of a plugin with specified name or descriptor. CreateInstance returns a reference to an IHYCrossPlatformPlugin.

• UnloadModule - unloads plugin module by using reference to a module.

• Host - this property allows you to set a reference to an object that implements IHYCrossPlatformHost this object will be automatically assigned to every new loaded modules and created instances.

• Plugins - allows you to access to a list of plugin descriptors from all modules.

• Modules - a collection of all modules loaded by the module manager.

Events that reacts on various loading events:

• ModuleLoading
• ModuleLoaded

Modules and Descriptors

As you can see module manager provides couple of members that allows you to access to the modules and descriptors. So let's find out what is this.

Every plugin that was loaded by the module manager is represented by a special class that describes this module. All modules is descendants of the LoadedModule and allows you to get access to module data.

LoadedModule allows you to access to following data:

• FileName - file name of the loaded module.
• ModuleController - holds reference to an instance of a plugin's module controller (IHYCrossPlatformModuleController).
• Plugins - allows you to access to a list of plugin descriptor, unlike module manager property this one allows you to get descriptors only for this specific module.

Plugin descriptors is used to describe a plugin that is stored in the module. In most cases you will use PluginDescriptor class to deal with the descriptors.

PluginDescriptor provides access to a set of data that describes plugin:

• Name - holds name of the plugin, you can use it to create an instance of a plugin.
• MajorVersion and MinorVersion - holds user specified version of a plugin.
• Description - holds a string that allows you to read plugin description.
• UserData - string that sores custom data.
• RequiredPrivilege - string that defines privileges that required to create this plugin.
• CheckPluginType - method that allows you to check if plugin is derived from a specified type.
• CheckPluginInterface - method that allows you to check if plugin implements specified interface.
• CheckPluginAttribute - method that allows you to check whether plugin has a specified attribute.

Please note that MajorVersion, MinorVersion, Description and UserData is optional fields, they can be defined on the plugin side if you need such info, by default they are empty.

Custom Interfaces

We won't dig deep into details of custom interfaces usage (please refer to this article - Passing interfaces between Host and Plugins), but we will describe how host deals with them.

By default your host application doesn't implement any specific hosting interfaces, so in order to allow plugins to access to a host we first need to define a host object.

Basically host object is an object that implements IHYCrossPlatformHost interface, this is interface doesn't have any methods it just shows that object is a host.

Most common way is implement this interface in your main form, like this:

public partial class Main : Form, IHYCrossPlatformHost
  {
    public Main()
    {
      InitializeComponent();
    }
  }

But of course you can have a dedicated object. After you have a host object you need to assign it to plugin instances, there is couple of ways to do this, first is to assign it to the module manager's Host property.

moduleManager.Host = this; //in case when your main form is a host object

This will allow module manager to assign it to every module that is being loaded and to every instance that you will create. The other way is to assign individually to plugin and module controller instances:

var Module = moduleManager.LoadModule("Plugin.dll");
  Module.ModuleController.Host = this;
  var Instance = moduleManager.CreateInstance("MyPlugin");
  Instance.Host = this;

Both these ways does the same job, but first is a little bit simpler and second gives you more control over the process.

Usage Example

While plugins does not require any special setup, you need to perform couple steps in a host application to be able to load your plugins, for example:

public partial class Main : Form, IHYCrossPlatformHost
  {
    public Main()
    {
      InitializeComponent();
    }

    private IHYCrossPlatformPlugin Instance = null; 

    private void Main_Load(object sender, EventArgs e)
    {
      moduleManager.LoadModule("Plugin.dll");
      Instance = moduleManager.CreateInstance("MyPlugin");
      hostPanel1.HostPlugin(Instance as IBasePlugin);
    }
  }

Let's review this example step-by-step:

• IHYCrossPlatformPlugin Instance - this is a reference to an instance of a plugin. You can use it to perform any specific actions with a plugin. In case you need a specific plugin (visual or non-visual) you can cast this instance to a desired interface, for example:

if (Instance is IHYCrossPlatformNonVisualPlugin)
    (Instance as IHYCrossPlatformNonVisualPlugin).Start();

• moduleManager.LoadModule("Plugin.dll"); - this method allows you to load a plugin module with a specified path. Module manager will automatically detect type of a module and will use appropriate method.

• Instance = moduleManager.CreateInstance("MyPlugin"); - this method will create an instance of plugin with specified name and assign this instance to a Instance variable that we defined above.

• hostPanel1.HostPlugin(Instance as IBasePlugin); - this method is used for a visual plugins, it can show plugin content in a special container called HostPanel.

This is it, with just a few lines of code host is able to load, create and show your visual plugin.

Other Articles

Product Articles — Data Abstract — RemObjects SDK  

Product: RemObjects Hydra
Current version: Hydra 4.0

Glossary — Architecture — Articles — Library — Samples