A Friendly Way to Deliver Custom ArcMap Tools

After experimenting with different ways to distribute a custom ArcMap tool, the most friendly for the end-user seemed to be an ArcGIS extension delivered with an installer package.  The following will go through some basic steps for coding an ArcMap extension/installer in C# 2008, and assumes you have already developed a custom COM based menu or toolbar. In my case, I am using a simple tool which adds ortho-rectified imagery to an ArcMap session based on the location of a user's click (although the code for the tool will not be discussed).

Coding an ArcMap Extension

Anybody who has used tools from Spatial Analyst or 3D Analyst is familiar with ArcMap extensions.  To enable ArcMap extension, you simply open Tools --> Extensions, and select the appropriate checkbox.

Once you have a custom tool or toolbar written and successfully tested, it is very easy to wrap the tool(s) up as an extension just like Spatial Analyst. Let's take a look.

The first thing you want to do is create a new COM class in the same Visual Studio project as your tools.  Your new class will need to implement the IExtension and IExtensionConfig Interfaces.   Make sure that you include the necessary imports.  Notice the two module level properties m_app and m_extensionState. The first will be used during the implementation of IExtension, and the second for IExtensionConfig.

Looking at the implementation of the IExtension interface below, we see the m_app property which is set during the IExtension's startup method and holds the hook into the ArcMap instance. Here I have also included a name for the extension, but did not add any additional logic to be executed during shutdown.

  With IExtension finished, we move on to IExtensionConfig setting the return message for the extension's description and coding the State property which sets and return the m_extensionState variable.  The State method store info on which the extension has been enabled/disabled from the ArcMap tools -> extensions dialog.

 To round out our extension class, we add the component category registration which registers the component with the Windows registry.  As you would guess, MxExtension is used instead of MxCommandBars or MxCommands.

To finish development of the extension, I have added an additional method to a utilities class which I use to store functions which will be shared among tools.  This new function returns a boolean which indicates whether or not the extension is currently enabled. In this project, I also wanted to ensure layers were present in the map document which is why there is some additional logic.  It would probably be better to separate that logic out into its own function to increase reuse-ability for future endeavors.

I then use this function inside the Enabled method of my tool to add the additional prerequisite that the extension be enabled.

That wraps up creating the extension.  To review, we created a new extension class, implemented the IExtension, and IExtensionConfig interfaces, and rigged up the logic to the ortho tool to enable only when the extension has been enabled.

Creating an Installer/Setup file

Now that we have an extension for the ortho-tool, it is time to create the installer class which will sit inside the same Visual Studio project.  To do this just add a new item and select the Installer Class template.  Switch to the code view and override the methods shown below.  The Install/Uninstall methods will now handle registering/unregistering our tools Assembly with Windows.

 Next, we create a brand New Project, select Other Project Types, and Setup and Deployment Project.  My tools were part of a project called "Boston Tools" so I call the setup project "BostonToolsSetup".  To link the two project together creating our friendly solution for distributing the tools:

• Click on the new project and customize the manufacturer and product name properties for the tool.  These properties will also be used forming the path for where the extension is install on the users computer.
• Right-Click the setup project and select Add->Project Output.  You can then select Primary Output and the ArcMap Extension's project name. 
• Once you see the dependencies are added to the setup project, right-click the setup project again and select view->custom actions.  Double-click on the Application Folder and confirm that Primary Output from is selected and click OK. 

Now you can build the setup package and the setup.exe / project.msi for friendly distribution of your tool, but note that when you make changes to your tool, you will also need to rebuild the setup project.