source: trunk/Documentation/PluginHowTo/part2.tex

Last change on this file was 8983, checked in by kopal, 8 months ago

Complete CrypTool 2 project

  • renamed "Cryptool" namespace to "CrypTool" namespace
File size: 13.8 KB
Line 
1\chapter{Plugin Implementation}
2\label{sec:PluginImplementation}
3In 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 SVN repository, set up Visual Studio 2013 or Visual Studio Community 2015 to build CrypTool 2, and you have placed the plugin template in the right place.
4
5\section{Create a new project}
6\label{sec:CreatingANewProject}
7
8Open the CrypTool 2 solution, right click in the solution explorer on \textit{CrypPlugins} and select \textit{Add~$\rightarrow$ New Project}. In the dialog window, select \textit{Visual C\# $\rightarrow$ CrypTool 2 Plugin} as project template and enter a unique name for your new plugin project (such as \textit{Caesar} in our case). The \textbf{next step is crucial} to ensure that your plugin will compile and run correctly: select the subdirectory \texttt{CrypPluginsExperimental\textbackslash} as the location of your project (Figure~\ref{fig:vs_create_new_project}).
9
10\begin{figure}[h!]
11        \centering
12                \includegraphics{figures/vs_create_new_project.png}
13        \caption{Creating a new CrypTool 2 plugin project}
14        \label{fig:vs_create_new_project}
15\end{figure}
16
17As 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 \texttt{Caesar.cs} and \texttt{CaesarSettings.cs}. You should choose a descriptive name for your project. \textbf{Do not delay this for later}, since renaming the project later can become cumbersome.
18
19\begin{figure}[h!]
20        \centering
21                \includegraphics{figures/caesar_project.png}
22        \caption{Items of a new plugin project}
23        \label{fig:caesar_project}
24\end{figure}
25
26\section{Adapt the plugin skeleton}
27\label{AdaptingThePluginSkeleton}
28
29If you look into the two C\# source files (Figure~\ref{fig:caesar_project}), you will notice a lot of comments marked with the keyword \texttt{HOWTO}. These are hints as to what you should change in order to adapt the plugin skeleton to your custom implementation. Most \texttt{HOWTO} hints are self-explanatory and thus we won't discuss them all.
30
31\section{Defining the attributes of the Caesar class}
32\label{sec:DefiningTheAttributesOfTheCaesarClass}
33
34The next thing we will do in our example \textit{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.
35
36Attributes 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.
37
38\subsection{The \protect\textit{[Author]} attribute}
39\label{sec:TheAuthorAttribute}
40
41The \textit{[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.
42
43\begin{figure}[h!]
44        \centering
45                \includegraphics[width=.90\textwidth]{figures/attribute_author.jpg}
46        \caption{The definition for the \textit{[Author]} attribute}
47        \label{fig:attribute_author}
48\end{figure}
49
50All of these elements are optional and may be null:
51
52\begin{itemize}
53        \item \textit{Author} --- the name of the plugin developer.
54        \item \textit{Email} --- the email address of the plugin developer, should he or she wish to be available for contact.
55        \item \textit{Institute} --- the organization, company or university with which the developer is affiliated.
56        \item \textit{URL} --- the website of the developer or of his or her institution.
57\end{itemize}
58
59\subsection{The \protect\textit{[PluginInfo]} attribute}
60\label{sec:ThePluginInfoAttribute}
61
62The \textit{[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:
63
64\begin{figure}[h]
65        \centering
66                \includegraphics[width=1.00\textwidth]{figures/attribute_plugininfo.png}
67        \caption{Multilingual definition of \textit{[PluginInfo]} attribute}
68        \label{fig:attribute_plugininfo}
69\end{figure}
70
71\noindent This attribute has the following parameters:
72
73\begin{itemize}
74        \item \textit{Resource File} --- the namespace and class name of an associated resource file \textit{.resx}. This element is optional and used only if the plugin provides multilingual strings (see also Section~\ref{sec:Internationalization}).
75        \item \textit{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.
76        \item \textit{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.
77        \item \textit{DescriptionURL} --- the local path of the user documentation file (XML file, see Section~\ref{sec:Documentation}). This element may be null.
78        \item \textit{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 \ref{sec:AddingAnIconToTheCaesarClass}). This element may be null.
79\end{itemize}
80
81For your first plugin, it's recommended to skip the resource file and use English strings for \textit{Caption} and \textit{ToolTip}. If you're ready to add multi-language support to your plugin, take a look at Section~\ref{sec:Internationalization}.
82
83The \textit{DescriptionURL} element defines the location path of the user documentation file (custom XML format), e.g. \texttt{"assemblyname/path/filename.xml"}. Take a look at Section~\ref{sec:Documentation} to see how to create a documentation file.
84
85The \textit{Icons} parameter is an array of strings and should be provided in format: \\
86\texttt{new[] \{ "assemblyname/path/filename.png" \} }
87
88Don't forget to add all files to your project in Visual Studio. See Section~\ref{sec:AddingAnIconToTheCaesarClass} how to do this.
89
90\subsection{Set algorithm category}
91\label{sec:AlgorithmCategory}
92
93In the CrypTool 2 user interface plugins are grouped by their algorithm category, for example hash function, symmetric cipher, and so on. To set the category, you must specifiy the attribute \textit{[ComponentCategory]}. Multiple categories are allowed.
94
95\begin{lstlisting}
96    [ComponentCategory(ComponentCategory.CiphersClassic)]
97    public class ExamplePluginCT2 : ICrypComponent
98                {
99\end{lstlisting}
100
101\subsection{Adding parameters to the CaesarSettings class}
102\label{sec:AddingControlsToTheCaesarSettingsClass}
103
104If your component provides user-configurable parameters, you can set them up in the settings class derived from \textit{ISetting}. This comprises text input fields, number fields, combo boxes, radio buttons and so on. Take a look at \textit{CaesarSettings.cs} to see some examples for user-configurable parameters.
105
106If you don't want to provide any parameters, delete the class and return null for the \textit{Settings} property:
107
108\begin{lstlisting}
109        public ISettings Settings
110        {
111                get { return null; }
112        }
113\end{lstlisting}
114
115\section{Add an icon file}
116\label{sec:AddingAnIconToTheCaesarClass}
117
118Your component is represented in the CrypTool 2 user interface by an icon. You should add a custom icon file, but if you don't, the template uses a generic default one.
119
120The proper image size is 40x40 pixels, but since the image will be rescaled if necessary, any size is technically acceptable. Once you have saved your icon, you should add it directly to the project or to a subdirectory with it. Right-click on your plugin project or any subfolder and select \textit{Add $\rightarrow$ Existing Item}.
121
122\begin{figure}[h!]
123        \centering
124                \includegraphics{figures/add_existing_item.jpg}
125        \caption{Adding an existing item}
126        \label{fig:add_existing_item}
127\end{figure}
128\clearpage
129
130Choose \textit{Image Files} as the file type and select your newly-created icon for your plugin.
131
132\begin{figure}[h!]
133        \centering
134                \includegraphics{figures/choose_icon.jpg}
135        \caption{Selecting the image file}
136        \label{fig:choose_icon}
137\end{figure}
138\clearpage
139
140It's \textbf{necessary} to set the icon file as a \textit{Resource} in the file properties. Right-click on your icon file, click \textit{Properties} and set the \textit{Build Action} to \textit{Resource}.
141
142\begin{figure}[h!]
143        \centering
144                \includegraphics{figures/icon_properties.jpg} \includegraphics{figures/icon_build_action.jpg}
145        \caption{Go to \textit{Properties}, select \textit{Build Action} to \textit{Resource}}
146        \label{fig:icon_properties}
147\end{figure}
148
149\section{Input and output dockpoints}
150\label{sec:InputAndOutputDockpoints}
151
152Next we will define some class properties to be used as data input and output connectors of the component. Each property is defined by a \textit{[PropertyInfo]} attribute:
153
154\begin{itemize}
155        \item \textit{direction} --- defines whether this property is an input or output property:
156        \begin{itemize}
157                \item \texttt{Direction.Input}
158                \item \texttt{Direction.Output}
159        \end{itemize}
160        \item \textit{caption} --- a short caption of the data property shown in the editor. May be either a text or a key referring to a multilingual resource file (see Section~\ref{sec:Internationalization}).
161        \item \textit{tooltip} --- similar as a caption, but more descriptive. May be either a text or a key referring to a multilingual resource file.
162        \item \textit{mandatory} --- this flag determines whether an input must be attached by the user to use the plugin. If set to \texttt{true}, an input connection will be required or else the plugin will not be executed in the workflow chain. If set to \texttt{false}, connecting an input is optional. As this only applies to input properties, if the direction has been set to \texttt{Direction.Output}, this flag will be ignored.
163
164\end{itemize}
165
166Here is an example:
167\clearpage
168
169\begin{lstlisting}
170[PropertyInfo(Direction.InputData, "Text input", "Input a string to be processed by the Caesar cipher", false)]
171public string InputString
172{
173        get;
174        set;
175}
176\end{lstlisting}
177
178The output data property (which handles the input data after it has been encrypted or decrypted) may look as follows. CrypTool 2 does not require implementing set methods for output properties, as they will never be called from outside the plugin (it won't hurt, though).
179
180\begin{lstlisting}
181[PropertyInfo(Direction.OutputData, "Text output", "The string after processing with the Caesar cipher", false)]
182public string OutputString
183{
184        get;
185        set;
186}
187\end{lstlisting}
188
189You can basically use any data type. If your component deals with potentially large amounts of binary data, you may want to use the \textit{ICrypToolStream} data type instead of \textit{byte[]}. More information about how to use the \textit{ICrypToolStream} can be found in the CrypTool 2 wiki: \url{https://trac.ct2.cryptool.org/wiki/ICrypToolStreamUsage}. You will need to include the namespace \textit{CrypTool.PluginBase.IO}. Here's an example how to use \textit{ICrypToolStream} for an output property:
190
191\begin{lstlisting}
192[PropertyInfo(Direction.OutputData, "CrypToolStream output", "The raw CrypToolStream data after processing with the Caesar cipher", false)]
193public ICrypToolStream OutputData
194{
195        get
196        {
197                if (OutputString != null)
198                {
199                        return new CStreamWriter(Encoding.UTF8.GetBytes(OutputString));
200                }
201                return null;
202        }
203}
204\end{lstlisting}
205
206\section{Implement your algorithm}
207\label{sec:ImplementingTheActualAlgorithm}
208
209Algorithmic processing should be done in the \textit{Execute()} function. Here's a boilerplate example of how it could look like (example simplified for demonstration purposes):
210
211\begin{lstlisting}
212public void Execute()
213{
214  if (string.IsNullOrEmpty(InputString))
215                return;
216       
217        try
218        {
219                ProgressChanged(0, 100);  // set progress bar to 0%
220                if (settings.Action == CaesarMode.encrypt)
221                {
222                        OutputString = Encrypt(InputString);
223                }
224                else
225                {
226                        OutputString = Decrypt(InputString);
227                }
228                ProgressChanged(100, 100); // set progress bar to 100%
229               
230                OnPropertyChanged("OutputString"); // push output to editor
231        }
232        catch(Exception ex)
233        {
234          // log error
235                GuiLogMessage("Failure: " + ex.Message, NotificationLevel.Error);
236        }
237}
238\end{lstlisting}
239
240You \textbf{must} announce all changes to output properties by calling \textit{OnPropertyChanged} with the correct property name. This step is crucial to correctly pass output data to other components.
241
242You should set the progress of an execution by calling \textit{ProgressChanged}. You may use interim progress updates for long-running computations in a loop.
243
244You may use \textit{GuiLogMessage} to show errors, warnings or informational messages to the user.
245
246\begin{figure}[h]
247        \centering
248                \includegraphics[width=1.00\textwidth]{figures/status_bar.jpg}
249        \caption{An example status bar}
250        \label{fig:status_bar}
251\end{figure}
252
253\section{Create an editor template}
254\label{DrawingTheWorkfloweOfYourPlugin}
255
256Each plugin should have an associated workflow file to show the algorithm in action in CrypTool 2. These workflow files are saved as \textit{Compressed Workspace Manager} files with file extension \textit{.cwm}. You can view the example files from other plugins by opening any of the files in the \texttt{Templates\textbackslash} folder with CrypTool 2. Below is an example workflow. You should provide such a template .cwm file to demonstrate a typical use case of your plugin. Please place it into the \texttt{Templates\textbackslash} folder and make sure to commit the file to the SVN repository (see Section \ref{CommitingYourChanges}).
257
258\begin{figure}[h]
259        \centering
260                \includegraphics{figures/sample.jpg}
261        \caption{A sample workflow diagram for the Caesar algorithm}
262        \label{fig:sample}
263\end{figure}
Note: See TracBrowser for help on using the repository browser.