How to create an application extension


Development licensing Deployment licensing
ArcView ArcView
ArcEditor ArcEditor
ArcInfo ArcInfo

In this topic


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 takes place when the extension is started or shut 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 will be used to identify the extension. This will not be the name displayed in the Extensions dialog box; for more information, see Creating configurable extensions.
 
The Startup method is used to perform an action when the extension gets loaded. This method has a parameter called 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 gets unloaded.
 
Register the class in the appropriate extension component category based on the target application. When the target application starts up, this extension will be loaded automatically.
 
The following are the available extension component categories:
 
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 may want to share data between extensions. In such circumstances, the data should not be associated with one extension but instead with another helper class. Each extension can then check to see 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 is opened.
Not every extension needs to be loaded when the application starts up; see Just-in-time extensions.
The following steps create an extension (Steps 1–3) that also listens to document events (Steps 4–7).
  1. Select the Application Extension item template in the New Item dialog box under the ArcGIS Desktop category. Name the new class and click Add.
  2. Choose any of the Blank extension options based on the target desktop application.
  3. Locate the TODO comments in the newly generated class and add code accordingly.
  4. 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.
  5. The code snippet requires adding a project reference to ESRI.ArcGIS.ArcMapUI.dll.
  6. In the IExtension.Startup implementation, call the SetupDocumentEvent() method inserted by the snippet to wire the document event to the extension.
  7. Modify the code in the OnNewDocument and OnOpenDocument event handlers accordingly.
 

Creating configurable extensions

Extensions that are listed in the Extension Manager dialog box can be checked on and off. To create a configurable extension allowing users to toggle its enabled state, implement the optional IExtensionConfig interface.
 
The ProductName property specifies the name that is displayed for this extension in the Extensions dialog box. Use the Description property to set the text that is displayed for this extension in the About this extension box in 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 will be displayed as checked in the Extensions dialog box. The checked state of the extension is saved in the user settings in the registry (for example, HKEY_CURRENT_USER\Software\ESRI\ArcMap\Extensions).
 
The following steps show how to create a configurable extension:
  1. Select the Application Extension item template in the New Item dialog box under the ArcGIS Desktop category. Name the new class and click Add.
  2. Choose any of the Configurable extension options based on the target desktop application.
  3. Locate the TODO comments and add code accordingly; for example:
 
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 in the Extensions dialog box.
 
The following occurs when a user checks one of the ArcGIS extensions in the Extensions dialog box:
 
The following occurs when a user unchecks one of the ArcGIS extensions in the Extensions dialog box:
 
The IExtensionConfig interface is independent of ESRI's licensing implementation, so 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 may 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.
 

Just-in-time extensions

To improve application startup performance, just-in-time (JIT) extensions are designed to be loaded 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:
 
For more information on when to load a JIT extension, see How to find an extension.
 
The following steps show how to create a JIT extension:
  1. Select the Just-In-Time Extension item template in the New Item dialog box under the ArcGIS Desktop category. Name the new class and click Add.
  2. Choose any of the extension options based on the target desktop application.
  3. Locate the TODO comments in the newly generated class and add code accordingly.
 
When creating a JIT extension, keep the following in mind:

Persisting data in a document

You can save data in a document with a custom extension that also implements IPersistVariant. For more details, 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 do 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 such an extension class.


See Also:

How to find an extension
How to persist data in a document