Quick guide: Create a new plugin using Visual Studio

We assume that you have obtained the source as described in Quick guide: Download and build sources. We assume your directory structure looks as follows:

A new solution

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

• In Visual Studio select "File > New > Project..." or press <Ctrl+Shift+N>
• Use the "Class Library" template
• Make sure "Create directory for solution" is checked
• Use "HeuristicLab.GreatIdea.ThePlugin" as name
• Use "GreatIdea" as solution name
• Choose the extension folder as location

Your working directory should now look something like this:

Configuring the project

Project properties

In the project's properties we configure: Assembly information, build, debug, and signing. If you open the properties please also make sure the target framework is set to .NET Framework 4.6.1.

Assembly information

We set the assembly version to the same value as the current HeuristicLab version by convention. It should only include major and minor, build and revision should always remain 0. In the official HeuristicLab repository the revision part is synchronized with the SVN revision number, it can be simply set to 0 in our case. The assembly file version can include the whole version string.

Build

We want to automatically put the plugin into the StableRoot\bin folder when we compile it. On the "Build" tab change the configuration box from "Active (Debug)" to "All Configurations" and enter ..\..\..\stable\bin in the output path.

Debug

On the "Debug" tab choose "Start external program" and select HeuristicLab.exe inside StableRoot\bin - this setting is stored in the .csproj.user file.

Signing

Activate "Sign the assembly" and create a new key or use the HeuristicLab.snk inside the plugins of StableRoot. Otherwise call the new key "TheKey", but deselect the password option.

Save and close the project's properties. These changes ensure that the generated plugin is automatically added as a plugin to the HeuristicLab build and that we can use our solution to start a debugging session (shortcut <F5>). Now, we want to make this class library a HeuristicLab plugin.

References

Every plugin has at least a reference to the PluginInfrastructure as this is needed to identify as a plugin.

• For the project add a reference to HeuristicLab.PluginInfrastructure.dll in StableRoot\bin
• Important: Since we're building into a common bin folder you have to open the properties of this reference and set "Copy Local" to false

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 we will write the following code in our Plugin.cs file:

using HeuristicLab.PluginInfrastructure;

namespace HeuristicLab.GreatIdea.ThePlugin {
  [Plugin("HeuristicLab.GreatIdea.ThePlugin", "Provides an implementation of a great idea", "3.3.9.0")]
  [PluginFile("HeuristicLab.GreatIdea.ThePlugin.dll", PluginFileType.Assembly)]
  public class Plugin : PluginBase {
  }
}

Important: The plugin class needs to derive from HeuristicLab.PluginInfrastructure.PluginBase so that the dll is realized as a plugin. The attributes specify the details of the plugin and which files it provides. The filename given in PluginFile has to be the same as the assembly output filename in the "Application" tab of the project's properties.

Important: Changing major or minor version numbers in the course of development marks a breaking change to previously saved files. If HeuristicLab wants to load an item of a plugin with version 3.3.8 it will accept the same plugin in version 3.3.9 to open it. However, it will reject the plugin when its major or minor is different (e.g. 3.2.7, 3.4.3 or 4.0.1). The "Assembly file version" is not used by HeuristicLab and can be set without any restrictions.

Testing the plugin

• Build the project and press <Ctrl+F5> to start it without a debugger attached
• You will see the starter window again, but you already know the switches to hide it
• Inside the starter open the "Plugin Manager" and see that it is correctly loaded

Now we have created an empty plugin that we can use to implement a new great idea. Please refer to the Documentation pages and the various HowTos on how to write views, operators, algorithms, etc.

For HL core developers

HL core developers must check out the trunk, branches and stable folders, though not all of the individual branches need to be checked out. New functionality should be developed in a branch and not in the trunk. The merge back into the trunk will occur, after a new feature reaches maturity. This requires at least a code review and clearance by head developer Stefan Wagner!

• SVN repository main: ​https://src.heuristiclab.com/svn/core (use "Choose Items" in the checkout dialog to limit the depth of the branches)

If you develop new projects, they must reside inside a directory that denotes major.minor version. If a plugin is named HeuristicLab.Problems.Mine, the project files should be placed inside HeuristicLab.Problems.Mine\3.3\HeuristicLab.Problems.Mine-3.3.csproj. Note that the version number is also appended to the .csproj file.

Configuring the project properties

Once a project has been created and the directory structure has been adapted, the project properties need to be adjusted.

• The output name of the project should include the version number, e.g. HeuristicLab.Problems.Mine-3.3
• The default namespace should be free from version numberings, e.g. HeuristicLab.Problems.Mine
• The target framework needs to be set to .NET Framework 4.6.1.
• On the build tab please choose the appropriate output path. In case a branch is merged into the trunk this should be changed as well!
  • ..\..\bin for projects inside the trunk
  • ..\..\..\..\trunk\sources\bin\ for projects inside the branches directory
• We typically use pre-build events for automatic versioning. This expects a Plugin.cs.frame and Properties\AssemblyInfo.cs.frame file to be present in your project (see below "Create frame files"). Typically, this is the pre-build command:

  set Path=%Path%;$(ProjectDir);$(SolutionDir)
  set ProjectDir=$(ProjectDir)
  set SolutionDir=$(SolutionDir)
  set Outdir=$(Outdir)
  
  call PreBuildEvent.cmd
  

  • If you are on a branch, copy the PreBuildEvent.cmd to your branch directory

Adding references to a project

If you are working within the HeuristicLab solution, you can reference other projects through project references. If you are working in your own solution, reference the assemblies in trunk\sources\bin\. In both cases, if you add references, switch the "Copy local" option to false in the properties of the reference. Otherwise your build might break!

Use the configuration manager

Create configurations for debug and release builds and all platforms (Any CPU, x86, x64). Make sure that the respective solution configurations target the right configuration of your projects and that they are checked.

Create frame files

Each HeuristicLab plugin has two frame template files, AssemblyInfo.cs.frame and Plugin.cs.frame. We use these .frame files and SubWCRev to automatically convert those into .cs files and add the repository version number to the revision-version.

• AssemblyInfo.cs.frame --> create by duplicating AssemblyInfo.cs
  • Make sure AssemblyTitle, AssemblyDescription, etc. are all set
  • AssemblyVersion --> should be set to e.g. 3.3.0.0 and touched only when major or minor version changes
  • AssemblyFileVersion --> should be set to e.g. 3.3.10.$WCREV$
• Plugin.cs.frame
  • Used to replace your plugin version number with the build number on SVN commit, e.g. 3.3.10.$WCREV$
• If you check in your sources make sure to exclude and ignore AssemblyInfo.cs and Plugin.cs on commit

Configuring the plugin file

• Plugin attribute, e.g. [Plugin("HeuristicLab.Problems.Mine", "Description of my problem", "3.3.10.$WCREV$")]
• PluginDependencies --> Please make sure that you list all referenced plugins. There is a unit test that checks if you have included all or if you have specified too many (your plugin must be referenced by the unit test project)
  • Version numbers: Major and minor must be used for HeuristicLab plugins, e.g. 3.3 or 3.4, additional version information may be required for some external libraries, e.g. [PluginDependency("HeuristicLab.ALGLIB", "3.7.0")]

Trunk integration

When your branch has matured and is ready for trunk integration, you should remove your branch and add your projects to the trunk solution.

• Remember that the output path for trunk projects is different, change it!
• Convert all references to project references (don't forget to set Copy Local to false!)
• Add your project to the build dependencies of the HeuristicLab-3.3 project to ensure that your project is also built on every rebuild. To do this right click on the solution, Properties, Project Dependencies, select the HeuristicLab-3.3 project.
• Add your plugin as a reference to the HeuristicLab.Tests project
• Sign the project with the HeuristicLab key (if you haven't done so already)
• Check all source files and Designer generated source files for a GPL license header
• If you want to add a custom resource (say, an image), it belongs into HeuristicLab.Common.Resources. Mail Stefan Wagner if you require custom resources. Note that the image should have a license that is compatible with the GPL.