How to ... Create HeuristicLab Plugins Step by Step

This quick guide will help you to develop your own HeuristicLab plugins. We are assuming that you are using Visual Studio 2010 as development environment. For a more detailed description of how to create plugins for the development trunk see UsersHowtosImplementPlugins.

Prerequisites

We assume that you have checked out and built (see here? how to build the sources) the HeuristicLab sources. Your working directory should look something like this:

In this case the complete path is C:\HL\trunk\.

A new solution

We will now create a new Visual Studio solution and project which will become the HeuristicLab plugin.

Start Visual Studio and create a new C# Class Library project:

Note that we place the solution in the HL folder. It's a good idea to place your solution near the the HeuristicLab source and use relative paths whenever possible (e.g. references, output path, ...). This makes it more easy to develop if you are more then 1 person working on the plugin and the project settings have to work on the computers of your colleagues.

Your working directory should now look something like this:

Configuring the project

AssemblyInfo

There are two important attributes that you have to configure in the AssemblyInfo file. The AssemblyVersion is set to the same value as the HeuristicLab Version by convention. It should only be incremented if you use the HL serialization mechanism and want to signal a persistence break between two version. AssemblyFileVersion can be set without any restrictions:

References

Every HL plugin has at least a reference to PluginInfrastructure as this is needed for the Plugin.cs file. Therefore add a reference to this plugin:

Plugin file

Visual Studio has already created a cs file when creating the project. Rename this file to Plugin.cs:

Every HeuristicLab plugin needs a Plugin file. This file contains information about the plugin itself (Name, Filename, Version) and it's dependencies. The dependencies are used by the plugin infrastructure to check if all required plugins for a certain plugin are found. Therefore write the following code in your Plugin.cs file:

or copy:

  using HeuristicLab.PluginInfrastructure;

namespace HeuristicLab.Algorithms.MyAlgorithm {
  [Plugin("HeuristicLab.Algorithms.MyAlgorithm", "1.0.0.0")]
  [PluginFile("HeuristicLab.Algorithms.MyAlgorithm.dll", PluginFileType.Assembly)]
  public class MyAlgorithmPlugin : PluginBase {
  }
}

Build path

The last step is to adjust the output path for the plugin. Because we don't want to copy the plugin file by hand to the HeuristicLab bin directory, we set the output path to this location so that it gets directly built there. Right click on your project, choose Properties and then the Build register card:

The output path is set as a relative path. This makes it possible for other people who may have a different directory layout (e.g. no C:\HL\) to also build the project.

Testing the plugin

You should now be able to compile your project and find your plugin file in the HeuristicLab bin folder. To test if everything works and the plugin infrastructure recognizes the plugin, start HeuristicLab an double click the Plugin Manager application in the Starter dialog. Your plugin should be listed under "Active Plugins":