Creating an application extension

The easiest way to add a menu is to build an add-in. For more information, see Building add-ins for ArcGIS for Desktop.

About creating an application extension

The simplest form of an extension is created by implementing the IExtension interface. This interface allows you to set the name of the extension and specify the action that occurs when the extension starts or shuts down. Use the Name property to set a Name string for this extension—this will be a programmatic string—which can be used to identify your extension. When IApplication.FindExtensionByName is called, the Name property is used to identify the extension. This will not be the name shown on the Extensions dialog box. For more information, see the Creating configurable extensions section in this topic.

The Startup method is used to perform an action when the extension is loaded. This method has a parameter, initializationData, that is a reference to the object this extension is registered to. For example, if the extension is loaded in ArcMap, the object type passed in by initializationData will be ESRI.ArcGIS.ArcMap.Application. The Shutdown method is used to perform an action when the extension is unloaded.

Register the class in the appropriate extension component category based on the target application. When the target application starts, this extension is automatically loaded.

The following are the available extension component categories:

ArcCatalog—Esri Gx extensions
ArcMap—Esri Mx extensions
ArcScene—Esri Sx extensions
ArcGlobe—Esri GMx extensions

The order of extension loading cannot be controlled. The extensions are loaded in a class identifier (CLSID) order using the appropriate component category. In certain circumstances, you might want to share data between extensions. In this case, the data should not be associated with one extension but instead, with another helper class. Each extension can then verify if the helper object has been created, and if not, the extension can create it. Once the helper object is created by the first initialized extension, the other extensions can access the data it contains. Any document-specific code should not be placed in the extension loading stage. The extensions are loaded before any document opens.

Not every extension needs to be loaded when the application starts. For more information, see the Loading just-in-time extensions section in this topic.

Complete the following steps to create an extension (Steps 1–3) that also listens to document events (Steps 4–7):

Select the Application Extension item template on the New Item dialog box under the ArcGIS Desktop category. See Using item templates to extend ArcObjects.
Name the new class and click Add.
Choose any of the Blank extension options based on the target desktop application.
Locate the TODO comments in the newly generated class and add code accordingly.

Change the Name property, which is used as the extension identifier.
After getting a hold to the hosting application in the Startup method, perform extension initialization.
Remember to clean up resources in the Shutdown implementation.

To listen to document events, insert the code snippet—Add Event Wiring for New and Open Documents—(under ArcGIS Desktop, Mapping, then Map Documents) by right-clicking at the end of the class and selecting the Insert Snippet command.
The code snippet requires adding a project reference to ESRI.ArcGIS.ArcMapUI.dll.
In the IExtension.Startup implementation, call the SetupDocumentEvent() method inserted by the snippet to wire the document event to the extension.
Modify the code in the OnNewDocument and OnOpenDocument event handlers accordingly.

Creating configurable extensions

Extensions that are listed on the Extensions dialog box can be selected (checked) on and off. To create a configurable extension allowing users to toggle its enabled state, implement the optional IExtensionConfig interface.

The ProductName and Description properties display on the Extensions dialog box.

In the State property, use the incoming ExtensionState parameter (esriExtensionState enumeration) to determine whether your extension should be enabled, disabled, or unavailable. When the state is enabled, the extension shows as selected (checked) on the Extensions dialog box. The selected state of the extension is saved in the user settings in the registry (for example, HKEY_CURRENT_USER\Software\ESRI\Desktop10.1\ArcMap\Extensions).

Complete the following steps to create a configurable extension:

Select the Application Extension item template on the New Item dialog box under the ArcGIS Desktop category. Name the new class and click Add.
Choose any of the Configurable extension options based on the target desktop application.
Locate the TODO comments and add code accordingly, for example, see the following:

Change the StateCheck() helper method to update the extension enabling logic called by the IExtensionConfig.State property.
IExtensionConfig.ProductName returns a localizable caption shown on the Extensions dialog box.
The string returned by the IExtensionConfig.Description property shows on the bottom of the Extensions dialog box when it is selected in the top list. To span multiple lines in a single string, use the .NET Framework System.Environment.NewLine Constant.

The configurable extension item template class also implements IPersistVariant. You can remove this optional interface implementation by deleting the implement statement and its associated members in the code file.

With a custom extension, you have full control over what happens when your extension is turned on or off; however, it is a good idea to follow the same general procedures as the existing ArcGIS extensions. The following explains how the ArcGIS extensions work when they are turned on or off on the Extensions dialog box.

The following occurs when a user selects (checks) one of the ArcGIS extension check boxes on the Extensions dialog box:

The selected state of the extension is saved to the user settings in the registry. This is done by the application—it is not the responsibility of the extension.
The extension requests a license from the license manager. If a license is available, the tools are enabled on the toolbar delivered by the extension.
If a license is not available, the tools are disabled on the toolbar delivered by the extension. Also, text stating that the license is unavailable shows to the right of the extension name on the Extensions dialog box. Again, this is done by the application—it is not the responsibility of the extension.

The following occurs when a user clears (unchecks) one of the ArcGIS extension check boxes on the Extensions dialog box:

The extension verifies that it is not used in that application.
If the extension is used, the extension does not allow itself to be unchecked and a warning message appears.
If the extension is not used in the application, the uncheck completes successfully and the following remaining steps occur.
The unchecked state of the extension is saved in the user settings in the registry. Again, this is done by the application—it is not the responsibility of the extension.
If the toolbar for the extension is active, the appropriate tools, commands, and so on, are disabled.
The extension informs the license manager that it is no longer using the extension license in the application and the license manager releases the license for that application.

The IExtensionConfig interface is independent of the Esri licensing implementation; therefore, as a developer, you can incorporate a custom licensing solution of your choice. Alternatively, if your extension does not work with a license manager, you might not have to worry about requesting and releasing a license. You can implement IExtensionConfig to enable and disable the tools on your extension's toolbar accordingly.

Loading just-in-time extensions

To improve application startup performance, just-in-time (JIT) extensions load by request only. An extension is considered loaded when the IExtension.Startup method is called by the application framework.

The same interfaces are used to implement a JIT extension, but the custom extension should be registered in one of the following component categories to enable delay loading:

ArcCatalog—Esri Gx JIT extensions
ArcMap—Esri Mx JIT extensions
ArcScene—Esri Sx JIT extensions
ArcGlobe—Esri GMx JIT extensions

For more information on when to load a JIT extension, see How to find an extension.

Complete the following steps to create a JIT extension:

Select the Just-In-Time Extension item template on the New Item dialog box under the ArcGIS Desktop category. Name the new class and click Add.
Choose any of the extension options based on the target desktop application.
Locate the TODO comments in the newly generated class and add code accordingly.

When creating a JIT extension, remember the following:

Be careful if your extension listens for document events, for example, IDocumentEvents. Document events get called on application startup, but your extension might not start until well after the application starts, and will never receive the initial document event calls. Before continuing, it may be necessary to call the same code that you call from the document events from inside your extension Startup method as well.
If your extension implements IExtensionConfig, do not assume in your IExtensionConfig code that the extension is fully initialized; the extension startup might not have been called. For example, if your JIT extension is not currently started in the ArcGIS application when a user opens the Extensions dialog box, the Startup method for your extension will not have been called; therefore, in the members of IExtensionConfig, your code cannot rely on any state you set during the IExtension.Startup method. As a general rule, you might want to avoid creating any classes in the extension class initialization and defer until IExtension.Startup is called.
Command items, toolbars, menus, or any other classes that need to find their extension should be careful when calling IApplication.FindExtensionbyCLSID. For example, a command should find its extension in the ICommand.OnCreate method (or the ICommand.OnClick method) instead of in its class initialization code. This is because the first time FindExtensionByCLSID is called, the extension is created and IExtension.Startup is called, which a JIT extension wants to avoid until necessary. Avoid using IApplication.FindExtensionByName, as this might not work for JIT extensions until the extension is created.

Persisting data in a document

You can save data in a document with a custom extension that also implements IPersistVariant. For more information, see How to persist data in a document.

Assigning command shortcut keys

Systemwide shortcut keys (or keyboard accelerators) for commands and tools can be assigned by a custom extension that implements IExtensionAccelerators. If you implement this interface, ensure that you do not change the behavior of existing accelerator keys.

There are a number of optional interfaces you can implement for an extension that are not covered by the extension item templates. In this case, use the ArcGIS Add Class wizard to create this type of extension class. See Using the ArcGIS Add Class Wizard to extend ArcObjects for details.