Geert Bellekens

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.

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
• Add a key to registry containing the name of the assembly and the name of the add-in class
• Register the 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….

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 addin, 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.
Doubleclick on 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.

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
        /// a string
        public String EA_Connect(EA.Repository Repository)
        {
            //No special processing required.
            return "a string";
        }

        ///
        /// 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 name="Location" />the location of the menu
        /// <param name="MenuName" />the name of the menu
        ///
        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
        /// true if a project is opened in EA
        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 name="Location" />the location of the menu
        /// <param name="MenuName" />the name of the menu
        /// <param name="ItemName" />the name of the menu item
        /// <param name="IsEnabled" />boolean indicating whethe the menu item is enabled
        /// <param name="IsChecked" />boolean indicating whether the menu is checked
        public void EA_GetMenuState(EA.Repository Repository, string Location, string MenuName, string ItemName, ref bool IsEnabled, ref bool IsChecked)
        {
            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 name="Location" />the location of the menu
        /// <param name="MenuName" />the name of the menu
        /// <param name="ItemName" />the name of the selected menu item
        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
        ///
        private void sayGoodbye()
        {
            MessageBox.Show("Goodbye World");
            this.shouldWeSayHello = true;
        }

        ///
        /// EA calls this operation when it exists. Can be used to do some cleanup work.
        ///
        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

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:

1. Copy the required files to a convenient location.
   You can find the files needed in your Visual Studio project folder: ..\MyAddin\MyAddin\bin\Release
2. 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
3. Add the registry key
   The easiest way to add the registry key on another computer is to export the key from your registry 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
• Sparx Community Site
• EA forum
• Examples in the EA installation folder: C:\Program Files\Sparx Systems\EA\Code Samples