Part of creating useful Reflector Addins should be making the functionality easy to find in the UI.  Some addins, such as a language, won't need the addin writer to provide a UI to access.  However, most addins need to provide the user a way to access the addin logic.  Some ways to do this are:

• Add a command to an existing menu (with or without a short-cut key combination assigned)
• Create your own menu
• Add a sub menu to a menu (good to group commands logically)
• Add a toolbar button
• Add commands/submenus to context menus

In this entry, I provide examples that perform each of these.  The example code can be downloaded at: http://jasonhaley.com/files/ReflectorUI.zip

Adding a command to an existing menu

In order to make your addin available from an existing menu, the 'Tools' menu for example, you need to add an item to the menu and connect an event handler to your addin logic.

The quickest way to get an addin started and do this, is to download my Reflector Addin Starter Kit, and create a new .NET Reflector Add-in project - the code to add an item to the 'Tools' menu will already be done for you.  Listing 1 shows the lines of code that do the work of adding a command button to the Tools menu in the starter kit's package class.

Listing 1 - Adding a button to the Tools menu

public void Load(IServiceProvider serviceProvider)
{
    // Create a command button, separator on the Tools menu and wire up the button click event
    this.commandBarManager = (ICommandBarManager)serviceProvider.GetService(typeof(ICommandBarManager));
    this.separator = this.commandBarManager.CommandBars["Tools"].Items.AddSeparator();
    this.button = this.commandBarManager.CommandBars["Tools"].Items.AddButton("ReflectorAddin3",
      new EventHandler(this.Button_Click));
}

The CommandBarManager provides access to Reflector's menus and toolbars.  In order to access the CommandBarManager you need to retrieve it from the IServiceProvider instance passed into the Load() of the package (this method is where all addin logic begins).  Menus, context menus and toolbars are all collections of ICommandBarItems - which may be any of the following:

• ICommandBarMenu
• ICommandBarSeparator
• ICommandBarButton
• ICommandBarComboBox
• ICommandBarCheckBox

To create any of these ICommandBarItems, you use the AddXxx() and InsertXxx() methods - Listing 1 shows the usage of AddSeparator() and AddButton().  The CommandManager contains a collection of CommandBars, giving access to the items collection - which expose the AddXxx() and InsertXxx() methods.  By default, there are currently 22 CommandBars in Reflector, here are their identities/names:

• MenuBar
• ToolBar
• Browser.Default
• Browser.Assembly
• Browser.AssemblyReference
• Browser.Module
• Browser.ModuleReference
• Browser.Resource
• Browser.Namespace
• Browser.TypeDeclaration
• Browser.TypeReference
• Browser.MethodDeclaration
• Browser.MethodReference
• Browser.FieldDeclaration
• Browser.PropertyDeclaration
• Browser.EventDeclaration
• Browser.BaseType
• Browser.DerivedType
• Formatter
• Bookmark.Default
• SearchWindowContextMenu
• AnalyzerWindow

Using the CommandManager and the command bar's name, you can easily add/edit/remove items from menus, context menus and tool bars in Reflector.  Each item has it's own unique identity/name you use to refer to it in the CommandBars collection.  For instance - the code in Listing 1 and Listing 2 both refer to the CommandBar with the identity of "Tools" instead of accessing the "MenuBar" CommandBar and its child the "Tools" menu.

Listing 2 shows some code that adds a commad button, with an image and short-cut key combination for starting my addin logic.  Figure 1 shows a screen shot of what the 'Tools' menu looks like after the addin has loaded.

Listing 2 - Add an item to the Tools menu with an image and a shortcut key binding

private void AddToToolsMenu(Image debrisImage)
{
    // Add to the tools menu
    this.button1 = this.commandBarManager.CommandBars["Tools"].Items.AddButton("Break",
        debrisImage,
        new EventHandler(this.Button_Click),
        Keys.Control | Keys.Shift | Keys.B);
}

Figure 1 - New break item on Tools Menu

If your addin is simple and you only need a menu item or two for the functionality, the just adding a couple of command buttons to the 'Tools' menu should work well for you - but if you have more than a couple of items, then you might want to create your own menu for you addin.

Creating your own menu

When your addin is more complicated, you might want to add your own menu to Reflector's menu bar to organize all your addin commands - like some the more feature rich Visual Studio addins do.

In order to add your own menu to the menu bar, you first need to determine where you want it to show up.  In Listing 3, I decided I wanted my menu to show up to the right of the 'Tools' menu - which would make it the third menu from the last.  In order to do this, I used the InsertMenu() to create a new menu before the second to the last menu (count - 2).  Adding items to the menu is just like mentioned above, except now you should actually have a reference to the menu and not have to access it through the CommandBars (like we did with the 'Tools' menu above).

Listing 3 - Creating a new menu

private void CreateDebrisMenu(Image debrisImage)
{
    // will need count of items to insert before the tools menu (count-2) - could check the caption value
    int count = this.commandBarManager.CommandBars["MenuBar"].Items.Count;

    // Create a new menu on the menubar
    debrisRootMenu = this.commandBarManager.CommandBars["MenuBar"].Items.InsertMenu(count - 2, "Menu.Debris",
        "&Debris");
    this.button = this.debrisRootMenu.Items.AddButton("Break",
        debrisImage,
        new EventHandler(this.Button_Click),
        Keys.Control | Keys.Shift | Keys.B);
}

Below in Figure 2, you can see the new menu named 'Debris' just to the right of the 'Tools' menu.  The new Debris menu has one button and a sub menu - which we will get into next.

Figure 2 - New menu

WARNING: Out of order screen shot. The SubMenu item on the 'Debris' menu would not be there if only the code in Listing 3 was added, but since I took the screen shots using the code provided with this entry, the sub menu is already visible.

Creating and adding items to a submenu

Sometimes you want to group commands into a submenu, for instance on Windows LiveWriter (the application I'm writing this blog entry in), the context menu groups all the align options into a single submenu named 'Align'.  A submenu on an existing menu might be a good option if you have 3 or 4 commands you want to add for you addin.  

To create a submenu, you need a reference to a menu that will serve as the parent menu - in Listing 4, I use the debrisRootMenu member level variable.  This menu was the one we created above in Listing 3.  Once you have a reference to the parent menu (debrisRootMenu in this case), you need to use the same syntax as we used to create the menu above.  In Listing 4, I used the AddMenu() instead of the InsertMenu() since I just want the sub menu added to the end of the items (not inserted in the middle of them).

Listing 4 - Creating a submenu

private void AddSubMenu(Image debrisImage)
{
   // Add a submenu to the Debris menu
   debrisSubMenu = debrisRootMenu.Items.AddMenu("Menu.Debris.SubMenu", "Sub&Menu");
   button2 = this.debrisSubMenu.Items.AddButton("Break2",
       debrisImage,
       new EventHandler(this.Button_Click),
       Keys.Control | Keys.Shift | Keys.B);
}

Figure 3 - A new submenu

Menus and submenus are nice, but if you find yourself using certain menu items often, you might want to add a tool bar button to access your commands faster.

Adding to the toolbar

Reflector's Toolbar is one of the available CommandBars which you can add to, but in this case you'll need a nice meaningful 16x16 image to display for the toolbar button.  The image I use in the buttons of the menu items above is what I used for my toolbar button (as you can see in Figure 4 below).

First thing you'll need to do is create an image, I used a 16x16 png image for the example.  Once you have an image to use for your toolbar button, you need to decide where you want it to show up.  In my case I wanted to keep the 'Your Feedback' button as the last button on the toolbar.  The code in Listing 5 shows how I added by own toolbar button to the left of the language drop down.

Listing 5 - Add a toolbar button to the ToolBar

private void AddToolbarButton(Image debrisImage)
{
    // Add a button to the toolbar
    int toolCount = commandBarManager.CommandBars["ToolBar"].Items.Count;

    separator2 = commandBarManager.CommandBars["ToolBar"].Items.InsertSeparator(toolCount - 2);
    button4 = commandBarManager.CommandBars["ToolBar"].Items.InsertButton(toolCount - 1, "Break",
        debrisImage,
        new EventHandler(this.Button_Click),
        Keys.Control | Keys.Shift | Keys.B);
}

Figure 4 - A custom toolbar button

Menus and toolbar buttons are globally accessible, and sometimes you only want your addin commands to be available in a certain context - like when someone right clicks on an assembly name in the Assembly Browser (the tree control).  This is were context menus come in handy.

Adding to a context menu

Context menus are shown when the user right-clicks on certain locations - giving the ability to provide a context to functionality the user might want at that point in time.

If you read Lutz Roeder's article Introduction to the .NET Reflector Add-In Model, you'll notice at the bottom he lists some of the context menus id's and a description of what they are.  The list of 5 context menus he has (compare his list to the 22 command bar names mentioned above), are the majority of the context menus you would want to add your addin command to in order to be useful for the user. You might have to try out adding your command to different context menus until you figure out which is the right one for your situation.  Listing 6 shows the I used to add items to the Browser.Assembly context menu - which shows when you right click on the assembly name in the Assembly Browser (shown in Figure 5).

Listing 6 shows the adding of a submenu to the context menu (not just a button or separator) - which is the same idea as shown above in Listing 4/Figure 3 with the menu.  Figure 5 shows this code in action.

Listing 6 - Adding to a Context Menu

private void CreateSubmenuOnContextMenu(Image debrisImage)
{
    // Add a separator and submenu to the Browser.Assembly context menu
    separator = commandBarManager.CommandBars["Browser.Assembly"].Items.AddSeparator();
    subAssemblyContextMenu = commandBarManager.CommandBars["Browser.Assembly"].Items
        .AddMenu("Assembly.Debris", "&Debris");

    // Add a button to the submenu
    button3 = this.subAssemblyContextMenu.Items.AddButton("Break3",
        debrisImage,
        new EventHandler(this.Button_Click),
        Keys.Control | Keys.Shift | Keys.B);
}

Figure 5 - Adding a Submenu to a Context Menu

Summary

Providing easy UI accessibility to your addin's commands is an important part of a useful addin.  Depending on how many features you expose and how context sensitive your functionality is, you have several options in Reflector to expose your commands to the user:

1. Menu buttons (also reachable by assigning short-cut keys)
2. Complete menus
3. Sub menus
4. Toolbar buttons
5. Context menus (with or without submenus)