Building add-ins for ArcGIS for Desktop



About add-ins

The ArcGIS for Desktop add-in model provides you with a declaratively-based framework for creating a collection of customizations conveniently packaged within a single compressed file. Add-ins are easily shared between users as they do not require installation programs or Component Object Model (COM) registration; add-ins are added to a system by simply copying them to a well-known folder and removed by deleting them from this folder. Add-ins can also be shared between users within an organization using a centralized network share.
Add-ins are authored using .NET, Java, or Python along with Extensible Markup Language (XML). The XML describes the customizations, while the .NET, Java, or Python classes provide the custom behavior. The ArcObjects software development kit (SDK) includes an Add-Ins Wizard that integrates with development environments—such as Eclipse, Microsoft Visual Studio, and the free Express Editions of Visual Studio—to simplify development.

When to use add-ins

ArcGIS add-ins make it easy to build and share desktop customizations; however, depending on the goals and specifics of the solution you’re building, one of the following options may be more suitable.

Python

At ArcGIS 10.1, Python has been added to the list of languages for authoring Desktop add-ins, providing you will an easy to use solution for extending desktop functionality. For more information about building desktop add-ins with Python, see the ArcGIS for Desktop Help guide book, Customizing ArcGIS for Desktop with Python add-ins.

Classic COM extensibility

The add-in framework does not support every extensibility point defined by ArcGIS; for example, you cannot write a custom renderer, a custom workspace, or a custom feature as an add-in. You will need to use the classic COM extensibility approach if your solution includes component types that are unsupported in the add-in framework. Additionally, since the sharing of add-ins does not involve a registration step, do not use add-in based solutions that rely on external dependencies—such as libraries, assemblies, and services—that require registration or administrative intervention.

Add-in types

ArcGIS for Desktop applications support a fixed set of add-in types, including the most popular types used in the classic COM-based extensibility model introduced in previous versions of ArcGIS. The following add-in types are supported in the current release:
  • Buttons and tools—Simple controls that can appear on toolbars or—in the case of buttons—on menus.
  • Combo boxes—Provides a drop-down list of items and can optionally provide an editable input area.
  • Menus and context menus—Shows a drop-down list of buttons, submenus, and multi-items. Menu items can come from built-in sources, add-in sources, or a combination of both. Menus are typically hosted on toolbars, but they can also appear independently as context (pop-up) menus and root menus.
  • Multi-items—Dynamic collection of menu items created at run time. Multi-items are useful when the items on a menu cannot be determined before run time or the items need to be modified based on the state of the system.
  • Toolbars—Can host buttons, tools, menus, tool palettes, and combo boxes. As with menus, controls that appear on toolbars can come from built-in sources, add-in sources, or a combination of both. Toolbars can be configured to automatically appear when initially added to an application to make their presence more obvious to users.
  • Tool palettes—Provide a compact way to group a related set of tools. The most recently used tool appears on the toolbar alongside a small drop-down button used to access other tools in the group. As with menus, tools that appear on tool palettes can come from built-in sources, add-in sources, or a combination of both.
  • Dockable windows—Floating or docked windows that appear within ArcGIS for Desktop applications. You can populate dockable windows with any sort of content: charts, slide shows, video, mini-maps, or custom dialog boxes containing other controls—including Esri controls. Add-in developers have considerable control over where the dockable window initially appears and whether it will be grouped with other dockable windows.
  • Application extensions—Used to coordinate activities between other components—such as buttons, tools and dockable windows—within a containing add-in. Application extensions are usually responsible for storing state associated with the add-in as a whole and are often used to listen for and respond to various events exposed by the host application. Application extensions can be configured to load when needed or automatically when their associated application is started; extensions can also be configured to appear in the standard ArcGIS extension dialog box.
  • Editor extensions—Allow you to customize your editing workflows by plugging directly into the editing framework. As opposed to application extensions, editor extension add-ins are loaded when the edit session starts (Editor, Start Editing). You can customize the behavior of your editing session (for example, listening for edit events) by creating editor extensions.

Managing add-ins

Add-ins can be obtained from a variety of sources including Web-based repositories, via e-mail, or by browsing the file system or network. You can install an add-in by simply double-clicking an add-in file in Windows Explorer. When double-clicked, the Esri supplied Add-In Installation Utility validates the add-in and copies it to the appropriate well-known folder. Users are given an opportunity to review the author, description, version, and digital signature information of the add-in before proceeding. This validation step ensures that: the file is copied to the appropriate location; name conflicts are handled; and guarantees that any existing version of the add-in file isn’t overwritten by an older version. This utility also works directly on e-mail attachments and Web page links. See the following screen shot:
Add-ins can also be installed using the Add from file button on the Customize dialog box available in all the ArcGIS for Desktop applications. See the following screen shot:
You can access the Customize dialog box via the Customize menu. Add-ins installed using either the double-click or Add from file options are classified as local add-ins. Local add-ins reside within a special well-known/per-user folder on the local machine.
Though add-in files can be manually copied to a well-known folder without using the Esri Add-In Utility, care must be taken to avoid file name collisions, version overwrites, and so forth. This approach is typically used when sharing add-ins on a network.
As with classic COM components, individual add-in types are accessible via the Customize dialog box. For example, a button defined in an add-in behaves no differently than a COM command, both are listed under their specified category on the Commands tab. From this location, either can be dragged onto any toolbar or menu.
ArcGIS for Desktop applications provide an Add-In Manager dialog box available from the Customize menu. The Add-Ins tab on this dialog box provides detailed information on every installed add-in currently available to the running application. Add-ins targeting ArcGlobe, for instance, will not appear inside ArcMap. See the following screen shot:
The Add-In Manager Options tab lets users add custom well-known add-in folders. The add-in framework will additionally search for add-ins within these custom folders each time the application is started. This option is particularly useful in scenarios where a central network location is used to share add-ins throughout an organization. Add-ins can be added, deleted, and updated in these locations without intervention on any of the client machines; updates will be automatically reflected on the clients when the relevant applications are next re-started. The Options tab can also be used to disable all add-in functionality. See the following screen shot:
From the Add-In Manager, users can also elect to uninstall a particular add-in. Uninstalling an add-in moves the selected add-in file to the system Recycle Bin where it can later be restored if necessary.
The Uninstall button is only enabled for local add-ins. To uninstall an add-in originating from a custom add-in folder, simply delete the add-in from the share or remove the custom add-in folder using the Remove Folder button.

Add-in file anatomy

An add-in is composed of numerous parts including metadata in the form of an XML file that describes the add-in itself as well as its customizations, images and other sorts of simple data the customizations use, and compiled code. To keep these related files bundled together, add-ins are packaged as self-contained zipped archives with the esriAddIn file extension (for example, Acme.esriAddIn).
Add-ins use both declarative and imperative programming techniques. The XML file mentioned above is the declarative portion, and it describes all the static aspects of the add-in, including captions, tooltips, help, images, and initial layout details. The imperative, or active, portion is the classic instruction-based programming model, which can be any .NET language or Java. This portioning into declarative and programmatic aspects increases flexibility, reduces and simplifies the coding burden on developers, and in general makes development and maintenance easier. For example, you can change the caption and image of a button without recompiling your code; some customizations, such as toolbars, tool palettes, and menus, are completely declarative—they have no active portion.
The following XML code example shows an add-in declaring a toolbar with a button on it:
[XML]
<ESRI.Configuration
  xmlns="http://schemas.esri.com/Desktop/AddIns"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Name>
    Acme Custom Mapping Extension
  </Name>
  <AddInID>{6fa0df73-57ab-491e-a73d-e58ce07af414}</AddInID>
  <Description>Custom mapping toolbar.</Description>
  <Version>1.0</Version>
  <Image>Images\Acme.png</Image>
  <Author>John Locke</Author>
  <Company>Acme</Company>
  <Date>5/28/2009</Date>
  <Targets>
    <Target name="Desktop" version="10.0"/>
  </Targets>
  <AddIn language="CLR" library="Acme.dll" namespace="Acme">
    <ArcMap>
      <Commands>
        <Button
          id="Acme_ToggleDockWinBtn"
          class="ToggleDockWinBtn"
          caption="OpenDockWin"
          category="Acme Tools"
          image="Images\ToggleDockWinBtn.png"
          tip="Toggle dockable window."
          message="Open dockable window.">
          <Help heading="Toggle">Turns the ACME dockable window on and off.</Help>
        </Button>
      </Commands>
      <Toolbars>
        <Toolbar id="Acme_Toolbar" caption="Acme Toolbar">
          <Items>
            <Button refID="Acme_ToggleDockWinBtn"/>
          </Items>
        </Toolbar>
      </Toolbars>
    </ArcMap>
  </AddIn>
</ESRI.Configuration>
The following code example shows the active portion of a button. All ArcObjects, as well as the richness of your programming environment, are directly available for developers to consume.
[C#]
public class ToggleDockWndBtn: Button
{
    public ToggleDockWndBtn(){}

    protected override void OnClick()
    {
        //Get dockable window.
        UID dockWinID = new UIDClass();
        dockWinID.Value = @"ESRI_SelectionSample_SelCountDockWin";
        s_dockWindow = ArcMap.DockableWindowManager.GetDockableWindow(dockWinID);
    }
}
[VB.NET]
Public Class ToggleDockWinBtn
    Inherits ESRI.ArcGIS.Desktop.AddIns.Button
    
    Public Sub New()
        
    End Sub
    
    Protected Overrides Sub OnClick()
    
    'Get dockable window.
    Dim dockWinID As UID = New UIDClass()
    dockWinID.Value = "ESRI_SelectionSample_SelCountDockWin"
    s_dockWindow = ArcMap.DockableWindowManager.GetDockableWindow(dockWinID)
End Sub

Building add-ins

Add-ins are built using an integrated development environment (IDE), such as Visual Studio Express for .NET and Eclipse for Java, and simple wizards and templates are provided with the ArcObjects SDKs to automatically generate fully stubbed out add-in projects including the XML and class files. In addition, when these projects are built, they automatically generate an add-in file and copy it to a well-known folder. For the most part, the XML is authored by the wizards; however, if you do need to edit the XML by hand, the associated schema file makes edits easy as it provides IntelliSense and on-the-fly validation. To learn more about developing add-ins and using these wizards and templates, see Building custom UI elements using add-ins.


See Also:

How to migrate from COM components to add-ins