Tutorial: Create your first C# Enterprise Architect add-in in 10 minutes by Geert Bellekens geert@bellekens.com originally published on http://geertbellekens.wordpress.com Contents Prerequisites... 2 EA s addin architecture... 2 Step 1: Create the add-in dll... 3 Step 2: Add the registry key... 8 Step 3: Try it out in EA... 9 Distributing the add-in... 9 More resources... 10 2011-02-01 Author: Geert Bellekens Page 1 of 10
Enterprise Architect from Sparx Systems is a great UML Case tool, but you can make it even better by adding your own functionality in the form of an add-in. This post will take you through the basic steps to create your first C# EA add-in in about 10 minutes. You can use a number of programming languages to create add-ins for EA, but personally I like C# the best. Prerequisites Before you start you should have following software on your computer ready to use: Enterprise Architect (download the fully functional trial if you don t have it installed yet) Visual Studio (I m using the free Visual C# 2010 Express for this tutorial) EA s addin architecture To fully understand the steps necessary to get your add-in running you should first understand how EA s add-in architecture works. cmp EA Addin Enterprise Architect 3. Use MyAddin.dll :MyAddinDLL ProjectName = MyAddin 1. Read 2. Read Location of MyAddin.dll Windows Registry :Registry Key FQ Name = [HKEY_CURRENT_USER\Software\Sparx Systems\EAAddins\MyAddin] Value = MyAddin.MyAddinClass COM codebase entries When EA starts up it will read the registry key [HKEY_CURRENT_USER\Software\Sparx Systems\EAAddins]. Each of the keys in this location represents an add-in for EA to load. The (default) value of the key contains the name of the assembly and the name of the add-in class separated with a dot. EA then asks Windows for the location of the assembly, which is stored on the COM codebase entries in the registry, and it will use the public operations defined in the add-in class.so in order for our add-in to work we ll need to: Create the add-in dll containing the add-in class 2011-02-01 Author: Geert Bellekens Page 2 of 10
Add a key to registry containing the name of the assembly and the name of the add-in class Register the dll in the COM codebase entries in the registry Step 1: Create the add-in dll So open up Visual Studio, start a new project, and choose Class Library as type of project. The first thing we need to do is to add the EA API assembly to our references, so choose Add Reference. 2011-02-01 Author: Geert Bellekens Page 3 of 10
Select the Browse tab, browse tot the EA installation folder (default: C:\Program Files\Sparx Systems\EA) and choose the file Interop.EA.dll. This will allow us to use the classes/interfaces defined by EA s API. And since we will be using a messagebox for our first add-in, select the.net tab, scroll down and select System.Windows.Forms Then there are some build options we need to configure. First we re going to tell Visual Studio to build our dll so it can be used as a COM object. Double-click on the properties folder under your project, click on the button Assembly Information and tick the little checkbox on the bottom that says Make assembly COM-visible Then we would also like Visual Studio to register the dll in the COM codebase entries in the registry each time it builds our little project. To do so go into the Build tab of the project properties and tick the checkbox Register for COM interop. 2011-02-01 Author: Geert Bellekens Page 4 of 10
Then we rename the default Class1.cs to MyAddinClass.cs and replace the existing template code by the following: using System; using System.Windows.Forms; namespace MyAddin public class MyAddinClass // define menu constants const string menuheader = "-&MyAddin"; const string menuhello = "&Say Hello"; const string menugoodbye = "&Say Goodbye"; // remember if we have to say hello or goodbye private bool shouldwesayhello = true; /// Called Before EA starts to check Add-In Exists /// Nothing is done here. /// This operation needs to exists for the addin to work /// <param name="repository">the EA repository</param> /// <returns>a string</returns> public String EA_Connect(EA.Repository Repository) //No special processing required. return "a string"; 2011-02-01 Author: Geert Bellekens Page 5 of 10
/// Called when user Clicks Add-Ins Menu item from within EA. /// Populates the Menu with our desired selections. /// Location can be "TreeView" "MainMenu" or "Diagram". /// <param name="repository">the repository</param> /// <param name="location">the location of the menu</param> /// <param name="menuname">the name of the menu</param> /// <returns></returns> public object EA_GetMenuItems(EA.Repository Repository, string Location, string MenuName) switch (MenuName) // defines the top level menu option case "": return menuheader; // defines the submenu options case menuheader: string[] submenus = menuhello, menugoodbye; return submenus; return ""; /// returns true if a project is currently opened /// <param name="repository">the repository</param> /// <returns>true if a project is opened in EA</returns> bool IsProjectOpen(EA.Repository Repository) try EA.Collection c = Repository.Models; return true; catch return false; /// Called once Menu has been opened to see what menu items should active. /// <param name="repository">the repository</param> /// <param name="location">the location of the menu</param> /// <param name="menuname">the name of the menu</param> /// <param name="itemname">the name of the menu item</param> /// <param name="isenabled">boolean indicating whethe the menu item is enabled</param> /// <param name="ischecked">boolean indicating whether the menu is checked</param> public void EA_GetMenuState(EA.Repository Repository, string Location, string MenuName, string ItemName, ref bool IsEnabled, ref bool IsChecked) 2011-02-01 Author: Geert Bellekens Page 6 of 10
if (IsProjectOpen(Repository)) switch (ItemName) // define the state of the hello menu option case menuhello: IsEnabled = shouldwesayhello; break; // define the state of the goodbye menu option case menugoodbye: IsEnabled =!shouldwesayhello; break; // there shouldn't be any other, but just in case disable it. default: IsEnabled = false; break; else // If no open project, disable all menu options IsEnabled = false; /// Called when user makes a selection in the menu. /// This is your main exit point to the rest of your Add-in /// <param name="repository">the repository</param> /// <param name="location">the location of the menu</param> /// <param name="menuname">the name of the menu</param> /// <param name="itemname">the name of the selected menu item</param> public void EA_MenuClick(EA.Repository Repository, string Location, string MenuName, string ItemName) switch (ItemName) // user has clicked the menuhello menu option case menuhello: this.sayhello(); break; // user has clicked the menugoodbye menu option case menugoodbye: this.saygoodbye(); break; /// Say Hello to the world private void sayhello() MessageBox.Show("Hello World"); this.shouldwesayhello = false; /// Say Goodbye to the world 2011-02-01 Author: Geert Bellekens Page 7 of 10
private void saygoodbye() MessageBox.Show("Goodbye World"); this.shouldwesayhello = true; work. /// EA calls this operation when it exists. Can be used to do some cleanup public void EA_Disconnect() GC.Collect(); GC.WaitForPendingFinalizers(); Now all we need to do is build the project, and the add-in dll is finished. Step 2: Add the registry key In order to let EA know there is a new add-in to be loaded we need to add a key in the registry in the location: HKEY_CURRENT_USER\Software\Sparx Systems\EAAddins To do so open up the Windows registry editor by clicking Start Run and type regedit Then browse to the HKEY_CURRENT_USER\Software\Sparx Systems\EAAddins key, right click and add a key with the name of the project in Visual Studio, in our case MyAddin The registry editor will automatically create a default value for the new key. Doubleclick on the (Default) value on the right pane, and enter the value in the form of [ProjectName].[ClassName], so in this case MyAddin.MyAddinClass 2011-02-01 Author: Geert Bellekens Page 8 of 10
Step 3: Try it out in EA Alright, now the add-in is ready to be used. So fire up EA, open a project and right click on an element in the projectbrowser, or a diagram. You should now see an additional menu option with the options we defined. Congratulations! You have just created your first C# add-in for EA Distributing the add-in Once you have finished your add-in you will probably want to share it with others. There are three steps needed to install your add-in on another computer: Copy the required files to a convenient location. You can find the files needed in your Visual Studio project folder:..\myaddin\myaddin\bin\release Register your add-in dll in the COM codebase entries in the registry using regasm.exe Open up a command prompt in folder where you copied the add-in dll and register the dll with the /codebase option. In my case that command would be: %WINDIR%\Microsoft.NET\Framework\v4.0.30319\regasm MyAddin.dll /codebase Add the registry key The easiest way to add the registry key on another computer is to export the key from your registry 2011-02-01 Author: Geert Bellekens Page 9 of 10
using regedit. This will save the information stored in the key in a.reg file, which you can execute by doubleclicking. These three steps can of course be automated by your favorite installer program. More resources EA User Guide: http://www.sparxsystems.com/enterprise_architect_user_guide/8.0/automation_and_scripts/au tomation_interface.html Sparx Community Site: http://community.sparxsystems.com/ EA Forum http://www.sparxsystems.com/cgi-bin/yabb/yabb.cgi?board=automation Modelling Tooling: http://themodelfactory.org/modelling_tooling Tooling Framework Pattern: http://themodelfactory.org/pattern:modelling_tooling_framework Examples in the EA installation folder: C:\Program Files\Sparx Systems\EA\Code Samples 2011-02-01 Author: Geert Bellekens Page 10 of 10