Testing Your Add-In

Once you’ve coded your add-in, you can easily test it using the Visual Studio debugger. However, debugging can be a bit easier once you review the XML configuration files and understand the add-in life cycle.

Configuration files

When you first create an add-in using the wizard, the wizard generates your class code, and also two XML configuration files that control your add-in’s behavior. These are:

• <Add-in Name> - For Testing.Addin
• <Add-in Name>.AddIn

For Testing.AddIn

When you generate an add-in using the wizard, it creates the XML file and places it into the add-in folder. This file allows Visual Studio to load your add-in, but refers to the assembly DLL in your project folder. Other than the assembly location, this file has the same content as your actual AddIn file you’ll use to install the add-in.

Of course, this can create a catch-22 for future debugging sessions. When Visual Studio loads the add-in, the DLL containing the add-in code is locked by the IDE. Hence, you might see this message when you attempt to tweak and build your add-in:

Unable to delete file ".\bin\CodeWindow.dll".

Access to the path 'C:\Users\..\documents\visual studio 2010\Projects\CodeWindow\CodeWindow\bin\CodeWindow.dll' is denied.

Add-in settings

The add-in configuration file contains some settings that control how and when the add-in is loaded. These settings can be found in the <Addin> element in the XML file.

LoadBehavior

This value indicates when the add-in is loaded. The available values are:

• 0: Add-in must be loaded manually.
• 1: Add-in automatically loads when IDE starts.
• 4: Add-in loads when started from command prompt.

You will rarely see option 4, since most add-ins provide a UI and would not make sense when run from the command line. Option 0 is good for debugging, because the add-in’s DLL is only loaded when you open the add-in, not every time you open the IDE.

CommandPreload

This value determines if the add-in is loaded via the Add-in Manager or automatically when Visual Studio starts (the first time after the add-in file is installed):

• 0: Add-in must be manually started by Add-in Manager.
• 1: Add-in is loaded first time when Visual Studio starts after install.

Sometimes, when you are debugging an add-in, you might need to set Command Preload to 0 in the add-in files to allow you to update the DLL when you compile your add-in. If you set it to 1, you might get the “Unable to delete” error when you attempt to rebuild your add-in file.

I recommend generating the Add-in Wizard without the add-in being loaded at start-up to make it easier for testing and debugging. Once you are ready to deploy your add-in, you can manually change the Load Behavior flag to 1 if you want your add-in loaded at start-up time.

Add-in life cycle

The Load Behavior setting controls which events from your connect class are called and when. Regardless of the setting, the first two events are always:

• OnConnect with the cm_UISetup connect mode.
• Disconnect with the dm_UISetup disconnect mode.

This is why when you attach your add-in module to Visual Studio during the CM_UISetup mode, it is always called.

0: Call Manually

When set to Call Manually, the add-in does not get called again until you actually request it from the menu. The command has been added to the IDE, and the menu updated, but the code is not loaded. Once you select the item from the menu or toolbar, Connect with cm_AfterStartup is called.

At this point, the add-in is loaded to memory. You can manually unload it using the Add-in Manager, in which case Disconnect with dm_userShutdown is called. If you don’t close it manually, the events OnShutdown and Disconnect – with dm_HostShutdown are called. If you’ve closed it manually, these events will not be called since the add-in is no longer in memory.

If you plan on loading the add-in manually, be sure to set any configuration information you want to save during the Disconnect method.

1: Load at Start-up

When set to load at start-up, additional events are triggered since the IDE is loading your add-in as part of the start-up code:

• Connect with cm_Startup.
• Adds-in update event.
• Start-up complete event.

This means that once the IDE makes its appearance, your add-in module is loaded in memory. Unless you unload it manually using the Add-in Manager, the following events will be triggered when the user shuts down Visual Studio:

• Begin Shutdown.
• Disconnect with dm_HostShutdown.

The events that your add-in will respond to are handled differently. During debugging sessions, I generally only load the add-in when called from the menu. However, once the code is ready for deployment, I typically set the flag to 1, load at start-up.

Debugging

When you debug your add-in by pressing F5, a second instance of Visual Studio will be loaded. When this instance loads, it will see the newly added XML file and load the add-in module into Visual Studio. At this point, you can step through the add-in and debug the code or you can run it and test its behavior.

Common mistakes

Here are some common mistakes that might pop up while using your add-in.

Add-in not enabled on menu

If your add-in is not available on the menu, check the QueryStatus method and ensure that the return status variable contains both Command Supported and Command Enabled.

Add-in never invoked

If the command name in the Exec command does not match the add-in class name and friendly name in the add-in XML file, your exec method will never reach your code.

Events not triggering

Be sure the events you are expecting to be called are compatible with the Load Behavior mode set in the XML file.

Not seeing code changes

Sometimes, your add-in code appears not to recognize recent code changes. If this is the case, the most likely culprit is that the wrong DLL version was loaded. I would recommend making sure the Load Behavior flag is set to 0, restarting the IDE, and running the add-in from the menu. This should load the most recent version of the DLL.

Removing an add-in module

There are times you might need to remove an add-in module entirely. The easiest way to do this is to find and delete (or rename) the Addin XML file in any of the paths specified in the Add-in and Macros properties. In the Tools menu, select Options, and then Environment.

Pesky “Unable to delete” message

Occasionally, you might not be able to shake that “Unable to Delete” message, no matter how many times you restart the IDE and tweak settings. If your add-in is not marked as load on start-up, the DLL should not be loaded. However, in the event you cannot unload it, you can start the IDE with the /SafeMode switch, which loads Visual Studio without any add-in modules at all.

Even if you start the IDE in Safe Mode, you can still debug since the second instance of the IDE will start in regular mode without the /SafeMode switch being applied. If you are having trouble working with an add-in, consider making an add-in free shortcut on your desktop to run the IDE with add-ins.