Adding a custom menu created in .NET to ArcGIS for Desktop

Click here to get the sample associated with this walkthrough.

In this topic

• Create a class library
• Add references
• Delete the class1 file
• Create MyBaseMenu
• Understand and edit MyBaseMenu
• Add a custom command as a menu item
• Compile the project
• Add and use MyBaseMenu in ArcMap
• Debug the menu
• Deploy the command

Create a class library

1. Open Visual Studio.
2. Click File, click New, and click Project. The New Project dialog box opens.

Add references

1. As part of the ArcGIS Visual Studio Integration Framework features, the ArcGIS Project Wizard steps you through adding references to .NET assemblies. The ArcGIS Project Wizard appears after you click OK on the New Project dialog box. Although there are other formats for viewing the available ESRI references, this walkthrough uses the default Filter by: Product Features view. See the following screen shot:
   
   
   
2. Since you are creating an ArcGIS for Desktop application, only assemblies relevant to ArcGIS for Desktop display. Click to expand the Desktop ArcMap node and select the following assemblies:
   • ESRI.ArcGIS.ADF.Local
   • ESRI.ArcGIS.ArcMapUI
   • ESRI.ArcGIS.Carto
   • ESRI.ArcGIS.DataSourcesFile
   • ESRI.ArcGIS.Display
   • ESRI.ArcGIS.Framework
   • ESRI.ArcGIS.Geodatabase
   • ESRI.ArcGIS.Geometry
   • ESRI.ArcGIS.System
   • ESRI.ArcGIS.SystemUI
   To select multiple items at once, press and hold the Ctrl key while you click each item, then click Add to include the references under the Selected Assemblies area. See the following screen shot:
   
   
   
3. Click Finish to create the project.
4. To reference System.Drawing, click the Project menu, click Add Reference, click the .NET tab, and click System.Drawing under the Component Name area. See the following screen shot:
   
   
5. Click OK. The assembly reference is added.
6. To view recently added references, reopen the Add Reference dialog box, and click the Recent tab.
7. Click OK to close the dialog box.

Delete the class1 file

Create MyBaseMenu

1. In Solution Explorer, right-click the project, click Add, and click New Item. The Add New Item dialog box opens.
2. Under the Categories area, click the Common Items node, and click ArcGIS.
3. Click Base Menu under the Templates area, name the class MyBaseMenu.cs (C#) or MyBaseMenu.vb (VB .NET), and click Add. See the following screen shot:
   
   
   
   The ArcGIS New Item Wizard Options dialog box opens.
   
4. Click Desktop ArcMap, and click OK. See the following screen shot:
   
   

• The MyBaseMenu class inherits from the BaseMenu abstract base class. Abstract classes are classes that cannot be instantiated and are sometimes partially implemented or not implemented at all. BaseMenu provides a basic implementation for IMenuDef.
• Since you want your menu to appear as a root level item with the other ArcMap menu items on the graphical user interface (GUI), implement the ESRI.ArcGIS.Framework.IRootLevelMenu interface. This can be done by modifying the code as shown in the following code example: 

public sealed class MyBaseMenu: BaseMenu, ESRI.ArcGIS.Framework.IRootLevelMenu

<ComClass(MyBaseMenu.ClassId, MyBaseMenu.InterfaceId, MyBaseMenu.EventsId), _
          ProgId("CustomMenus.MyBaseMenu")> _
          Public NotInheritable Class MyBaseMenu
    Inherits BaseMenu
    Implements ESRI.ArcGIS.Framework.IRootLevelMenu

public MyBaseMenu()
{
    //
    // TODO: Define your menu by adding items.
    //
    AddItem("esriArcMapUI.ZoomInFixedCommand");
    BeginGroup(); //Separator.
    AddItem("{FBF8C3FB-0480-11D2-8D21-080009EE4E51}", 1); //Undo command.
    AddItem(new Guid("FBF8C3FB-0480-11D2-8D21-080009EE4E51"), 2); //Redo command.
}

Public Sub New()
    '
    'TODO: Define your menu by adding items.
    '
    AddItem("esriArcMapUI.ZoomInFixedCommand")
    BeginGroup() 'Separator.
    AddItem("{FBF8C3FB-0480-11D2-8D21-080009EE4E51}", 1) 'Undo command.
    AddItem(New Guid("FBF8C3FB-0480-11D2-8D21-080009EE4E51"), 2) 'Redo command.
End Sub

public override string Caption
{
    get
    {
        //TODO: Replace bar caption.
        return "My_Menu";
    }
}

Public Overrides ReadOnly Property Caption() As String
Get
'TODO: Replace bar caption.
Return "My_Menu"
End Get
End Property

Add a custom command as a menu item

1. In Solution Explorer, right-click the project, click Add, and click New Item. The Add New Item dialog box opens.
2. Under the Categories area, click the Common Items node, then click ArcGIS.
3. Under the Templates area, click Base Command, name the class AddShapefile.cs (C#) or AddShapefile.vb (VB .NET), then click Add. See the following screen shot:
   
   
   
   The ArcGIS New Item Wizard Options dialog box opens.
   
4. Click Desktop ArcMap Command, and click OK (this adds the template code for the AddShapefile class). See the following screen shot:
   
   
   
   5.  By default, a bitmap is added to your project. This bitmap will be the icon you click in ArcMap to use as your custom command. You can customize the bitmap with the image editor. To accomplish this, double-click AddShapefile.bmp on Solution Explorer and use Visual Studio's tools to design your bitmap file. See the following screen shot for the edits made to the bitmap:
   
   
   Modify the constructor of the AddShapefile class as shown in the following code example:

public AddShapefile()
{

    base.m_category="Developer Samples";
    base.m_caption="Add Shapefile";
    base.m_message="Adds a shapefile to the focus map";
    base.m_toolTip="Adds a shapefile";
    base.m_name="CustomMenus_AddShapefile";

    try
    {
        string bitmapResourceName=GetType().Name + ".bmp";
        base.m_bitmap=new Bitmap(GetType(), bitmapResourceName);
    }
    catch (Exception ex)
    {
        System.Diagnostics.Trace.WriteLine(ex.Message, "Invalid Bitmap");
    }
}

Public Sub New()
    
    MyBase.New()
    
    MyBase.m_category="Developer Samples"
    MyBase.m_caption="Add Shapefile"
    MyBase.m_message="Adds a shapefile to the focus map"
    MyBase.m_toolTip="Adds a shapefile"
    MyBase.m_name="CustomMenus_AddShapefile"
    
    Try
    Dim bitmapResourceName As String=Me.GetType().Name + ".bmp"
    MyBase.m_bitmap=New Bitmap(Me.GetType(), bitmapResourceName)
    Catch ex As Exception
    System.Diagnostics.Trace.WriteLine(ex.Message, "Invalid Bitmap")
    End Try
    
End Sub

7. Another feature of the ArcGIS Visual Studio Integration Framework is ArcGIS snippets. ArcGIS snippets are chunks of ArcObjects reusable code that can be inserted into your project. To access ArcGIS snippets, right-click the Visual Studio code editor window at the necessary insertion point (before the end of the class file), and Insert Snippet: Double-click `ArcObjects` from the popup window. Double-click 'Mapping'. Double click the 'Add Shapefile Using OpenFileDialog' snippet.

#region "Add Shapefile Using OpenFileDialog"
public void AddShapefileUsingOpenFileDialog(ESRI.ArcGIS.Carto.IActiveView activeView)
{
    //Parameter check.
    if (activeView == null)
    {
        return ;
    }

    // Use the OpenFileDialog class to choose the shapefile to load.
    System.Windows.Forms.OpenFileDialog openFileDialog=new
        System.Windows.Forms.OpenFileDialog();
    openFileDialog.InitialDirectory="c:\\";
    openFileDialog.Filter="Shapefiles (*.shp)|*.shp";
    openFileDialog.FilterIndex=2;
    openFileDialog.RestoreDirectory=true;
    openFileDialog.Multiselect=false;

    if (openFileDialog.ShowDialog()=System.Windows.Forms.DialogResult.OK)
    {
        // The user chose a particular shapefile.

        // The returned string will be the full path, file name, and file extension for the chosen 
        // shapefile. Example: "C:\test\cities.shp".
        string shapefileLocation=openFileDialog.FileName;

        if (shapefileLocation != "")
        {
            // Ensure the user chooses a shapefile.

            // Create a new ShapefileWorkspaceFactory CoClass to create a new workspace.
            ESRI.ArcGIS.Geodatabase.IWorkspaceFactory workspaceFactory=new
                ESRI.ArcGIS.DataSourcesFile.ShapefileWorkspaceFactoryClass();

            // System.IO.Path.GetDirectoryName(shapefileLocation) returns the directory part of the 
            // string. Example: "C:\test\".
            ESRI.ArcGIS.Geodatabase.IFeatureWorkspace featureWorkspace=
                (ESRI.ArcGIS.Geodatabase.IFeatureWorkspace)
                workspaceFactory.OpenFromFile(System.IO.Path.GetDirectoryName
                (shapefileLocation), 0); // Explicit Cast

            // System.IO.Path.GetFileNameWithoutExtension(shapefileLocation) returns the base file 
            // name (without extension). Example: "cities".
            ESRI.ArcGIS.Geodatabase.IFeatureClass featureClass =
                featureWorkspace.OpenFeatureClass
                (System.IO.Path.GetFileNameWithoutExtension(shapefileLocation));

            ESRI.ArcGIS.Carto.IFeatureLayer featureLayer=new
                ESRI.ArcGIS.Carto.FeatureLayerClass();
            featureLayer.FeatureClass=featureClass;
            featureLayer.Name=featureClass.AliasName;
            featureLayer.Visible=true;
            activeView.FocusMap.AddLayer(featureLayer);

            // Zoom the display to the full extent of all layers in the map.
            activeView.Extent=activeView.FullExtent;
            activeView.PartialRefresh
                (ESRI.ArcGIS.Carto.esriViewDrawPhase.esriViewGeography, null, null);
        }
        else
        {
            // The user did not choose a shapefile.
            // Do whatever remedial actions as necessary.
            // System.Windows.Forms.MessageBox.Show("No shapefile chosen", "No Choice #1",
            // System.Windows.Forms.MessageBoxButtons.OK,
            // System.Windows.Forms.MessageBoxIcon.Exclamation);
        }
    }
    else
    {
        // The user did not choose a shapefile and clicked Cancel or closed the dialog box by 
        // clicking the X button.
        // Do whatever remedial actions as necessary.
        // System.Windows.Forms.MessageBox.Show("No shapefile chosen", "No Choice #2",
        // System.Windows.Forms.MessageBoxButtons.OK,
        // System.Windows.Forms.MessageBoxIcon.Exclamation);
    }
}

#endregion

#Region "Add Shapefile Using OpenFileDialog"

Public Sub AddShapefileUsingOpenFileDialog(ByVal activeView As ESRI.ArcGIS.Carto.IActiveView)
    
    'Parameter check.
    If activeView Is Nothing Then
        Return
    End If
    
    ' Use the OpenFileDialog class to choose the shapefile to load.
    Dim openFileDialog As System.Windows.Forms.OpenFileDialog=New System.Windows.Forms.OpenFileDialog
    openFileDialog.InitialDirectory="c:\"
    openFileDialog.Filter="Shapefiles (*.shp)|*.shp"
    openFileDialog.FilterIndex=2
    openFileDialog.RestoreDirectory=True
    openFileDialog.Multiselect=False
    
    If openFileDialog.ShowDialog=System.Windows.Forms.DialogResult.OK Then
        
        ' The user chose a particular shapefile.
        ' The returned string will be the full path, file name, and file extension for the chosen
        ' shapefile. Example: "C:\test\cities.shp".
        Dim shapefileLocation As String=openFileDialog.FileName
        
        If shapefileLocation <> "" Then
            
            ' Ensure the user chooses a shapefile.
            
            ' Create a new ShapefileWorkspaceFactory CoClass to create a new workspace.
            Dim workspaceFactory As ESRI.ArcGIS.Geodatabase.IWorkspaceFactory=New ESRI.ArcGIS.DataSourcesFile.ShapefileWorkspaceFactoryClass
            
            ' System.IO.Path.GetDirectoryName(shapefileLocation) returns the directory part of the
            ' string. Example: "C:\test\".
            Dim featureWorkspace As ESRI.ArcGIS.Geodatabase.IFeatureWorkspace=CType(workspaceFactory.OpenFromFile(System.IO.Path.GetDirectoryName(shapefileLocation), 0), ESRI.ArcGIS.Geodatabase.IFeatureWorkspace) ' Explicit Cast
            
            ' System.IO.Path.GetFileNameWithoutExtension(shapefileLocation) returns the base
            ' filename (without extension). Example: "cities".
            Dim featureClass As ESRI.ArcGIS.Geodatabase.IFeatureClass=featureWorkspace.OpenFeatureClass(System.IO.Path.GetFileNameWithoutExtension(shapefileLocation))
            Dim featureLayer As ESRI.ArcGIS.Carto.IFeatureLayer=New ESRI.ArcGIS.Carto.FeatureLayerClass
            featureLayer.FeatureClass=featureClass
            featureLayer.Name=featureClass.AliasName
            featureLayer.Visible=True
            activeView.FocusMap.AddLayer(featureLayer)
            
            ' Zoom the display to the full extent of all layers in the map.
            activeView.Extent=activeView.FullExtent
            activeView.PartialRefresh(ESRI.ArcGIS.Carto.esriViewDrawPhase.esriViewGeography, Nothing, Nothing)
            
        Else
            
            ' The user did not choose a shapefile.
            ' Do whatever remedial actions as necessary.
            ' System.Windows.Forms.MessageBox.Show("No shapefile chosen", "No Choice #1",
            ' System.Windows.Forms.MessageBoxButtons.OK,
            'System.Windows.Forms.MessageBoxIcon.Exclamation)
            
        End If
        
    Else
        
        ' The user did not choose a shapefile and clicked Cancel or closed the dialog box by
        ' clicking the X button.
        ' Do whatever remedial actions as necessary.
        ' System.Windows.Forms.MessageBox.Show("No shapefile chosen", "No Choice #2",
        ' System.Windows.Forms.MessageBoxButtons.OK,
        ' System.Windows.Forms.MessageBoxIcon.Exclamation)
        
    End If
    
End Sub

#End Region

public override void OnClick()
{
    IMxDocument mxDocument=m_application.Document as IMxDocument;
    AddShapefileUsingOpenFileDialog(mxDocument.ActiveView);
}

Public Overrides Sub OnClick()
Dim mxDocument As IMxDocument
mxDocument=m_application.Document As IMxDocument
AddShapefileUsingOpenFileDialog(mxDocument.ActiveView)
End Sub

public MyBaseMenu()
{
    //
    // Define the menu by adding items.
    //
    AddItem("esriArcMapUI.ZoomInFixedCommand");
    BeginGroup(); //Separator.
    AddItem("{FBF8C3FB-0480-11D2-8D21-080009EE4E51}", 1); //Undo command.
    AddItem(new Guid("FBF8C3FB-0480-11D2-8D21-080009EE4E51"), 2); //Redo command.

    BeginGroup(); //Add a separator.
    AddItem("CustomMenus.AddShapefile");
}

Public Sub New()
    '
    ' Define the menu by adding items.
    '
    AddItem("esriArcMapUI.ZoomInFixedCommand")
    BeginGroup() 'Separator.
    AddItem("{FBF8C3FB-0480-11D2-8D21-080009EE4E51}", 1) 'Undo command.
    AddItem(New Guid("FBF8C3FB-0480-11D2-8D21-080009EE4E51"), 2) 'Redo command
    
    BeginGroup() ' Add a separator.
    AddItem("CustomMenus.AddShapefile", 3)
End Sub

Compile the project

1. Save the project.
2. Click the Build menu and click Build Solution.
3. View the output window at the bottom of the Visual Studio .NET IDE. If the project builds correctly, a report shows that the build succeeded.

Add and use MyBaseMenu in ArcMap

1. Start ArcMap.
2. Click the Customize menu, and click Customize Mode. The Customize dialog box opens.
3. Click the Commands tab and in the Categories area, scroll down and click [Menus]. See the following screen shot:
   
   

4. In the Commands area, click My_Menu, drag it onto the ArcMap GUI in the menu bar area, then click Close. You can now access the functionality on your custom menu. See the following screen shot:
   
   

Debug the menu

1. Return to the solution in the Visual Studio IDE.
2. Verify that ArcMap.exe is set as the external program to use for debugging. This is another feature set for you by the ArcGIS project template when you create your project.
   1. Right-click the CustomMenu project in the Solution Explorer window and click Properties. 
   2. Click the Debug tab on the property page.
   3. Under the Start Action area, select Start external program to use ArcMap.exe in the Bin folder of your ArcGIS install directory. See the following screen shot:
      
      

3. In the code window for the MyBaseMenu file, find the class constructor—MyBaseMenu() in C#, New() in VB .NET—and set a breakpoint. To set a breakpoint in the Visual Studio IDE, click the margin indicator bar (the gray area on the left side of the code editor) next to the code where you want the breakpoint set. See the following screen shot:
   
   
   
4. Click the Debug menu and click Start Debugging (or press F5); Visual Studio runs ArcMap. Follow the steps in the Add and use MyBaseMenu in ArcMap section to review the code. When the MyBaseMenu class is instantiated, the debugger returns to Visual Studio and allows you to step through the code one line at a time with the buttons on the debugging toolbar.

Deploy the command

See Also: