This document is archived and information here might be outdated.  Recommended version.

How to pass the ArcGIS Desktop application from a command or tool (ArcObjects .NET 10.8 SDK)
ArcObjects Help for .NET developers > ArcObjects Help for .NET developers > Developing with ArcGIS > Learning ArcObjects > Extending ArcObjects > Application framework customizations > Creating commands and tools > How to pass the ArcGIS Desktop application from a command or tool

How to pass the ArcGIS Desktop application from a command or tool

The Application object is the starting point for many ArcGIS Desktop customizations, especially when extending the framework with a custom graphical user interface (GUI). Commands and tools get a reference to the Application object from the ICommand.OnCreate method. This topic shows how to connect the running application object in ICommand.OnCreate among custom .NET components.

In this topic

Extending ArcGIS Desktop with custom commands or tools

Commands and tools are the most commonly implemented framework components to extend the functionality of an ArcGIS Desktop application. You can target your command or tool to work with ArcCatalog, ArcMap, ArcScene, or ArcGlobe by registering your component into the necessary application.
To get started, use the ArcGIS item templates to create a command and tool, then select the ArcGIS Desktop application where you want to create the command or tool. For more information, see Creating commands and tools.
The Base Command and ArcGIS Base Tool templates override the OnCreate method that is called by the framework when your command or tool is created. The framework also passes the Application object that creates the command or tool as the input hook parameter in this method. Although the hook parameter is a generic type of System.Object, the expected hook is a reference to the Application object that implements the IApplication interface.
The IApplication reference is the top-level entry point into the various ArcGIS Desktop applications. In most cases, a command or tool only works in a specific application or applications but not all. The following table shows the interface you can test the IApplication reference against:
Desktop application
ArcCatalog command or tool
ArcGlobe command or tool
ArcMap command or tool
ArcScene command or tool

Creating an application-specific command  

To create an application-specific command, follow these steps:
  1. Create an ArcGIS Desktop class library project targeting the application of your choice, for example, ArcMap. For more information, see Choosing an ArcGIS Desktop project template.
  2. Create a command using the ArcGIS Base Command templates. Select the ArcGIS Desktop application option where you want to create the command, for example, Desktop ArcMap command. For more information, see the previously referenced topic, Creating commands and tools.
  3. Specify command properties in the constructor, for example, set the category to .NET Samples caption to My Command, and the name to NETSamples_MyCommand.
  4. Examine how the code in the OnCreate method handles the incoming hook parameter, for example, IMxApplication for ArcMap.
  5. Go to the OnClick method and add code to display the name of the application in which the command resides. See the following code example:
IMessageDialog msgDialog=new MessageDialogClass();
msgDialog.DoModal("Test", "My command works in " + m_app.Name, "", "", 0);
Dim msgDialog As IMessageDialog=New MessageDialogClass()
msgDialog.DoModal("Test", "My command works in " + m_app.Name, "", "", 0)
  1. Add a break point in the previous code example (optional).
  2. Debug the command in your Visual Studio project. Make sure the debug application property of your project points to ArcMap.exe.
  3. Once ArcMap starts in your debug session, open the Customize dialog box. Search for the custom command in the .NET Samples category, and drag and drop the command onto the application.
  4. Close the dialog box.
  5. Click the command. It hits the break point you added in the OnClick method announcing the name of the application.

Creating a generic command

You can repeat the steps in Creating an application-specific command by creating another command in a different desktop application. However, you can also create a single command that works in all applications by modifying the previous code example.
To create a generic command, follow these steps:
  1. Omit the check for a specific application in the OnCreate method by commenting out or deleting lines of code in the following code example:
//Disable if it is not ArcMap.
//if (hook is IMxApplication)
'Disable if it is not ArcMap.
'If TypeOf hook Is IMxApplication Then
'End If
  1. Add code to register your class into all desktop application command categories using the ArcGIS Component Category Registrar dialog box. Select the following categories on the dialog box:
    • ArcMap Commands
    • ArcCatalog Commands
    • ArcGlobe Commands
    • ArcScene Commands
  2. Run or debug your command in any of the desktop applications. When debugging, switch the debug application project property to the appropriate application path.
  3. Drag and drop the command from the Customize dialog box, and click the command to display a message with the application name.

Passing the hook object to dialog boxes or other .NET components

Sometimes a command is used to display a dialog box that also needs to access the application object. 
You can use the same technique to pass the application hook object to other .NET components in your project.
To pass the application object to a form via a write-only property, follow these steps:
  1. Create a desktop command using the ArcGIS Base Command template. Follow Steps 1 - 3 in Creating an application-specific command.
  2. Add a form to your project, for example, Form1.
  3. Add a button to your form.
  4. Add a write-only property to the form to accept the application object.

    See the following code example:
public partial class Form1: Form
    private IApplication m_application;
    ... public IApplication ArcGISApplication
Public Class Form1
    Private m_application As IApplication
    Public WriteOnly Property ArcGISApplication() As IApplication
    Set(ByVal Value As IApplication)
    End Set
End Property

End Class
  1. Add code to the OnClick event handler of the form button to display a message for the application.

    See the following code example:
private void button1_Click(object sender, EventArgs e)
Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click
End Sub
  1. Return to the command file and add the following code to the OnClick method to initialize and hand over the application object to the form:
public sealed class Command1: BaseCommand
    private Form1 m_form;
    ... public override void OnClick()
        //Initialize form.
        if (m_form == null || m_form.IsDisposed)
            m_form=new Form1();
        //Show form (modeless).
        if (!m_form.Visible)
Public NotInheritable Class Command1
Inherits BaseCommand
Public Overrides Sub OnClick()
'Initialize form.
If m_form Is Nothing OrElse m_form.IsDisposed Then
    m_form=New Form1()
End If
'Show form (modeless).
If Not m_form.Visible Then m_form.Show()
End Sub

End Class
  1. Compile and run the code by adding the command to the application, then click it to display the form. Click the form button to announce the application name.

See Also:

Creating commands and tools

To use the code in this topic, reference the following assemblies in your Visual Studio project. In the code files, you will need using (C#) or Imports (VB .NET) directives for the corresponding namespaces (given in parenthesis below if different from the assembly name):

Development licensing Deployment licensing
ArcGIS Desktop Basic ArcGIS Desktop Basic
ArcGIS Desktop Standard ArcGIS Desktop Standard
ArcGIS Desktop Advanced ArcGIS Desktop Advanced