Developer HowTo

1. Developer Guidelines

CrypTool 2 is built using .NET and the Windows Presentation Foundation (WPF). Before you can start writing code and adding to the development of the project, a few things need to be considered. To make this process easier, please read through this document and follow the instructions closely. This document exists to help get you started by showing you how CrypTool 2 plugins are built in order to successfully interact with the application core. We have tried to be very thorough, but if you encounter a problem or error that is not described here, please let us know. Not only do we want to help get you up and running, but we also want to add the appropriate information to this guide for the benefit of other future developers.

In this first chapter we will describe all steps necessary in order to compile CrypTool 2 on your own computer. This is always the first thing you need to do before you can begin developing your own plugins and extensions. The basic steps are:

• Getting all prerequisites and installing them
• Accessing and downloading the source code with git
• Compiling the latest version of the source code

1.1 Prerequisites

Since CrypTool 2 is based on Microsoft .NET, you will need a Microsoft Windows environment. (Currently no plans exist for porting this project to Mono or other platforms.) We have successfully tested with Windows 7, Windows 8, Windows 10, and Windows 11.

Since you are reading the developer guidelines, you probably want to develop something. Hence, you will need a development environment. In order to compile our sources you need Microsoft Visual Studio or the free Microsoft Visual Studio Community Edition. Make sure to always install the latest service packs for Visual Studio.

In order to run or compile our source code you will need at least the Microsoft .NET. Usually the installation of Visual Studio also installs the .NET framework, but if you do not have the latest version, you can get it for free from Microsoft’s website. Once the framework has been installed, your development environment should be ready for our source code.

1.2 Clone the GitHub repository

Please read the Build instructions how to clone and build your own CT2.

1.3 Download the plugin template

Before you can start implementing a new plugin, you will need to download the CrypTool 2 plugin template. The most current version of this template is located in our CrypTool 2 repository, and can be downloaded here: (todo: add new template).

The template can be installed by (todo: write installation guide for template)

2. Plugin / Component Implementation

In this chapter we provide step-by-step instructions for implementing your own CrypTool 2 plugin. We shall assume that you have already retrieved the CrypTool 2 source code from the GitHub repository, set up Visual Studio or Visual Studio Community to build CrypTool 2, and you have placed the plugin template in the right place.

2.1 Create a new project

Open the CrypTool 2 solution, right click in the solution explorer on CrypPlugins and select Add --> New Project. In the dialog window, select Visual C# --> CrypTool 2 Plugin as project template and enter a unique name for your new plugin project (such as Caesar in our case). The next step is crucial to ensure that your plugin will compile and run correctly: select the subdirectory CrypPluginsExperimental\ as the location of your project:

Figure 2.1: Creating a new CrypTool 2 plugin project

As the project basics are already correctly set up in the template, you should now be able to compile the new plugin. First of all, rename the two files in the solution explorer to something more meaningful, for example Caesar.cs and CaesarSettings.cs. You should choose a descriptive name for your project. Do not delay this for later, since renaming the project later can become cumbersome:

Figure 2.2: Items of a new plugin project

2.2 Adapt the plugin skeleton

If you look into the two C# source files (Figure 2.2), you will notice a lot of comments marked with the keyword HOWTO. These are hints as to what you should change in order to adapt the plugin skeleton to your custom implementation. Most HOWTO hints are self-explanatory and thus we won’t discuss them all.

2.3 Defining the attributes of the Caesar class

The next thing we will do in our example Caesar.cs is define the attributes of our class. These attributes are used to provide necessary information for the CrypTool 2 environment. If they are not properly defined, your plugin won’t show up in the application user interface, even if everything else is implemented correctly.

Attributes are used for declarative programming and provide metadata that can be added to the existing .NET metadata. CrypTool 2 provides a set of custom attributes that are used to mark the different parts of your plugin. These attributes should be defined right before the class declaration

2.3.1 The [Author] attribute

The [Author] attribute is optional, meaning that we are not required to define it. The attribute can be used to provide additional information about the plugin developer (or developers, as the case may be). This information will appear in the TaskPane. We will define the attribute to demonstrate how it should look in case you want to use it in your plugin.

Figure 2.3: The definition for the [Author] attribute

All of these elements are optional and may be null:

• Author — the name of the plugin developer.
• Email — the email address of the plugin developer, should he or she wish to be available for contact.
• Institute — the organization, company or university with which the developer is affiliated.
• URL — the website of the developer or of his or her institution.

2.3.2 The [PluginInfo] attribute

The [PluginInfo] attribute provides necessary information about the plugin, and is therefore mandatory. The information defined in this attribute appears in the caption and tool tip window. The attribute is defined as follows:

Figure 2.4: Multilingual definition of [PluginInfo] attribute

This attribute has the following parameters:

• Resource File — the namespace and class name of an associated resource file .resx. This element is optional and used only if the plugin provides multilingual strings (see also Section 3).
• Caption — the name of the plugin, or, if using a resource file, the name of the field in the file with the caption data. This element is mandatory.
• ToolTip — a description of the plugin, or, if using a resource file, the name of the field in the resource file with the tooltip data. This element may be null.
• DescriptionURL — the local path of the user documentation file (XML file, see Section 4). This element may be null.
• Icons — an array of strings to define all the paths of the icons used in the plugin (i.e. the plugin icon described in Section 2.4). This element may be null.