-
Notifications
You must be signed in to change notification settings - Fork 771
AddIn Developer Quick Start Guide
This guide is essentially a transcript of Daniel's Developer Tutorial Video.
In this tutorial you are going to create a very simple Add-in for SharpDevelop that will add a "hello world" pad to the SharpDevelop GUI, as shown below.
PICTURE 1 - GUI with our add-in
Before you can get started with developing your add-in you are going to need:
- A normal installation of SharpDevelop IDE (get an installable MSI here)
- .Net Framework and SDK (get it here)
- A SubVersion client (e.g. Tortoise SVN)
- A nice clean directory to work in (we will be using
C:\Devif you choose something else you will need to adjust the rest of this article to suit)
To develop our add-in you are going to need two versions of SharpDevlop on your machine.
One copy (the development copy) you will use to edit and compile your add-in, it is normal to use a regular binary release for this purpose.
The second copy of SharDevelop is a runtime target. That is, you will build your add-in against this copy. But also you will run this copy to load and debug your add-in. It is normal to use a source copy of SharpDevelop for this purpose and to compile it yourself to include debug information: this will allow you to step through and inspect SharpDevelop code as well as that of your add-in.
To get a source copy of SharpDevelop you need to download it from the SubVersion repository (this is known in SubVersion as a "checkout"). Open a Windows Explorer in C:\Dev. Right click inside the folder and select "SVN Checkout...".
PICTURE
The Tortoise SVN dialog appears, you need to tell it where the SharpDevelop SubVersion repository is. Entersvn://svnmirror.sharpdevelop.net/sharpdevelop/branches/2.1/SharpDevelop into the "URL of the repository" field. We are going to put our new add-in in this directory, so let's keep SharpDevelop separate and enter C:\Dev\Target as the "Checkout directory" and click OK.
PICTURE
Tortoise will now check out the whole of SharpDevelop for you to work against. This is several hundred files and can take several minutes to fully download. When completed you should see the source code in your folder.
Now you need to compile SharpDevelop so that you can run it (and your add-in) later on. Don't worry - the SharpDevelop team make this really easy for you. In Windows Exloprer, navigate to the C:\Dev\Target\src directory and double click on debugbuild.bat - this will now compile SharpDevelop with debugging information. Once again this can be a lengthy process depending on your machine and it's memory/processor.
PICTURE
When this is finished you will have a debug copy of SharpDevelop that will act as a runtime target for your new addins.
Open your development version of SharpDevelop (not the source one you just downloaded, but the one you installed with setup.exe). You will be greeted by an empty IDE.
Click File -> New -> Solution... (or press CTRL + SHIFT + N) and bring up the new project dialog box.
PICTURE
Navigate to C# -> SharpDevelop in the categories tree on the left of the dialog and select "SharpDevelop addin" from the list of project templates. Now enter MyTestAddin as a name for your add-in in the "name" field (you could choose anything you wanted here, but for this tutorial lets keep it simple). We will also create the new project in C:\Dev folder so input this in the "location" field and click "create".
PICTURE
The template project has created all the files needed to get a basic hello world application running. And it is nearly ready to run. The particularly important files are:
- MyTestAddin.addin - This is the XML addin metadata file that tells SharpDevelop all about the project (name, copyright, author ect) and the assembly the code for the addin is in. This file also declares our pad extension so that SharpDevelop will add our pad to the target IDE when it runs.
- TestPad.cs - The C# source for our pad, simply creates our user control and returns it to SharpDevelop when asked.
- MyUserControl.cs - The C# source code for our user interface it just has a button, an event handler for the button and a label.
We need to tell SharpDevelop to output the binary version of our plugin into the AddIn folder of the target SharpDevelop instance. To do this, right click on the MyTestAddin project node in the project scout (the tree control on the left of the IDE). Then choose "properties" from the pop-up menu. This allows us to edit the build settings for our new addin project.
PICTURE
Move to the "Compilation" tab and find the "output path" field in the "output" section and click the "..." button. Navigate to the Addins directory under the target copy of SharpDevelop (C:\Dev\Target\Addins) and create a new folder to hold our new Addin called MyTestAddin. Click OK.
We are still not quite done, if you click now you will see that you get a whole pile of build errors. This is because we have not yet told our development copy of SharpDevelop where to find our target copy.
Right click the MyTestAddin project again and select "Add Reference". In the dialog select the ".Net Assembly Browser" page and click "Browse".
PICTURE
Then goto the bin directory of your target SharpDevelop instance (C:\Dev\Target\Bin) and select two assemblies: ISharpCode.Core.dll and ISharpCode.SharpDevelop.dll.
Finally we need to tell SharpDevelop not to copy these assemblies into the output path of our addin. This would be a waste of space as we would end up with lots of copies of these assemlies in the runtime. Select each assembly in the references section of the project scout and in the properties window (on the right of the development IDE) select "False" for the "Local copy" property.
Repeat this for both assembly references that were added.
PICTURE
Now you can click build and your add-in will build happily... but we are not quite finished yet!
The last step is actually running the new add-in inside the target instance of SharpDevelop.
Go to the MyTestAddin properties again and this time select the "debug" tab.
Change the Start Action section to "Start external program" and click "..." to choose the program.
Navigate to the target installation of SharpDevelop and select the SharpDevleop.exe program (C:\Dev\Target\Bin\SharpDevelop.exe) and click OK. This will appear as a path relative to your add-in (..\Target\Bin\SharpDevelop.exe).
You can now click debug to run the target instance of SharpDevelop - complete with your new add-in.
PICTURE
Once you have developed your add-in, and you have tested it, you will then want to share it with the rest of the world!!
SharpDevelop has a special way to do this that makes it easy for the rest of the world to install, update and uninstall your add-in in their installation of SharpDevelop. They are called .sdaddin installation packages.
To create one you first need to add some more metadata to your addin. Open the MyTestAddin.addin file in the route of your addin project.
PICTURE
Then insert the following XML anywhere under the root node (between the <AddIn></AddIn> tags):
{{ <Manifest> <Identity name="MyTestAddin.Test" version="@MyTestAddin.dll"/> <Dependency addin="SharpDevelop" version="2.1"/> </Manifest>}}
This tells SharpDevelop that the identity of your add-in is MyTestAddin.Test and the version is the same as that of the assembly MyTestAddin.dll. Furthermore, you are telling SharpDevelop that this can only be installed on SharpDevelop 2.0.* (any 2.1 version of SharpDevelop).
Now compile your application (either as debug or release depending on what you want to ship). Open Windows Explorer and navigate to your build output directory. Assuming we are still using everything as before (and are happy to ship a debug build) open C:\dev\Target\AddIns\MyTestAddin.
You should have 3 files:
- MyTestAddin.addin - Our addin XML file
- MyTestAddin.dll - Our code packaged as an assembly
- MyTestAddin.pdb - Debugger symbols for our code
Select all of these and then using your favourite ZIP compression utility (I use WinZip) compress these into the root of a ZIP file, MyTestAddin.zip (the name of the ZIP is irrelevant).
Now rename the ZIP extension to MyTestAddin.sdaddin. Windows will moan at you and ask you to confirm the change, click Yes.
PICTURE
You can now ship (copy, email, upload etc.) the .addin file to anyone who wants it. If they have SharpDevelop installed and they double click it the AddIn Manager component will run and ask them if they want to install your addin.
In the future they can use the addin manager (Click on Tools -> AddIn Manager) to uninstall or disable your (or any other) add-in.
PICTURE