| 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:
- ESRI Gx extensions (ArcCatalog)
- ESRI Mx extensions (ArcMap)
- ESRI Sx extensions (ArcScene)
- ESRI GMx extensions (ArcGlobe)
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.
The following steps create an extension (Steps 1–3) that also listens to document events (Steps 4–7).
- Select the Application Extension item template in the New Item dialog box under the ArcGIS Desktop category. 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 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:
- Select the Application Extension item template in 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:
- Change the StateCheck() helper method to update the extension enabling logic called by the IExtensionConfig.State property.
-
IExtensionConfig.ProductName returns a localizable caption listed in the Extension Manager dialog box.
- The string returned by the IExtensionConfig.Description property is displayed at the bottom of the Extension Manager dialog box when it is selected in the top list. Use the escaped characters "\r\n" to insert a new line in the string.
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 checked 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 is displayed to the right of the extension name in 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 unchecks one of the ArcGIS extensions in the Extensions dialog box:
- The extension verifies that it is not being used in that application.
- If the extension is being used, the extension does not allow itself to be unchecked and a warning message is given.
- If the extension is not being 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 lets the license manager know 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 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.
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:
- ESRI Gx JIT extensions (ArcCatalog)
- ESRI Mx JIT extensions (ArcMap)
- ESRI Sx JIT extensions (ArcScene)
- ESRI GMx JIT extensions (ArcGlobe)
The following steps show how to create a JIT extension:
- 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.
- 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, keep the following in mind:
- You need to be careful if your extension listens for document events; for example, IDocumentEvents. The document events get called on application startup, but your extension may not start up 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 may not have been called yet. 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 yet, so in the members of IExtensionConfig, your code cannot rely on any state you set during the IExtension.Startup method. As a general rule, you may 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 will be created and IExtension.Startup will be called, which a JIT extension wants to avoid until necessary. Avoid using IApplication.FindExtensionByName as this may not work for JIT extensions until the extension is created.
Persisting 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 extensionHow to persist data in a document
