# Changeset 1060 for trunk/Documentation

Ignore:
Timestamp:
Jan 11, 2010, 12:56:41 AM (12 years ago)
Message:

Removed the right chapter titles; Fixed wrong image positions; fixed wrong chapter references; fixed and complete some text passages; changed abstract page

Location:
trunk/Documentation
Files:
4 edited

### Legend:

Unmodified
 r1053 \fancyhead[L]{\leftmark} %Kopfzeile links \fancyhead[C]{\AddToShipoutPicture*{\BackgroundHeaderPic}} %zentrierte Kopfzeile \fancyhead[R]{\rightmark} %Kopfzeile rechts %\fancyhead[R]{\rightmark} %Kopfzeile rechts --> Removed because it's overflowing on the leftmark if the text is too long \fancyfoot[C]{\thepage\AddToShipoutPicture*{\BackgroundFooterPic}} %zentrierte FuÃzeile \title{CrypTool 2.0} \subtitle{Developer Manual} \author{S.\ Przybylski, A.\ Wacker, M\ Wander and F\ Enkler} \subtitle{\Huge Developer Manual\\\normalsize How to build your own plugins for CT2?} \author{S.\ Przybylski, A.\ Wacker, M.\ Wander and F.\ Enkler} \email{\{przybylski$|$wacker$|$wander$|$enkler\}@cryptool.org} \version{0.1} \begin{document} \maketitle \begin{abstract} \textbf{''Abstract.} CrypTool 2 is the modern successor of the well known e-learning platform for cryptography and cryptanalysis \htmladdnormallink{CrypTool 1}{http://www.cryptool.org}, which is used world-wide for educational purposes at school and universities and in companies and agencies.\\\\Since the first launch of CrypTool 1 in 1999 the art of software development has changed dramatically. So the CrypTool 2 team started in 2008 to develop a completely new e-learning application, embracing the newest trends in both didactics and software architecture to delight the end-user with an entirely new experience.\\\\CT 2 is build using \renewcommand{\labelitemi}{-} \begin{itemize} \item .NET (modern software framework with solutions to common programming problems form Microsoft), \item C\# (modern object-oriented programming language, comparable to Java) and \item WPF (modern purely vector-based graphical subsystem for rendering user interfaces in Windows-based applications) plus \item VisualStudio2008 (development environment) and \item Subversion (source code and documentation version management system). \end{itemize}\\ This document is intended for plugin developers, who want to contribute new visual or mathematical functionality to CT2.\\Currently (January 2010) the code exists of about 7000 lines of C\# code in the Core system and about 240,641 lines of C\# code in the 115 plugins.\\\\For further news and more screenshots please see the developer page \htmladdnormallink{http://www.cryptool2.vs.uni-due.de}{http://www.cryptool2.vs.uni-due.de}.'' \end{abstract} \tableofcontents \AddToShipoutPicture{\WaterMarkPic} \begin{abstract} \textbf{Abstract.} This document is intended for plugin developers. \end{abstract} \AddToShipoutPicture{\WaterMarkPic} \include{part1}
 r1053 \label{sec:CreateANewProjectInVS2008ForYourPlugin} Open Visual Studio 2008 or C\# 2008 Express Edition and create a new project:\\ \begin{figure}[h] \begin{figure}[h!] \centering \includegraphics[width=1.00\textwidth]{figures/vs_create_new_project.jpg} \end{figure}\\ Select ''.NET-Framework 3.5'' as the target framework (the Visual Studio Express edition don't provide this selection because it automatically chooses the actual target framework), and ''Class Library'' as default template to create a DLL file. Give the project a unique and significant name (here: ''Caesar''), and choose a location where to save (the Express edition will ask later for a save location when you close your project or your environment). Select the subdirectory ''CrypPlugins'' from your SVN trunk as location. Finally confirm by pressing the ''OK'' button. \begin{figure}[h] \begin{figure}[h!] \centering \includegraphics[width=0.80\textwidth]{figures/save_solution_csharp_express.JPG} \end{figure}\\ Now your Visual Studio/C\# Express solution should look like this:\\ \begin{figure}[h] \begin{figure}[h!] \centering \includegraphics[width=1.00\textwidth]{figures/solution_start_up.jpg} \end{figure}\\ Make a right click in the Solution Explorer on the ''Reference'' item and choose ''Add Reference''.\\ \begin{figure}[h] \begin{figure}[h!] \centering \includegraphics{figures/add_pluginbase_source.jpg} \end{figure}\\ Select the project ''CrypPluginBase''. If you don't have the CrypPluginBase source code, it's also possible to add a reference the the binary DLL. In this case browse to the path where the library file ''CrypPluginBase.dll'' is located e.g. ''C:\textbackslash Documents and Settings \textbackslash $<$Username$>$ \textbackslash My Documents\textbackslash Visual Studio  2008\textbackslash Projects\textbackslash CrypPluginBase\textbackslash bin\textbackslash Debug'') and select the library by double clicking the file or pressing the "OK" button.\\ \begin{figure}[h] \textit{\small Note: You can also take the binary DLL which is located in the folder where the ''CrypWin.exe'' is placed when you download CrypTool2.} \clearpage \begin{figure}[h!] \centering \includegraphics{figures/browse_reference.jpg} \item PresentationFramework \item WindowsBase \end{itemize} \end{itemize}\clearpage Afterwards your reference tree view should look like this: \begin{figure}[h!] \item Rename the existent class \item Delete the existent class and create a new one. \end{itemize} \end{itemize}\clearpage Which one you choose is up to you. We choose the second way as you can see in the next screenshot: \begin{figure}[h!] \caption{Create new class} \label{fig:new_class} \end{figure}\\ \end{figure}\clearpage Now make a right click on the project item "Caesar" and select "Add-$>$Class...": \begin{figure}[h] \caption{Add a new class} \label{fig:add_new_class} \end{figure}\\ Now give your class a unique name. We call the class as mentioned above "Caesar.cs" and make it public to be available to other classes.\\ \end{figure}\clearpage Now give your class a unique name. We call the class as mentioned above "Caesar.cs" and make it public to be available to other classes. \begin{figure}[h!] \centering \caption{Name the new class} \label{fig:name_new_class} \end{figure}\\ \end{figure} \subsection{Create the class for the settings (CaesarSettings)}\label{sec:CreateTheClassForTheSettingsCaesarSettings} Add a second public class for ISettings in the same way. We call the class "CaesarSettings". The settings class provides the necessary information about controls, captions and descriptions and default parameters for e.g. key settings, alphabets, key length and action to build the \textbf{TaskPane} in CrypTool. How a \textbf{TaskPane} could look like you can see below for the example of a Caesar encryption.\\ Add a second public class for ISettings in the same way. We call the class "CaesarSettings". The settings class provides the necessary information about controls, captions and descriptions and default parameters for e.g. key settings, alphabets, key length and action to build the \textbf{TaskPane} in CrypTool.\clearpage How a \textbf{TaskPane} could look like you can see below for the example of a Caesar encryption.\\ \begin{figure}[h!] \centering \item Cryptool.PluginBase = interfaces like IPlugin, IHash, ISettings, attributes, enumerations, delegates and extensions. \item Cryptool.PluginBase.Analysis = interface for the crypto analysis plugins like ''Stream Comparator'' \item Cryptool.PluginBase.Control = ? \item Cryptool.PluginBase.Control = contains global interfaces for the IControl feature to define own controls \item Cryptool.PluginBase.Cryptography = interface for all encryption and hash algorithms like AES, DES or MD5 hash \item Cryptool.PluginBase.Editor = interface for editors you want to implement for CrypTool 2.0 like the default editor \item Cryptool.PluginBase.IO = interface for CryptoolStream, input and output plugins like text input, file input, text output and file output \item Cryptool.PluginBase.Miscellaneous = provides all event helper like GuiLogMessage or PropertyChanged \item Cryptool.PluginBase.Resources = ? \item Cryptool.PluginBase.Resources = used by CrypWin and the editor. Not required for plugin developers \item Cryptool.PluginBase.Tool = interface for all foreign tools which CrypTool 2.0 has to provide and which does not exactly support the CrypTool 2.0 API \item Cryptool.PluginBase.Validation = interface which provides method for validation like regular expression \item ''Cryptool.PluginBase.Miscellaneous'' to use the entire CrypTool event handler \end{itemize} It is important to define a new default namespace of our public class (''Caesar''). In CrypTool the default namespace is presented by ''Cryptool.[name of class]''. Therefore our namespace has to be defined as follows: ''Cryptool.Caesar''.\\ It is important to define a new default namespace of our public class (''Caesar''). In CrypTool the default namespace is presented by ''Cryptool.[name of class]''. Therefore our namespace has to be defined as follows: ''Cryptool.Caesar''.\clearpage Up to now the source code should look as you can see below: \begin{lstlisting} Before we go back to the code of the Caesar class, we have to add an icon image to our project, which will be shown in the CrypTool \textbf{ribbon bar} or/and \textbf{navigation pane}. As there is no default, using an icon image is mandatory.\\\\ \textit{\small Note: This will be changed in future. A default icon will be used if no icon image has been provided.}\\\\ For testing purposes you may create a simple black and white PNG image with MS Paint or Paint.NET. As image size you can use 40x40 pixels for example, but as the image will be scaled when required, any size should do it. Place the image file in your project directory or in a subdirectory. Then make a right click on the project item "Caesar" or any subdirectory within the Solution Explorer, and select ''Add-$>$Existing Item...'': For testing purposes you may create a simple black and white PNG image with MS Paint or Paint.NET. As image size you can use 40x40 pixels for example, but as the image will be scaled when required, any size should do it. Place the image file in your project directory or in a subdirectory.\clearpage Then make a right click on the project item "Caesar" or any subdirectory within the Solution Explorer, and select ''Add-$>$Existing Item...'': \begin{figure}[h!] \centering \caption{Add existing item} \label{fig:add_existing_item} \end{figure}\\ As you can see, in our solution we create an new folder named ''Images'' (make a right click on the project item ''Caesar'' and select ''Add-$>$New Folder'') and placed there the new icon by clicking right on the folder as mentioned aboved. \end{figure} As you can see, in our solution we create an new folder named ''Images'' (make a right click on the project item ''Caesar'' and select ''Add-$>$New Folder'') and placed there the new icon by clicking right on the folder as mentioned aboved.\clearpage Then select ''Image Files'' as file type, and choose the icon for your plugin: \begin{figure}[h!] \caption{Choose the right icon} \label{fig:choose_icon} \end{figure}\\ Finally we have to set the icon as a ''Resource'' to avoid providing the icon as a separate file. Make a right click on the icon and select the item ''Properties'': \end{figure} Finally we have to set the icon as a ''Resource'' to avoid providing the icon as a separate file. Make a right click on the icon and select the item ''Properties'':\clearpage \begin{figure}[h!] \centering \caption{Icon properties} \label{fig:icon_properties} \end{figure}\\ \end{figure} In the ''Properties'' panel you have to set the ''Build Action'' to ''Resource'' (not embedded resource): \begin{figure}[h!] \end{figure} \section{Set the attributes for the class Caesar}\label{sec:SetTheAttributesForTheClassCaesar} Now let's go back to the code of the Caesar class ("Caesar.cs" file). First we have to set the necessary attributes for our class. This attributes are used to provide additional information for the CrypTool 2.0 environment. If not set, your plugin won't show up in the GUI, even if everything else is implemented correctly.\\\\ Attributes are used for \textbf{declarative} programming and provide meta data, that can be attached to the existing .NET meta data , like classes and properties. Cryptool provides a set of custom attributes, that are used to mark the different parts of your plugin.\\\\ Now let's go back to the code of the Caesar class (''Caesar.cs'' file). First we have to set the necessary attributes for our class. This attributes are used to provide additional information for the CrypTool 2.0 environment. If not set, your plugin won't show up in the GUI, even if everything else is implemented correctly.\\\\ Attributes are used for \textbf{declarative} programming and provide meta data, that can be attached to the existing .NET meta data , like classes and properties. CrypTool provides a set of custom attributes, that are used to mark the different parts of your plugin.\\\\ \textit{[Author]}\\ The first attribute called ''Author'' is optional, which means we are not forced to define this attribute. It provides the additional information about the plugin developer. This informations you can see for example in the TaskPane as shown on a screenshot above. We set this attribute to demonstrate how it has to look in case you want to provide this attribute. \label{fig:attribute_plugininfo_icon} \end{figure}\\ The detailed description could now look like this in CrypTool (right click plugin icon on workspace and select ''Show description''): \begin{figure}[h] The detailed description could now look like this in CrypTool (right click plugin icon on workspace and select ''Show description''):\clearpage \begin{figure}[h!] \centering \includegraphics[width=1.00\textwidth]{figures/xaml_description.jpg} #endregion \end{lstlisting} Please notice if there is a sinuous line at the code you type for example at the ''CryptoolStream'' type of the variable listCryptoolStreamsOut. ''CryptoolStream'' is a data type for input and output between plugins and is able to handle large data amounts. To use the CrypTool own stream type, include the namespace ''Cryptool.PluginBase.IO'' with a ''using'' statement as explained in chapter 3.3. Check the other code entries while typing and update the missing namespaces.\\ Please notice if there is a sinuous line at the code you type for example at the ''CryptoolStream'' type of the variable listCryptoolStreamsOut. ''CryptoolStream'' is a data type for input and output between plugins and is able to handle large data amounts. To use the CrypTool own stream type, include the namespace ''Cryptool.PluginBase.IO'' with a ''using'' statement as explained in chapter \ref{sec:AddNamespaceForTheClassCaesarAndThePlaceFromWhereToInherit}. Check the other code entries while typing and update the missing namespaces.\\ The following private variables are being used in this example: \begin{itemize} } \end{lstlisting} Thirdly we have to define five properties with their according attributes. This step is necessary to tell Cryptool that these properties are input/output properties used for data exchange with other plugins or to provide our plugin with external data.\\ Thirdly we have to define five properties with their according attributes. This step is necessary to tell CrypTool that these properties are input/output properties used for data exchange with other plugins or to provide our plugin with external data.\\ The attribute is named ''PropertyInfo'' and consists of the following elements: \begin{itemize} } \end{lstlisting} It is important to make sure that all changes of output properties will be announced to the CrypTool environment. In this example this happens by calling the setter of OutputData which in turn calls ''OnPropertyChanged'' for both output properties ''OutputData'' and ''OutputDataStream''. Instead of calling the property's setter you can as well call ''OnPropertyChanged'' directly within the ''Execute()'' method.\\\\ It is important to make sure that all changes of output properties will be announced to the CrypTool environment. In this example this happens by calling the setter of OutputData which in turn calls ''OnPropertyChanged'' for both output properties ''OutputData'' and ''OutputDataStream''. Instead of calling the property's setter you can as well call ''OnPropertyChanged'' directly within the ''Execute()'' method.\clearpage Certainly you have seen the unknown method ''ProgressChanged'' which you can use to show the current algorithm process as a progress on the plugin icon. To use this method you also have to declare this method to afford a successful compilation: Dispose(); } \end{lstlisting} \end{lstlisting}\clearpage \section{Finish implementation}\label{sec:FinishImplementation} When adding plugin instances to the CrypTool workspace, CrypTool checks whether the plugin runs without any exception. If any IPlugin method throws an exception, CrypTool will show an error and prohibit using the plugin. Therefore we have to remove the ''NotImplementedException'' from the methods ''Initialize()'', ''Pause()'' and ''Stop()''. In our example it's sufficient to provide empty implementations. } \end{lstlisting} Your plugin should compile without errors at this point. \section{Sign the created plugin}\label{sec:SignTheCreatedPlugin} \section{Import the plugin to Cryptool and test it}\label{sec:ImportThePluginToCryptoolAndTestIt} Your plugin should compile without errors at this point.\clearpage \section{Import the plugin to CrypTool and test it}\label{sec:ImportThePluginToCryptoolAndTestIt} After you have built the plugin, you need to move the newly created plugin DLL to a location, where CrypTool can find it. To do this, there are the following ways: \begin{itemize} \label{fig:copy_dll_global_storage} \end{figure}\\ This folder is called ''Global storage'' in the CrypTool architecture. Changes in this folder will take effect for all users on a multi user Windows. Finally restart CrypTool. This folder is called ''Global storage'' in the CrypTool architecture. Changes in this folder will take effect for all users on a multi user Windows. Finally restart CrypTool.\clearpage \begin{figure}[h] \centering \end{figure}\\ \item Copy your plugin DLL file in the folder ''CrypPlugins'' which is located in your home path in the folder ''ApplicationData'' and restart CrypTool.  This home folder path is called ''Custom storage'' in the CrypTool architecture. Changes in this folder will only take effect for current user.  On a German Windows XP the home folder path could look like: ''C:\textbackslash Dokumente und Einstellungen\textbackslash $<$User$>$\textbackslash Anwendungsdaten\textbackslash CrypPlugins'' and in Vista/Windows7 the path will look like ''C:\textbackslash Users\textbackslash $<$user$>$\textbackslash Application Data\textbackslash CrypPlugins''. ''C:\textbackslash Dokumente und Einstellungen\textbackslash $<$User$>$\textbackslash Anwendungsdaten\textbackslash CrypPlugins'' and in Vista/Windows7 the path will look like ''C:\textbackslash Users\textbackslash $<$user$>$\textbackslash Application Data\textbackslash CrypPlugins''.\clearpage \begin{figure}[h] \centering Notice, that this plugin importing function only accepts \textbf{signed} plugins. \textit{\small Note: This option is a temporary solution for importing new plugins. In the future this will be done online by a web service.} \textit{\small Note: This option is a temporary solution for importing new plugins. In the future this will be done online by a web service.}\clearpage \item Use post-build in your project properties to copy the DLL automatically after building it in Visual Studio with other plugins. Right-click on your plugin project and select ''Properties'': \caption{Solution Properties} \label{fig:solution_properties} \end{figure}\\ \end{figure}\clearpage Select ''Build Events'': \begin{figure}[h] password: not required\\} \htmladdnormallink{https://www.cryptool.org/svn/CrypTool2/trunk/CrypPlugins/Caesar/}{https://www.cryptool.org/svn/CrypTool2/trunk/CrypPlugins/Caesar/}\\\\ Here you can download the Visual Studio plugin \textbf{template} to begin with the development of a new Cryptool plugin:\\\\ \htmladdnormallink{http://cryptool2.vs.uni-due.de/downloads/template/encryptionplugin.zip}{http://cryptool2.vs.uni-due.de/downloads/template/encryptionplugin.zip} Here you can download the Visual Studio plugin \textbf{template} to begin with the development of a new CrypTool plugin:\\\\ \htmladdnormallink{http://cryptool2.vs.uni-due.de/downloads/template/encryptionplugin.zip}{http://cryptool2.vs.uni-due.de/downloads/template/encryptionplugin.zip}\clearpage \section{Provide a workflow file of your plugin}\label{ProvideAWorkflowFileOfYourPlugin} Every plugin developer should provide a workflow file which shows his algorithm working in CrypTool2. You will automatically create a workflow file by saving your project which was created on CrypTool2 work space. Here is an example how a workflow could look like: