Writing an Extensible Application – Part 3: IC#Code Addin Tree

 

Hi All,

This is the third part of my extensibility series and this time I would like to describe an open source extensibility mechanism which is part of SharpDevelop called the Addin Tree. To use the Addin Tree all you have to do is to download the latest version of SharpDevelop and reference the file ICSharpCode.Core.dll in your project. For my example I will be using the dll from version 4.1 which can be downloaded from the site.

The Addin Tree (AT for short) is a very simple mechanism based on XML files called Addins. Each Addin file may contain one or more Path elements which maps all child elements of the Path element to a specific node within the AT. The AT is a tree data structure where each node may contain one or more Codons that describe any user data. Each node in the tree can be reached using a path statement of the form “A/B/…/C/D” where A,B,C are the ids of the nodes to pass on the way to node D which is represented by this statement. When the application loads it can read any number of Addins and build the tree. Later, you may access any node of the tree and Build the codons within this node. Each codon is built by a Doozer which is mapped to that specific codon (the core mechanism provides some basic doozers to build elementary program elements).

The addins are defined using XML files that contain the following elements:

• Root Addin Element which contains some general data on the addin.
• The Manifest Element which describes the addin file.
• The Runtime Element which defines the Doozers and the assemblies needed in the addin.
• The Paths Elements which contain the codons of the addin.

Here is an example of such an Addin file (from SharpDevelop):

19.         <AddIn name= "AddInScout"
20.              author= "Satguru P Srivastava"
21.           copyright= "prj:///doc/copyright.txt"
22.                 url= "http://home.mchsi.com/~ssatguru"
23.        description = "Display AddIn Information"
24.        addInManagerHidden = "preinstalled">
25.  
26.   <Manifest>
27.     <Identity name = "ICSharpCode.AddInScout"/>
28.   </Manifest>
29.  
30.   <Runtime>
31.     <Import assembly="AddInScout.dll"/>
32.   </Runtime>
33.  
34.   <Path name = "/Workspace/Tools">
35.     <MenuItem id = "ShowAddInScout"
36.                   label = "AddIn Scout"
37.                   class = "AddInScout.AddInScoutCommand"/>
38.   </Path>
39. </AddIn>

The Balls Game

Back to our example… To use the Addin tree extensibility I made some small changes. First, the build process now builds the entire game into a single root Bin folder and all the Addins into an Addins folder. This structure is needed for the Runtime mechanism of the AT. I created a main addin file for the application called Main.addin which contains the definition of the three Doozers I will use to support the extensibility of my application. The doozers are defined in the Interfaces project as internal classes and they contain some logic to build the required class from the codon definition. The main addin file looks like this:

1. <AddIn name="Balls Main Addin"
2.        author="Boris Kozorovitzky"
3.        description="The main addin of the game"
4.        addInManagerHidden="preinstalled">
5.  
6.   <Manifest>
7.     <Identity name="MainAddin"/>
8.   </Manifest>
9.  
10.   <Runtime>
11.     <Import assembly=":BallsInterfaces">
12.       <Doozer name="Collider" class="BallsInterfaces.Doozers.ColliderDoozer"/>
13.       <Doozer name="Mover" class="BallsInterfaces.Doozers.MoverDoozer"/>
14.       <Doozer name="Drawer" class="BallsInterfaces.Doozers.DrawerDoozer"/>
15.     </Import>
16.   </Runtime>
17. </AddIn>

One important thing to notice here is that the Import element tells the extensibility mechanism where to find the doozers. In this case I use the “:” syntax to tell it that the required assembly is in the Bin folder. You will understand why this is important next.

The extensibility Addin may sit anywhere in the Addin folder (any directory structure) and it looks like this:

1. <AddIn name="Balls Addin"
2.        author="Boris Kozorovitzky"
3.        description="Adds some balls to the game"
4.        addInManagerHidden="preinstalled">
5.  
6.   <Manifest>
7.     <Identity name="AddinExtensibility"/>
8.   </Manifest>
9.  
10.   <Runtime>
11.     <Import assembly=":BallsInterfaces"></Import>
12.     <Import assembly="AddinExtensibility.dll"></Import>
13.   </Runtime>
14.  
15.   <Path name="/Balls/Colliders">
16.     <Collider type="AddinExtensibility.BasicCollider"></Collider>
17.     <Collider type="AddinExtensibility.StopperCollider"></Collider>
18.   </Path>
19.  
20.   <Path name="/Balls/Movers">
21.     <Mover type="AddinExtensibility.BasicMover"></Mover>
22.     <Mover type="AddinExtensibility.ParabolicMover"></Mover>
23.  
24.   </Path>
25.  
26.   <Path name="/Balls/Drawers">
27.     <Drawer type="AddinExtensibility.BasicDrawer" fill="Yellow"></Drawer>
28.       <Drawer type="AddinExtensibility.BlinkerDrawer"></Drawer>
29.  
30.   </Path>
31.  
32. </AddIn>

Note that the import section references the Dll where all the classes are defined – AddinExtensibility.dll and the BallsInterfaces assembly. The main section of the addin contains three Path elements (I chose the path randomly to something logical) and each path contains Codon which can be built by a specific doozer (see doozer mapping in the main addin file). The collider doozer code will reveal the nice trick which the import does for us:

9. internal class ColliderDoozer:IDoozer
10. {
11.   public object BuildItem(BuildItemArgs args)
12.   {
13.     string stringType = args.Codon.Properties["type"];
14.     object result = args.AddIn.CreateObject(stringType);
15.     return result;
16.   }
17.  
18.   public bool HandleConditions
19.   {
20.     get { return false; }
21.   }
22. }

The AT mechanism will call the BuildItem method on any codon which is mapped to that doozer. In this case I expect the element to have a “type” attribute where the type of the object is written. Now that the type is resolved I can call the CreateObject method which will do the magic for us and find the correct type from the assemblies referenced in the Runtime section and thus returning the correct item each time. To show you how the extensibility mechanism can work for us I added two editable properties to the BasicDrawer type. The Drawer doozer calls a new method – Configure which takes the codon and extracts the needed arguments from it. Now we can control the color and the diameter of the basic drawer directly from the addin file!

11. public class BasicDrawer : IDrawer
12.   {
13.     private static double _initialDiameter;
14.     private static Brush _initialBrush;
15.  
16.     public void Initialize(IBall ball)
17.     {
18.       ball.Diameter = _initialDiameter;
19.       ball.Fill = _initialBrush??Brushes.Blue;
20.     }
21.  
22.     public void Tick(IBall ball)
23.     {
24.  
25.     }
26.  
27.     public object Clone()
28.     {
29.       return new BasicDrawer();
30.     }
31.  
32.  
33.     public void Configure(ICSharpCode.Core.Codon codon)
34.     {
35.       _initialDiameter = 15;
36.       if (codon.Properties.Contains("diameter"))
37.       {
38.         string diameterString = codon.Properties["diameter"];
39.         double diameter = 15d;
40.         Double.TryParse(diameterString, out diameter);
41.         _initialDiameter = diameter;
42.       }
43.  
44.       _initialBrush = null;
45.       if (codon.Properties.Contains("fill"))
46.       {
47.         string fillString = codon.Properties["fill"];
48.         _initialBrush = (SolidColorBrush)new BrushConverter().ConvertFromString(fillString);
49.       }
50.  
51.     }
52.   }

In the example I set the color of all the balls created with the BasicDrawer to Yellow but the user may chose to edit this value as he wishes.

The extensibility initialization code changed slightly and now it loads all the addin files from the Addins path:

93. private void LoadExtensibility()
94. {
95.   Assembly applicationAssembly =  Assembly.GetAssembly(GetType());
96.   string extensibilityPath = System.IO.Path.Combine(System.IO.Path.GetDirectoryName(applicationAssembly.Location), ConfigurationManager.AppSettings["AddinsPath"]);
97.   string[] addinFiles = System.IO.Directory.GetFiles(extensibilityPath, "*.addin",System.IO.SearchOption.AllDirectories);
98.   AddInTree.Load(new List<string>(addinFiles), new List<string>());
99.   foreach (ICollider collider in AddInTree.BuildItems<ICollider>("/Balls/Colliders", null))
100.     Colliders.Add(new StrategyAdapter(collider));
101.  
102.   foreach (IMover mover in AddInTree.BuildItems<IMover>("/Balls/Movers", null))
103.     Movers.Add(new StrategyAdapter(mover));
104.  
105.   foreach (IDrawer drawer in AddInTree.BuildItems<IDrawer>("/Balls/Drawers", null))
106.     Drawers.Add(new StrategyAdapter(drawer));
107. }

This extensibility mechanism allows great flexibility and it is simple enough to cover many useful scenarios. In the worst case you can always take a look at the source code to see how things work under the hood. If you are looking for something simple yet powerful to extend your application you should definitely consider the Addin Tree.

Thank you for reading. You can get the new sources from my SkyDrive here:

 

Boris