In this section:

1. About Extensions
2. Just-in-time Extensions
3. Developing Custom Extensions

---

About Extensions

An extension provides another mechanism for extending an application. An extension is a suitable choice of customization if you want to deliver a package of associated functionality. Using an extension, you can provide many different types of functionality, such as deliver controls and toolbars, perform event handling, store data commonly shared between controls, perform validation, and much more.

Extensions can act as a central point of reference for developers when they are creating commands and tools for use within the applications. Often these commands and tools must share data or access common UI components. An extension is the logical place to store this data and develop the UI components. The main reason for this is that there is only ever one instance of an extension per running application and, given an IApplication interface, it is always possible to locate the extension and work with it.

An extension provides a mechanism for a developer to add a unit of additional functionality to an ArcGIS application.

The Application object implements the IExtensionManager interface, which has properties to get a reference to a particular extension and to get a count of how many extensions are currently loaded. To access the application extension manager, QI for IExtensionManager on Application. Note that other types of objects can also implement IExtensionManager. For example, the Editor toolbar in ArcMap is an extension that manages editor extensions. Therefore, the Editor object also implements IExtensionManager. There is also an ExtensionManager object that implements IExtensionManager.

Extension classes registered to the following component categories will be started up when the appropriate ArcGIS application is started.

• ArcMap extensions are loaded from 'ESRI Mx Extensions'.
• ArcCatalog extensions are loaded from 'ESRI GX Extensions'.
• ArcScene extensions are loaded from 'ESRI SX Extensions'.
• ArcGlobe extensions are loaded from 'ESRI GMx Extensions'.

---

Just-in-time Extensions

Extensions are generally loaded when an ArcGIS application first starts up. For example, in ArcMap the extension manager instantiates each extension it can find in the ESRI Mx Extensions component category and calls its IExtension::Startup method.

You may want to develop your extension to be a just-in-time (JIT) extension. The concept behind JIT extensions is to avoid creating objects until necessary; therefore, ArcMap does not start up a JIT extension until it is actually required.

JIT extensions are like standard extensions; however, they are not started up at application startup, but only when they are required.

To create an ArcMap JIT extension, you would create your extension, like a standard extension, by implementing the extension interface(s) as required. Then you just have to register the extension with the ESRI Mx JIT Extensions component category, and the application framework takes care of the rest. The JIT extension manager in ArcMap is essentially similar to the extension manager, but maintains the list of both JIT extensions and also maintains information on whether each is currently started up or not—a JIT extension will be started up the first time that IApplication::FindExtensionByCLSID is called for that extension.

For example, if your extension delivers a number of command items on a toolbar, like the commands and tools example in this section, you can design your extension so that the visibility of the toolbar controls the point at which the extension is loaded (started up). In this case, when the toolbar is made visible in ArcMap (by selecting the toolbar in the View, Toolbars menu), the command items on the toolbar are instantiated. It is these command items which control the extension startup - this is because members such as IMultiItem::OnPopup and ICommand::OnCreate call the FindExtensionByCLSID method to get a reference to the extension that they belong to. When FindExtensionByCLSID is called, the JIT extension manager recognizes that the extension in question is not already started up, and will then call its Startup method. If the toolbar is closed, the extension will not be loaded the next time that application is started, until the toolbar is once again made visible.

If you are using the IExtensionManager interface to iterate extensions, it will not list any JIT extensions. Similarly, if you are using IJITExtensionManager, ordinary extensions will not be listed. Keep in mind that iterating all the JIT extensions by calling FindExtensionByCLSID will start up each JIT extension at that point, leaving them in this state until ArcMap exits.

Here are a few things that you need to keep in mind when creating a JIT extension:

• Register to ESRI Mx JIT Extensions for an ArcMap JIT extension, (or ESRI GX JIT Extensions for ArcCatalog, ESRI GMx JIT Extensions for ArcGlobe, or ESRI SX JIT Extensions for ArcScene). Remove the registration to the existing extension component category.
• You need to be careful if your extension listens for document events (IDocumentEvents, IDocumentEventsDisp, and so forth). The document events get called on application startup, but your extension may not get started up until well after the application starts and will never receive the initial document event calls. It may be necessary to call the same code that you call from the document events from inside your extension Startup method as well, before continuing.
• 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 coclasses in the extension class initialization and defer until IExtension::Startup is called.
• Command items, toolbars or menus, or in fact 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, 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 IAppliciation::FindExtensionByName, as this may not work for JIT extensions until the extension is created.

• If your command delivers commands, make sure that you do not do any initialization beyond bitmap, caption, name, and message within the command constructor. You should use the ICommand::OnCreate method to do all other necessary initialization at the later stage.

---

Developing Custom Extensions

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 notes explain how the ArcGIS extensions work when they are turned on or off in the Extensions dialog box.

When a user checks one of the ArcGIS extensions in the Extensions dialog box, the following things occur:

• 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).

When a user unchecks one of the ArcGIS extensions in the Extensions dialog box, the following things occur:

• The extension verifies that it is not being used within 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 within the application, the uncheck completes successfully and the remaining steps below 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 within 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.

Application startup sequence

When working with extensions and document events, it is important to have an understanding of the application startup sequence. The basic startup sequence is:

1. User starts the application.
2. Application object created.
3. Document object created.
4. Extensions are loaded.
5. If a document file is specified on the command line, or if the application is started by double-clicking a document file, then that document is loaded. If not, a new document is created. If the user then chooses to open an existing document, that document is loaded.

The order of extension loading cannot be controlled. The extensions are loaded in 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.

Note that for JIT extensions, this sequence is not applicable—read the information above for information on JIT extension startup.

---

Back to top

See Also Extending the Framework, Commands and Tools Example.