Changeset 1236 for trunk/Documentation


Ignore:
Timestamp:
Mar 10, 2010, 4:49:36 PM (12 years ago)
Author:
Patrick Vacek
Message:

HowTo: reworked first Chapter, added some new screenshots, and started fixing smaller things in Chapter 2.

Location:
trunk/Documentation/Developer/PluginHowTo
Files:
3 added
5 edited

Legend:

Unmodified
Added
Removed
  • trunk/Documentation/Developer/PluginHowTo/HowToDeveloper.tex

    r1231 r1236  
    166166
    167167        \begin{abstract}
    168      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 schools and universities and in companies and agencies.
     168CrypTool 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 worldwide for educational purposes at schools and universities as well as in companies and agencies.
    169169
    170      Since the first launch of CrypTool 1 in 1999 the art of software development has changed dramatically. The CrypTool 2 team began working 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.\\
     170Since the first launch of CrypTool 1 in 1999 the art of software development has changed dramatically. The CrypTool 2 team began working 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.\\
    171171
    172      To meet these ends, CrypTool 2 is built using the following:
     172To reach these goals, CrypTool 2 is built using the following:
    173173
    174174\begin{itemize}
     
    180180\end{itemize}
    181181
    182 This document is intended for plugin developers who want to contribute new visual or mathematical functionality to CT2. As of January 2010, the code consists of about 7000 lines of C\# code in the core system and about 250,000 lines of C\# code in 115 plugins.
     182This document is intended for plugin developers who want to contribute new visual or mathematical functionality to CrypTool 2. As of January 2010, the program consists of about 7000 lines of C\# code in the core application and about 250,000 lines of C\# code in 115 plugins.
    183183
    184 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}.
     184For further information, please visit the CrypTool 2 website at \htmladdnormallink{http://www.cryptool2.vs.uni-due.de}{http://www.cryptool2.vs.uni-due.de}.
    185185    \end{abstract}
    186186
  • trunk/Documentation/Developer/PluginHowTo/part1.tex

    r1231 r1236  
    22\label{DeveloperGuidelines}
    33
    4 CrypTool 2.0 uses state-of-the-art technologies like .NET 3.5 and WPF. In order to make your first steps towards developing something in the context of this project, a few things need to be considered. First of all, please follow the instructions in this document so that you do not get stuck. If you encouter a problem or error that is not described here, please let us know so we can add the appropriate information to this guide.
     4CrypTool 2.0 is built upon state-of-the-art technologies such as .NET 3.5 and the Windows Presentation Foundation. 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 succesfully interact with the application core. We have tried to be very thorough, but if you encouter 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.
    55
    6 In the following sections we will describe all steps necessary in order to compile CrypTool 2.0 on your own. This is always the first thing you need to do before you can begin developing your own plugins and extensions. The basic steps are:
     6In this first chapter we will describe all steps necessary in order to compile CrypTool 2.0 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:
    77\begin{itemize}
    88        \item Getting all prerequisites and installing them
    99        \item Accessing and downloading the source code with SVN
    10         \item Compiling the current source code for the first time
     10        \item Compiling the latest version of the source code
    1111\end{itemize}
    1212
     
    1414\label{Prerequisites}
    1515
    16 Since CrypTool 2.0 is based on Microsoft .NET 3.5, you will need a Microsoft Windows environment. (Currently no plans exist for porting this project to mono or to other platforms.) We have successfully tested with \textbf{Windows XP}, \textbf{Windows Vista} and \textbf{Windows 7}.
     16Since CrypTool 2.0 is based on Microsoft .NET 3.5, 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 \textbf{Windows XP}, \textbf{Windows Vista} and \textbf{Windows 7}.
    1717
    18 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 \textbf{Microsoft Visual Studio 2008 Professional}. Please always install the latest service packs for Visual Studio. Unfortunately, our sources do not work (smoothly) with the freely available Visual Studio Express (C\#) versions. This is due to the fact that CrypWin uses a commercial component and is therefore distributed only as binary, and the current version of C\# Express cannot handle a binary as a start project, which makes debugging cumbersome. This will be resolved later in 2010 when the project is moved to Visual Studio 2010.
     18Since 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 \textbf{Microsoft Visual Studio 2008 Professional}. Make sure to always install the latest service packs for Visual Studio. Unfortunately, our sources do not work smoothly with the freely available Visual C\# Express. This is due to the fact that a major part of the application core, CrypWin, uses a commercial component and is therefore distributed only as a binary. The current version of Visual C\# Express does not accept a binary file as a start-up project, and thus debugging is quite cumbersome. We hope to resolve this issue later in 2010 when the project is ported to Visual Studio 2010, but until then, we recommend using the full Visual Studio 2008 Professional version.
    1919
    20 Usually the installation of Visual Studio also installs the .NET framework. In order to run or compile our source code you will need (at the time of writing) at least \textbf{Microsoft .NET 3.5 with Service Pack 1 (SP1)}. You can get this for free from Microsoft's \href{http://download.microsoft.com/download/2/0/e/20e90413-712f-438c-988e-fdaa79a8ac3d/dotnetfx35.exe}{webpage}. Once that has been installed, your development environment should be ready for our source code.
     20In order to run or compile our source code you will need at least the \textbf{Microsoft .NET 3.5 framework with Service Pack 1 (SP1)}. 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 \href{http://download.microsoft.com/download/0/6/1/061F001C-8752-4600-A198-53214C69B51F/dotnetfx35setup.exe}{Microsoft's website}. Once the framework has been installed, your development environment should be ready for our source code.
     21\clearpage
    2122
    22 \section{Accessing Subversion (SVN)}
     23\section{Accessing the Subversion (SVN) repository}
    2324\label{AccessingSubversion}
    2425
    25 Now you will need a way of accessing and downloading the source code. In the CrypTool 2.0 project we use Subversion (SVN) for version control, and hence you need an \textbf{SVN client}, e.g.\ \textbf{TortoiseSVN} or the \textbf{svn commandline from cygwin}. It does not matter which client you use, but if you have never worked with SVN before, we suggest using \href{http://www.tortoisesvn.net/}{TortoiseSVN}, since it offers a nice Windows Explorer integration of SVN.
    26 \clearpage
     26Next you will need a way of accessing and downloading the source code. For the CrypTool 2.0 project we use Subversion (SVN) for version control, and hence you will need an \textbf{SVN client}, i.e.\ \textbf{TortoiseSVN} or the \textbf{svn commandline from cygwin}, to access our repository. It does not matter which client you use, but if SVN is new to you, we suggest using \href{http://www.tortoisesvn.net/}{TortoiseSVN}, since it offers a handy, straightforward Windows Explorer integration. We will guide you through how to use TortoiseSVN, although you should be able to use any SVN client in a similar fashion.
    2727
    28 \subsection{The CrypTool2 SVN URL}
    29 \label{TheCrypTool2SVNURL}
     28\subsection{Checking out the sources}
     29\label{CheckingOutTheSources}
    3030
    31 Our code repository is accessable at the following URL:
    32 
    33 \url{https://www.cryptool.org/svn/CrypTool2/}
    34 
    35 To access the repository, you must provide a username and password. If you are a guest and just want to download our source code, you can use ``anonymous'' as the username and an empty password. If you are a registered developer, just use your provided username and password (which should be the same as for the wiki).
    36 
    37 \subsection{Accessing the repository with TortoiseSVN}
    38 \label{AccessingTheRepositoryWithTortoiseSVN}
    39 
    40 As mentioned above, in order to access the SVN repository one of the best options is \href{http://www.tortoisesvn.net/}{TortoiseSVN}. We will describe here how to use the basics of the program, although you should be able to use any SVN client in a similar fashion.
     31First, download and install TortoiseSVN. This will require you to reboot your computer, but once it is back up and running, create a directory (for instance, \textit{CrypTool2}) somewhere on your computer for storing the local working files. Right-click on this directory; now that TortoiseSVN has been installed, you should see a few new items in the context menu. Select \textit{SVN Checkout}:
    4132
    4233\begin{figure}[h!]
    4334        \centering
    4435                \includegraphics[width=0.40\textwidth]{figures/tortoise_svn_checkout.jpg}
    45         \caption{Selecting ``SVN Checkout'' from the context menu after installing TortoiseSVN.}
     36        \caption{Selecting \textit{SVN Checkout} from the context menu after installing TortoiseSVN.}
    4637        \label{fig:tortoise_svn_checkout}
    4738\end{figure}
     39\clearpage
    4840
    49 First install TortoiseSVN (which unfortunately requires you to reboot your computer) and then create a directory (for instance ``CrypTool2'') for storing the local working files somewhere on your computer. Right-click on this directory and select ``SVN Checkout'' from the context menu. A window will appear in which you will be asked for the URL of the repository; use the address given above, as seen in Figure \ref{fig:tortoise_svn_checkout2}. The ``Checkout directory'' should already be filled in correctly with your new folder. Then just hit ``OK'', accept the certificate (if necessary), and enter your login information as described above. Mark the checkbox for saving your credentials if you don't want to enter them every time you work with the repository. Then hit ``OK'', and now the whole CrypTool2 repository should be checked out into your chosen directory.
    50 \clearpage
     41A window will now appear that will ask you for the URL of the repository that you would like to access. Our code repository is stored at \url{https://www.cryptool.org/svn/CrypTool2/}, and this is what you should enter in the appropriate field. The \textit{Checkout directory} should already be filled in correctly with your new folder, and you shouldn't need to change any other options.
    5142
    5243\begin{figure}[h!]
    5344        \centering
    5445                \includegraphics[width=0.60\textwidth]{figures/tortoise_svn_checkout2.jpg}
    55         \caption{Checking out the CrypTool2 repository.}
     46        \caption{Checking out the CrypTool 2 repository.}
    5647        \label{fig:tortoise_svn_checkout2}
    5748\end{figure}
    5849
    59 Later on, if changes have been made in the repository and you want to update your working copy, you can do this by right-clicking on any directory within the working files and choosing ``SVN Update'' from the context menu. You should do this often to maintain a current version of the files.
     50Then just hit \textit{OK}. You may be asked to accept a certificate (which you should accept), and you will certainly be asked for login information. If you are a registered developer, you should have already been given a username and password, and you should enter them here. (These are the same username and password that you can use for the \href{https://www.cryptool.org/trac/CrypTool2/wiki/WikiStart}{CrypTool 2 development wiki}). If you are a guest and just want to download the source code, you can use ``anonymous'' as the username and an empty password. Mark the checkbox for saving your credentials if you don't want to enter them every time you work with the repository. Finally, hit \textit{OK}, and the whole CrypTool 2 repository will begin downloading into your chosen local directory.
    6051
    61 A TortoiseSVN tutorial can be found \href{http://www.mind.ilstu.edu/research/robots/iris4/developers/svntutorial}{here}.
     52Since CrypTool 2 is a collaborative project with many developers, changes are made to the repository rather frequently. You should maintain a current working copy of the files to ensure your interoperability with the rest of the project, and thus you should update to the latest version as often as possible. You can do this by right-clicking on any directory within the working files and choosing \textit{SVN~Update} from the context menu.
    6253
    63 \subsection{Committing your changes}
    64 \label{CommitingYourChanges}
     54A TortoiseSVN tutorial can be found at \url{http://www.mind.ilstu.edu/research/robots/iris4/developers/svntutorial}.
     55\clearpage
    6556
    66 If you are a registered developer, you can commit your file changes to the public CrypTool2 repository. Right-click on the directory within the working files that contains your changes and select ``SVN Commit'' from the context menu to upload your changes. Please always provide \textit{meaningful descriptions} of your updates. You should commit your sources to our SVN repository as often as you can to ensure your interoperability with the rest of the project, but only commit code that successfully compiles and runs!
     57\subsection{Adjusting the SVN settings}
     58\label{AdjustingTheSVNSettings}
     59
     60If you are a registered developer, you can commit your file changes to the public CrypTool 2 repository. However, before you do, you should edit your settings to make sure that you only check in proper source code. First, bring up the TortoiseSVN settings window:
    6761
    6862\begin{figure}[h!]
    6963        \centering
    70                 \includegraphics[width=0.40\textwidth]{figures/tortoise_svn_commit.jpg}
    71         \caption{Selecting ``SVN Commit'' from the context menu.}
    72         \label{fig:tortoise_svn_commit}
     64                \includegraphics[width=0.70\textwidth]{figures/tortoise_svn_accessing_settings.jpg}
     65        \caption{Getting to the TortoiseSVN settings.}
     66        \label{fig:tortoise_svn_accessing_settings}
     67\end{figure}
     68\clearpage
     69
     70\noindent The settings window will look something like this:
     71
     72\begin{figure}[h!]
     73        \centering
     74                \includegraphics[width=0.90\textwidth]{figures/tortoise_svn_ignore_patterns.jpg}
     75        \caption{The TortoiseSVN settings window with the proper ignore pattern.}
     76        \label{fig:tortoise_svn_ignore_patterns}
    7377\end{figure}
    7478
    75 You can use command words in the SVN comment to link your changes to a particular ticket. The command syntax is as follows:
    76 
    77 \begin{center}
    78 \fbox{\parbox{15cm}
    79 {\tt
    80 command \#1\newline
    81 command \#1, \#2\newline
    82 command \#1 \& \#2\newline
    83 command \#1 and \#2
    84 }}
    85 \end{center}
    86 
    87 You can have more than one command in a message. The following commands are supported. There is more than one spelling for each command, to make this as user-friendly as possible.
    88 
    89 \begin{center}
    90 \fbox{\parbox{15cm}
    91 {\tt
    92 closes, fixes:\newline
    93   The specified issue numbers are closed with the contents of this
    94   commit message being added to it.
    95 
    96 references, refs, addresses, re:\newline
    97   The specified issue numbers are left in their current status, but
    98   the contents of this commit message are added to their notes.
    99 }}
    100 \end{center}
    101 
    102 A fairly complicated example of what you can do is with a commit message of:
    103 
    104 \begin{center}
    105 \fbox{\parbox{15cm}
    106 {\tt
    107 Changed blah and foo to do this or that.\ Fixes \#10 and \#12, and refs \#12.
    108 }}
    109 \end{center}
    110 
    111 This will close \#10 and \#12, and add a note to \#12.
    112 
    113 \subsection{Ignore patterns}
    114 \label{IgnorePatterns}
    115 
    116 Please only check in proper source code by using the following \textbf{ignore patterns}:
     79\noindent Then in the \textit{Global ignore pattern} field, please enter the following text:
    11780
    11881\begin{center}
     
    12083\end{center}
    12184
    122 This basically means that you should never check in compiled and automatically generated files. For example, please do not check in the entire \textit{bin/} and \textit{obj/} directories that Visual Studio generates. Note that the server will reject your commits if you try to do so. If you want to submit a component (binary file) despite the ignore patterns you can still add \textit{*.dll} files by using the context menu and adding the file explicitly - but please be absolutely sure that you know what you are doing. Additionally, you need to provide an explicit list of file and directory names which should override the ignore pattern. For example, if you want to check in a file named someLib.dll, you must write a comment which looks like this:
     85You are free to also leave in any default pattern text or to write your own additions; this pattern serves simply to tell TortoiseSVN what kinds of files to ignore. You can now click \textit{OK} to save your settings and close the window.
     86\clearpage
     87
     88\subsection{Committing your changes}
     89\label{CommitingYourChanges}
     90
     91Once you start writing code and developing your plugin, you should check your work into the project repository. If you are reading this document in sequence, you are probably not ready to do this, but while we are on the topic of SVN we will describe the process. To upload your changes, right-click on a directory within the working files that contains your changes and select \textit{SVN Commit} from the context menu:
     92
     93\begin{figure}[h!]
     94        \centering
     95                \includegraphics[width=0.40\textwidth]{figures/tortoise_svn_commit.jpg}
     96        \caption{Selecting \textit{SVN Commit} from the context menu.}
     97        \label{fig:tortoise_svn_commit}
     98\end{figure}
     99\clearpage
     100
     101When you commit your code, you can leave a comment to describe what you have changed. Please always provide \textit{meaningful descriptions} of your updates. You can also select exactly which files you want to check in. The ignore pattern that we recommended should prevent most undesirable files from being in the list, but double-check to make sure everything you want to upload is included but nothing more. In general, you should never check in compiled and automatically generated files. For example, do not check in the entire \textit{bin\textbackslash } and \textit{obj\textbackslash } directories that Visual Studio generates. The server will reject your commits if you try to do so. You should commit your sources to our SVN repository as often as you can, but only commit code that successfully compiles and runs!
     102
     103\begin{figure}[h!]
     104        \centering
     105                \includegraphics[width=0.70\textwidth]{figures/tortoise_svn_commit2.jpg}
     106        \caption{Providing comments for a commit.}
     107        \label{fig:tortoise_svn_commit2}
     108\end{figure}
     109
     110You can use the SVN comments to link to your changes to a particular issue or bug ticket on the CrypTool 2 development wiki. (The list of active tickets can be found \href{https://www.cryptool.org/trac/CrypTool2/report/1}{here}.) The following commands are supported (note that there are multiple variations of each command that are functionally identical):
     111
     112\begin{center}
     113\fbox{\parbox{15cm}
     114{
     115\texttt{closes, fixes:}
     116
     117The specified ticket will be closed and the contents of this commit message will be added to its notes.\\
     118
     119\texttt{references, refs, addresses, re:}
     120
     121The contents of this commit message will be added to the specified ticket's notes, but the status will be left unaltered.
     122}}
     123\end{center}
     124\clearpage
     125
     126You can apply the commands to multiple tickets simultaneously. The command syntax is as follows (again note that there are multiple variations that are functionally identical):
    123127
    124128\begin{center}
    125129\fbox{\parbox{15cm}
    126130{\tt
    127 The lib is required by all developers, so I am adding it explicitly to the repository.
     131command \#1\\
     132command \#1, \#2\\
     133command \#1 \& \#2\\
     134command \#1 and \#2
     135}}
     136\end{center}
    128137
     138You can also use more than one command in a message if necessary. For example, if you want to close tickets \#10 and \#12, and add a note to \#17, you could type the following:
     139
     140\begin{center}
     141\fbox{\parbox{15cm}
     142{\tt
     143Changed blah and foo to do this or that.\ Fixes \#10 and \#12, and refs \#17.
     144}}
     145\end{center}
     146
     147The comments can also be used to override the ignore pattern that the server is designed to block. However, please do not do this unless you are absolutely sure that you know what you are doing. If you are, you must use the \textit{override-bad-extension} command and provide an explicit list of the file and directory names that you want to upload that need to override the ignore pattern. For example, if you want to check in a library file named \textit{someLib.dll}, you must write something like the following:
     148
     149\begin{center}
     150\fbox{\parbox{15cm}
     151{\tt
     152This library is required by all developers, so I am adding it explicitly to the repository.\\\\
    129153override-bad-extension:\ someLib.dll
    130154}}
    131155\end{center}
    132156
    133 Please note that any text after the colon and the whitespace will be treated as the file name. Therefore, do not use quotation marks and do not write any text after the file name.
    134 \clearpage
     157Note that any text after the colon and the whitespace will be treated as the file name. Therefore, do not use quotation marks and do not write any text after the file name.
    135158
    136159\section{Compiling the sources}
    137160\label{CompilingTheSources}
    138161
    139 By this point you should have checked out a copy of the entire CrypTool repository. Compiling is pretty easy; just go to the \textit{trunk/} directory and open the \textbf{\textit{CrypTool 2.0.sln}} Visual Studio solution. The Visual Studio IDE should open with all the working plugins components nicely arranged. In case you are now starting Visual Studio for the first time, you will have to choose your settings. Just select either ``most common'' or ``C\#'' --- you can change this at any time later. On the right side is the project explorer, where you can see all the subprojects included in the solution. Look for the project \textbf{\textit{CrypWin.exe}} there. Once you have found it, right-click on it and select ``Set as StartUp-Project'' from the context menu. Next, go to the menu bar and select ``Build'' $\rightarrow$ ``Build Solution''.
     162By this point you should have checked out a copy of the entire CrypTool repository. Compiling is pretty easy; just go to the \textit{trunk\textbackslash } directory and open the \textbf{\textit{CrypTool 2.0.sln}} Visual Studio solution. The Visual Studio IDE should open with all the working plugin components nicely arranged. If you are now starting Visual Studio for the first time, you will have to choose your settings. Just select either \textit{most common} or \textit{C\#} --- you can change this at any time later. On the right side is the project explorer, where you can see all the subprojects included in the solution. Look for the project \textbf{\textit{CrypWin.exe}} there. Once you have found it, right-click on it and select \textit{Set as StartUp Project} from the context menu. Next, go to the menu bar and select \textit{Build $\rightarrow$ Build Solution}.
    140163
    141 Then go to ``Debug'' and select ``Start Debugging''. CrypTool 2.0 should now start for the first time with your own compiled code. Presumably you have not changed anything yet, but you now have your own build of all the components (with the exception of CrypWin and AnotherEditor, since they are available only as binaries). If the program does not compile or start correctly, please consult our \href{https://www.cryptool.org/trac/CrypTool2/wiki/FAQ}{FAQ} and let us know if you found a bug.
     164You may have to wait a while for the program to compile. Once it is finished, select \textit{Debug $\rightarrow$ Start Debugging}. CrypTool 2.0 should now start for the first time with your own compiled code. Presumably you have not changed anything yet, but you now have your own build of all the components (with the exception of \textit{CrypWin} and \textit{AnotherEditor}, since they are available only as binaries). If the program does not compile or start correctly, please consult our \href{https://www.cryptool.org/trac/CrypTool2/wiki/FAQ}{FAQ} and let us know if you found a bug.
    142165
    143 If you are a \textbf{core developer}, hence somebody who can also compile CryWin and AnotherEditor, you should use the \textbf{\textit{CrypTool 2.0.sln}} solution from the \textit{trunk/CoreDeveloper/} directory (which will \textit{not} be visible to you if you are not a core developer). As a core developer, be aware that when you compile, you \textbf{change the \textit{CryWin.exe}} that is visible to everybody else. Thus, when doing a check-in, please make sure you \textit{really} want to check in a new binary. Core developers can also build a new setup and publish it as beta release on the website. This process is explained in the wiki at \url{https://www.cryptool.org/trac/CrypTool2/wiki/BuildSetup}.
     166If you are a \textbf{core developer}, hence somebody who can also compile CryWin and AnotherEditor, you should use the \textbf{\textit{CrypTool 2.0.sln}} solution from the \textit{trunk\textbackslash CoreDeveloper\textbackslash } directory (which will \textit{not} be visible to you if you are not a core developer). As a core developer, be aware that when you compile, you \textbf{change the \textit{CryWin.exe}} that is visible to everybody else. Thus, when committing to the repository, please make sure you \textit{really} want to check in a new binary. Core developers can also build a new setup and publish it as beta release on the website. This process is explained in the wiki at \url{https://www.cryptool.org/trac/CrypTool2/wiki/BuildSetup}.
  • trunk/Documentation/Developer/PluginHowTo/part2.tex

    r1231 r1236  
    11\chapter{Plugin Implementation}
    22\label{sec:PluginImplementation}
    3 In this chapter we provide step-by-step instructions for implementing your own CrypTool 2.0 plugin. The given instructions refer mostly to the usage of the Visual C\# Express and Visual Studio Professional 2008 editions, so before starting you should have a copy of \textbf{Microsoft Visual Studio 2008} (or \textbf{Microsoft Visual C\# 2008 Express Edition}) installed on your computer. We will use the \textbf{Caesar cipher} (also known as the \textbf{shift cipher}) for our example implemenation.
     3In this chapter we provide step-by-step instructions for implementing your own CrypTool 2.0 plugin. The given instructions refer primarily to the usage of the Visual C\# Express and Visual Studio Professional 2008 editions, so before starting you should have a copy of \textbf{Microsoft Visual Studio 2008} (or \textbf{Microsoft Visual C\# 2008 Express Edition}) installed on your computer. We will use the \textbf{Caesar cipher} (also known as the \textbf{shift cipher}) as an example throughout this chapter.
    44
    55\section{Creating a new project}
    66\label{sec:CreatingANewProject}
    77
    8 To begin, open Visual Studio, go to the menu bar and select ``File''~$\rightarrow$ ``New'' $\rightarrow$ ``Project\ldots ''. The following window will appear:
     8To begin, open Visual Studio, go to the menu bar and select \textit{File~$\rightarrow$ New $\rightarrow$ Project\ldots }. The following window will appear:
    99
    1010\begin{figure}[h!]
     
    1515\end{figure}
    1616
    17 \noindent If you are using Visual Studio 2008, select \textbf{``.NET-Framework 3.5''} as the target framework; the Express Edition will automatically choose the target framework. Then choose \textbf{``Class Library''} as the default template, as this will build the project for your plugin as a DLL file. Give the project a unique and meaningful name (such as ``Caesar'' in our case), and choose a location to save it to. (The Express Edition will ask for a save location later when you close your project or environment). Select the subdirectory ``CrypPlugins'' from your SVN trunk as the location. Finally, confirm by pressing the ``OK'' button. Note that creating a new project in this manner also creates a new solution into which the project is placed.
     17\noindent If you are using Visual Studio 2008, select \textbf{\textit{.NET-Framework 3.5}} as the target framework; the Express Edition will automatically choose the target framework. Then choose \textit{Class Library} as the default template, as this will build the project for your plugin as a DLL file. Give the project a unique and meaningful name (such as \textit{Caesar} in our case), and choose a location to save it to. (The Express Edition will ask for a save location later when you close your project or environment). Select the subdirectory \textit{CrypPlugins} from your SVN trunk as the location. Finally, confirm by pressing the \textit{OK} button. Note that creating a new project in this manner also creates a new solution into which the project is placed.
    1818
    1919\begin{figure}[h!]
    2020        \centering
    2121                \includegraphics[width=0.80\textwidth]{figures/save_solution_csharp_express.JPG}
    22         \caption{The Visual Studio C\# Express Edition ``Save Project'' dialog window.}
     22        \caption{The Visual Studio C\# Express Edition \textit{Save Project} dialog window.}
    2323        \label{fig:save_solution_csharp_express}
    2424\end{figure}
    2525
    26 \noindent At this point, your Visual Studio\slash C\# Express solution should look like this:
     26\noindent At this point, your Visual Studio solution should look like this:
    2727
    2828\begin{figure}[h!]
     
    3737\label{sec:InterfaceSelection}
    3838
    39 To include our new plugin in the CrypTool program, we must first add a reference to the CrypTool library, \textbf{\textit{CrypPluginBase.dll}}, where all the necessary CrypTool plugin interfaces are declared.
     39To include our new plugin in the CrypTool 2 application, we must first add a reference to the CrypTool 2 library \textbf{\textit{CrypPluginBase.dll}}, where all the necessary CrypTool 2 plugin interfaces are declared.
    4040
    4141\begin{figure}[h!]
     
    4545\end{figure}
    4646
    47 \noindent Right-click in the Solution Explorer on the ``Reference'' item and choose ``Add Reference''. A window like the following should appear:
     47\noindent Right-click in the Solution Explorer on the \textit{Reference} item and choose \textit{Add Reference}. A window like the following should appear:
    4848
    4949\begin{figure}[h!]
    5050        \centering
    5151                \includegraphics{figures/add_pluginbase_source.jpg}
    52         \caption{Adding a reference to the PluginBase source code.}
     52        \caption{Adding a reference to the CrypPluginBase source code.}
    5353        \label{fig:add_pluginbase_source}
    5454\end{figure}
    5555\clearpage
    5656
    57 \noindent Unless you have created your new project in the same CrypTool 2.0 solution, you probably will not be able to select the library directly as seen above in Figure \ref{fig:add_pluginbase_source}; instead you can browse for the binary DLL as seen below in Figure \ref{fig:browse_reference}. Click on the ``Browse'' tab and navigate to the folder in which you downloaded the CrypTool 2 project. Within that folder, go to \textit{\textbackslash CrypPluginBase\textbackslash bin\textbackslash Debug} and select the file ``CryptPluginBase.dll''. The library reference can then be added by double clicking the file or pressing the ``OK'' button.
     57Unless you have created your new project in the same CrypTool 2.0 solution, you probably will not be able to select the library directly as seen above in Figure \ref{fig:add_pluginbase_source}; instead you can browse for the binary DLL as seen below in Figure \ref{fig:browse_reference}. Click on the \textit{Browse} tab and navigate to the folder in which you downloaded the CrypTool 2 project. Within that folder, go to \textit{\textbackslash CrypPluginBase\textbackslash bin\textbackslash Debug} and select the file \textit{CrypPluginBase.dll}. The library reference can then be added by double clicking the file or pressing the \textit{OK} button.
    5858
    5959\begin{figure}[h!]
     
    6464\end{figure}
    6565
    66 \noindent Besides CrypPluginBase you will need to add three Windows assembly references to provide the necessary namespaces for the \textbf{user control} functions ``Presentation'' and ``QuickWatchPresentation''. This can be done in a similar manner as before with the ``CrypPluginBase'' reference, but by selecting the ``.NET'' tab and searching for the references there. Select the following .NET components:
    67 
     66Besides CrypPluginBase you will need to add three Windows assembly references to provide the necessary namespaces for the user control functions \textit{Presentation} and \textit{QuickWatchPresentation}. This can be done in a similar manner as before with the \textit{CrypPluginBase} reference, but by selecting the \textit{.NET} tab and searching for the references there. Select the following .NET components:
     67
     68\textit{
    6869\begin{itemize}
    6970    \item PresentationCore
    7071    \item PresentationFramework
    7172    \item WindowsBase
    72 \end{itemize}
    73 \clearpage
    74 
    75 \noindent Afterwards your reference tree view should look like this:
     73\end{itemize}}
     74\clearpage
     75
     76\noindent After these additions, your reference tree view should look like this:
    7677
    7778\begin{figure}[h!]
     
    8182\end{figure}
    8283
    83 \noindent If your plugin will be based on other additional libraries, you can add them in the same way.
     84\noindent If your plugin will require other additional libraries, you can add them in the same way.
    8485
    8586\section{Modifing the project properties}
    8687\label{sec:ModifyTheProjectProperties}
    8788
    88 It is important to make two small changes to your plugin's assembly data to make sure that it will be imported correctly into CrypTool 2. Go to the Solution Explorer and open ``AssemblyInfo.cs'', which can be found in the ``Properties'' folder. Make the following two changes:
     89It is important to make two small changes to your plugin's assembly data to make sure that it will be imported correctly into CrypTool 2. Go to the Solution Explorer and open \textit{AssemblyInfo.cs}, which can be found in the \textit{Properties} folder. Make the following two changes:
    8990
    9091\begin{itemize}
    91         \item Change the attribute ``AssemblyVersion'' to have the value ``2.0.*'', and
    92         \item Comment out the attribute ``AssemblyFileVersion''.
     92        \item Change the attribute \textit{AssemblyVersion} to have the value "2.0.*", and
     93        \item Comment out the attribute \textit{AssemblyFileVersion}.
    9394\end{itemize}
    9495
     
    103104\label{sec:CreatingClassesForTheAlgorithmAndItsSettings}
    104105
    105 In the next step we will create two classes. The first class will be the main driver; we will call ours ``Caesar'' since that is the name of the cipher that it will implement. In our case, this class has to inherit from IEncryption because it will be an encryption plugin. If it was instead a hash plugin, this class should inherit from IHash. The second class will be used to store setting information for the plugin, and thus we will name ours ``CaesarSettings''. It will need to inherit from ISettings.
     106In the next step we will create two classes. The first class will be the main driver; we will call ours \textit{Caesar} since that is the name of the cipher that it will implement. In our case, this class has to inherit from \textit{IEncryption} because it will be an encryption plugin. If it was instead a hash plugin, this class should inherit from \textit{IHash}. The second class will be used to store setting information for the plugin, and thus we will name ours \textit{CaesarSettings}. It will need to inherit from \textit{ISettings}.
    106107\clearpage
    107108
     
    109110\label{sec:CreatingAClassForTheAlgorithm}
    110111
    111 When starting a new project, Visual Studio automatically creates a class which has the name ``Class1.cs''.  Since this is a rather non-descriptive name, we will change it. In our example, it should be ``Caesar.cs''. There are two ways to change the name:
     112When starting a new project, Visual Studio automatically creates a class named \textit{Class1.cs}. Since this is a rather non-descriptive name, we will change it. In our example, it will be \textit{Caesar.cs}. There are two ways to change the name:
    112113
    113114\begin{itemize}
     
    117118%\clearpage
    118119
    119 \noindent Both options will achieve the same results. We will guide you through the second method. First, delete ``Class1.cs''.
     120\noindent Both options will achieve the same results. We will guide you through the second method. First, delete \textit{Class1.cs}.
    120121
    121122\begin{figure}[h!]
     
    127128\clearpage
    128129
    129 \noindent Then right-click on the project item (in our case, ``Caesar'') and select ``Add $\rightarrow$ Class\ldots '':
     130\noindent Then right-click on the project item (in our case, \textit{Caesar}) and select \textit{Add $\rightarrow$ Class\ldots }:
    130131
    131132\begin{figure}[h]
     
    137138\clearpage
    138139
    139 \noindent Finally, give your class a unique name. We will call our class ``Caesar.cs'' and define it as public so that it will be available to other classes.
     140\noindent Finally, give your class a unique name. We will call our class \textit{Caesar.cs} and define it as public so that it will be available to other classes.
    140141
    141142\begin{figure}[h!]
     
    146147\end{figure}
    147148
    148 \noindent Visual Studio will automatically generate a basic code outline for the new class. In our example, we will not use the all the namespaces that are automatically imported, so you can delete the lines \texttt{using System;} and \texttt{using System.Linq;}.
     149Note that Visual Studio will automatically generate a very basic code outline for the new class. In our example, we will not use the all the namespaces that are automatically imported, so you can delete the lines \texttt{using System;} and \texttt{using System.Linq;}.
    149150
    150151\subsection{Creating a settings class}
    151152\label{sec:CreatingASettingsClass}
    152153
    153 Add a second public class in the same way. We will call the class ``CaesarSettings''. The settings class stores the necessary information about controls, captions, descriptions and default parameters (e.g.\ for key settings, alphabets, key length and type of action) to build the \textbf{TaskPane} in the CrypTool application.
     154Add a second public class in the same way. We will call the class \textit{CaesarSettings}. The settings class will store the necessary information about controls, captions, descriptions and default parameters (e.g.\ for key settings, alphabets, key length and type of action) to build the \textbf{TaskPane} in the CrypTool application.
    154155\clearpage
    155156
     
    167168\label{sec:AddingTheNamespacesAndInheritanceSourcesForTheCaesarClass}
    168169
    169 Open the ``Caesar.cs'' file by double clicking on it in the Solution Explorer. To include the necessary namespaces in the class header, use the ``using'' statement followed by the name of the desired namespace. The CrypTool 2.0 API provides the following namespaces:
     170Open the \textit{Caesar.cs} file by double clicking on it in the Solution Explorer. To include the necessary namespaces in the class header, use the \texttt{using} statement followed by the name of the desired namespace. The CrypTool 2 API provides the following namespaces:
    170171
    171172\begin{itemize}
    172         \item Cryptool.PluginBase --- contains interfaces such as IPlugin, IHash, and ISettings, as well as attributes, enumerations, delegates and extensions.
    173         \item Cryptool.PluginBase.Analysis --- contains interfaces for cryptanalysis plugins (such as ``Stream Comparator'').
    174         \item Cryptool.PluginBase.Control --- contains global interfaces for the IControl feature for defining custom controls.
    175         \item Cryptool.PluginBase.Cryptography --- contains interfaces for encryption and hash algorithms such as AES, DES and MD5.
    176         \item Cryptool.PluginBase.Editor --- contains interfaces for editors that can be implemented in CrypTool 2.0, such as the default editor.
    177         \item Cryptool.PluginBase.Generator --- contains interfaces for generators, including the random input generator.
    178         \item Cryptool.PluginBase.IO --- contains interfaces for input, output and the CryptoolStream.
    179         \item Cryptool.PluginBase.Miscellaneous --- contains assorted helper classes, including \textit{GuiLogMessage} and \textit{PropertyChanged}.
    180         \item Cryptool.PluginBase.Resources --- used only by CrypWin and the editor; not necessary for plugin development.
    181         \item Cryptool.PluginBase.Tool --- contains an interface for all external tools implemented by CrypTool 2.0 that do not entirely support the CrypTool 2.0 API.
    182         \item Cryptool.PluginBase.Validation --- contains interfaces for validation methods, including regular expressions.
     173        \item \textit{Cryptool.PluginBase} --- contains interfaces such as \textit{IPlugin}, \textit{IHash}, and \textit{ISettings}, as well as attributes, enumerations, delegates and extensions.
     174        \item \textit{Cryptool.PluginBase.Analysis} --- contains interfaces for cryptanalysis plugins (such as \textit{Stream Comparator}).
     175        \item \textit{Cryptool.PluginBase.Control} --- contains global interfaces for the \textit{IControl} feature for defining custom controls.
     176        \item \textit{Cryptool.PluginBase.Cryptography} --- contains interfaces for encryption and hash algorithms such as AES, DES and MD5.
     177        \item \textit{Cryptool.PluginBase.Editor} --- contains interfaces for editors that can be implemented in CrypTool 2, such as the default editor.
     178        \item \textit{Cryptool.PluginBase.Generator} --- contains interfaces for generators, including the random input generator.
     179        \item \textit{Cryptool.PluginBase.IO} --- contains interfaces for input, output and the \textit{CryptoolStream}.
     180        \item \textit{Cryptool.PluginBase.Miscellaneous} --- contains assorted helper classes, including \textit{GuiLogMessage} and \textit{PropertyChanged}.
     181        \item \textit{Cryptool.PluginBase.Resources} --- used only by CrypWin and the editor; not necessary for plugin development.
     182        \item \textit{Cryptool.PluginBase.Tool} --- contains an interface for all external tools implemented by CrypTool~2 that do not entirely support the CrypTool 2 API.
     183        \item \textit{Cryptool.PluginBase.Validation} --- contains interfaces for validation methods, including regular expressions.
    183184\end{itemize}
    184185
     
    186187
    187188\begin{itemize}
    188         \item Cryptool.PluginBase --- to implement ISettings in the CaesarSettings class.
    189         \item Cryptool.PluginBase.Cryptography --- to implement IEncryption in the Caesar class.
    190         \item Cryptool.PluginBase.IO --- to use CryptoolStream for data input and output.
    191         \item Cryptool.PluginBase.Miscellaneous --- to use the CrypTool event handler.
     189        \item \textit{Cryptool.PluginBase} --- to implement \textit{ISettings} in the CaesarSettings class.
     190        \item \textit{Cryptool.PluginBase.Cryptography} --- to implement \textit{IEncryption} in the Caesar class.
     191        \item \textit{Cryptool.PluginBase.IO} --- to use CryptoolStream for data input and output.
     192        \item \textit{Cryptool.PluginBase.Miscellaneous} --- to use the CrypTool event handler.
    192193\end{itemize}
    193194
    194 \noindent It is important to define a new default namespace for our public class (``Caesar''). In CrypTool 2.0  the standard namespace convention is \textit{Cryptool.[name of class]}. Therefore our namespace will be defined as \textit{Cryptool.Caesar}.\clearpage
     195\noindent It is important to define a new default namespace for our public class (\textit{Caesar}). In CrypTool 2  the standard namespace convention is \textit{Cryptool.[name of class]}. Therefore our namespace will be defined as \textit{Cryptool.Caesar}.\clearpage
    195196
    196197\noindent At this point, the source code should look like the following:
     
    215216
    216217\ \\ % ugly but functional
    217 \noindent Next we should let the ``Caesar'' class inherit from IEncryption by making the following alteration:
     218\noindent Next we should let the \textit{Caesar} class inherit from \textit{IEncryption} by making the following alteration:
    218219
    219220\begin{lstlisting}
     
    368369\label{sec:AddingControlsToTheCaesarSettingsClass}
    369370
    370 The settings class is used to populate the TaskPane in the CrypTool 2 application so that the user can modify settings at will. To meet these ends we will need to implement some controls such as buttons and text boxes. If you will be implementing an algorithm that does not have any user-defined settings (e.g. a hash function), then this class can be left empty; you will, however, still have to modify the ``HasChanges'' property to avoid a ``NotImplementedException''. The following code demonstrates the modifications necessary to create the backend for the TaskPane for our Caesar algorithm. You can also look at the source code of other algorithms in the subversion repository for examples of how to create the TaskPane backend.\\
     371The settings class is used to populate the TaskPane in the CrypTool 2 application so that the user can modify settings at will. To meet these ends we will need to implement some controls such as buttons and text boxes. If you will be implementing an algorithm that does not have any user-defined settings (i.e.\ a hash function), then this class can be left empty; you will, however, still have to modify the ``HasChanges'' property to avoid a ``NotImplementedException''. The following code demonstrates the modifications necessary to create the backend for the TaskPane for our Caesar algorithm. You can also look at the source code of other algorithms in the subversion repository for examples of how to create the TaskPane backend.\\
    371372
    372373\begin{lstlisting}
     
    438439        /// <summary>
    439440        /// Returns true if any settings have been changed.
    440         /// This value should be set externally to false e.g.
     441        /// This value should be set externally to false, i.e.
    441442        /// when a project is saved.
    442443        /// </summary>
     
    783784These attributes can be defined anywhere within the ``Cryptool.Caesar'' namespace, but customarily they are defined right before the class declaration.
    784785
    785 \subsection{The \textit{[Author]} attribute}
     786\subsection{The \protect\textit{[Author]} attribute}
    786787\label{sec:TheAuthorAttribute}
    787788
     
    815816%\end{figure}
    816817
    817 \subsection{The \textit{[PluginInfo]} attribute}
     818\subsection{The \protect\textit{[PluginInfo]} attribute}
    818819\label{sec:ThePluginInfoAttribute}
    819820
     
    831832\begin{itemize}
    832833        \item Resource File --- defines where to find the associated resource file, if one is to be implemented. These are used, for example, to provide multilingual support for the plugin. This element is optional.
    833         \item Startable --- a flag that should be set to true only if the plugin is an input generator plugin (i.e. if your plugin only has outputs and no inputs). In all other cases this should be set to false. This flag is important --- setting it incorrectly will result in unpredictable results. This element is mandatory.
     834        \item Startable --- a flag that should be set to true only if the plugin is an input generator plugin (i.e.\ if your plugin only has outputs and no inputs). In all other cases this should be set to false. This flag is important --- setting it incorrectly will result in unpredictable results. This element is mandatory.
    834835        \item Caption --- the name of the plugin or, if the caption is specified in a resource file, the name of the appropriate field in the resource file. This element is mandatory.
    835836        \item ToolTip --- a description of the plugin or, if the tool tip is specified in a resource file, the name of the appropriate field in the resource file. This element is optional.
    836         \item DescriptionURL --- defines where to find the description file (e.g. XAML file). This element is optional.
    837         \item Icons --- an array of strings to define all the paths for the icons to be used in the plugin (i.e. the plugin icon described in section \ref{sec:AddingAnIconToTheCaesarClass}). This element is mandatory.
     837        \item DescriptionURL --- defines where to find the description file (e.g.\ XAML file). This element is optional.
     838        \item Icons --- an array of strings to define all the paths for the icons to be used in the plugin (i.e.\ the plugin icon described in Section \ref{sec:AddingAnIconToTheCaesarClass}). This element is mandatory.
    838839\end{itemize}
    839840
     
    909910If your plugin will use additional icons, you should define the paths to each of them by adding the path strings to the \textit{[PluginInfo]} attribute parameter list, each separated by a comma. We have added two further icons for the context menu in the CrypTool 2 workspace. (If you do choose to add more icons, don't forget to add the icons to your solution.)
    910911
    911 \subsection{The \textit{[EncryptionType]} attribute}
     912\subsection{The \protect\textit{[EncryptionType]} attribute}
    912913\label{sec:TheEncryptionTypeAttribute}
    913914
     
    925926\begin{itemize}
    926927        \item Asymmetric --- for asymmetrical encryption algorithms, such as RSA.
     928        \item SymmetricBlock --- for block cipher algorithms, such as DES, AES and Twofish.
     929        \item SymmetricStream --- for stream cipher algorithms, such as RC4, Rabbit and SEAL.
     930        \item Hybrid --- for algorithms which are actually a combination of several algorithms, such as algorithms in which the data is encrypted symmetrically and the encryption key asymmetrically.
    927931        \item Classic --- for classical encryption or hash algorithms, such as Caesar or MD5.
    928         \item Hybrid --- for algorithms which are actually a combination of several algorithms, such as algorithms in which the data is encrypted symmetrically and the encryption key asymmetrically.
    929         \item SymmetricBlock --- for block cipher algorithms, such as DES, AES and Twofish.
    930         \item SymmetricStream --- for stream cipher algorithms like RC4, Rabbit and SEAL.
    931932\end{itemize}
    932933
     
    949950
    950951\ \\ % ugly but functional
    951 If your algorithm works with longs strings of code, it is recommended to use the ``CryptoolStream'' data type. This was designed for input and output between plugins and to handle large amounts of data. To use the native CrypTool stream type, include the namespace ``Cryptool.PluginBase.IO'' with a ``using'' statement as explained in section \ref{sec:AddingTheNamespacesAndInheritanceSourcesForTheCaesarClass}.
     952If your algorithm works with longs strings of code, it is recommended to use the ``CryptoolStream'' data type. This was designed for input and output between plugins and to handle large amounts of data. To use the native CrypTool stream type, include the namespace ``Cryptool.PluginBase.IO'' with a ``using'' statement as explained in Section \ref{sec:AddingTheNamespacesAndInheritanceSourcesForTheCaesarClass}.
    952953
    953954The following private variables will be used in our example:
     
    10011002
    10021003\begin{itemize}
    1003         \item direction --- defines whether this property is an input or output property, i.e., whether it reads input data or writes output data. The possible values are:
     1004        \item direction --- defines whether this property is an input or output property, e.g.\ whether it reads input data or writes output data. The possible values are:
    10041005        \begin{itemize}
    10051006                \item Direction.Input
     
    10191020        \item mandatory --- this flag determines whether an input must be attached by the user to use the plugin. If set to true, an input connection will be required or else the plugin will not be executed in the workflow chain. If set to false, connecting an input is optional. As this only applies to input properties, if the direction has been set to ``output'', this flag will be ignored.
    10201021        \item hasDefaultValue --- if this flag is set to true, CrypTool 2 will assume that the property has a default input value that does not require user input.
    1021         \item displayLevel --- determines in which display levels your property will be shown in CrypTool 2. These are used to hide more advanced item from less-experienced users; a Beginner will not see the properties marked as any other level, but a Professional will have access to everything. The display levels are as follows:
     1022        \item displayLevel --- determines in which display levels your property will be shown in CrypTool 2. These are used to hide more advanced item from less-experienced users; a beginner using the corresponding display level will not see the properties marked as any other level, but a professional using the appropriate display level will have access to everything. These levels are as follows:
    10221023       
    10231024        \begin{itemize}
     
    14911492\textit{username: anonymous\\
    14921493password:} (not required)\\
    1493 \htmladdnormallink{https://www.cryptool.org/svn/CrypTool2/trunk/CrypPlugins/Caesar/}{https://www.cryptool.org/svn/CrypTool2/trunk/CrypPlugins/Caesar/}\\\\
     1494\url{https://www.cryptool.org/svn/CrypTool2/trunk/CrypPlugins/Caesar/}\\\\
    14941495We have also created a Visual Studio plugin template to help with the development of new plugins. This can be found here:\\\\
    1495 \htmladdnormallink{http://cryptool2.vs.uni-due.de/downloads/template/encryptionplugin.zip}{http://cryptool2.vs.uni-due.de/downloads/template/encryptionplugin.zip}
     1496\url{http://cryptool2.vs.uni-due.de/downloads/template/encryptionplugin.zip}
    14961497\clearpage
    14971498
Note: See TracChangeset for help on using the changeset viewer.