Tutorial Navigation | Previous: Part 3: Setting Up Visual Studio | Next: Part 5: Adding the Utility’s Dialog Form

In this step, we will use the ArcMap Add-in template wizard in Visual Studio to create a project that implements a button on a toolbar.

Resources

Files

The files needed for this part of the tutuorial can be downloaded here: Tutorial Data (96 KB)
Contents (click to expand for more information):

• VBAtoCS_Tutorial_01_v10.mxd (+/-)
  Sample map document to use when testing and debugging the C# Add-in.

• sample_data.mdb (+/-)
  Personal geodatabase with one feature class, “Hwy_94_Overlaps”, containing 13 line features of various lengths that overlap on the same highway.

• StaggerOffsetFeatures_Addin_values.TXT (+/-)
  Simple text file with text that can be copied and pasted into wizard and code files in Visual Studio C#.

• StaggerOffsetFeatures.png (+/-)
  Bitmap to use for the Add-In’s UI button.

• VBA_OffsetFeatures.txt (+/-)
  VBA source code for the utility that can be copy and pasted into the C# code editor to use for reference.

• VBA_OffsetFeatures_Form.png (+/-)
  Image of the VBA utility’s dialog form, to use as a reference when re-creating the form in C#.

Video Demonstrations

The following videos are also linked from the relevant sections below. (opens in a new browser window or tab)

New C# Project dialog (duration 0:41)
ArcGIS Add-in Wizard, Welcome page (duration 0:26)
ArcGIS Add-in Wizard, Button page (duration 0:57)
Add a toolbar (duration 0:46)
Add simple test code (duration 0:47)
Test the Add-in in ArcMap (duration 0:46)

Create the New Add-in Project

Exit ArcMap if it is running.

Launch Visual Studio.

Start a New C# Project

Video Demonstration: New C# Project dialog (duration 0:41)

Initiate an Add-in Project with a Button

Select New Project… from the File menu. Expand the list on the left of the New Project dialog and select the Desktop Add-Ins item. Select the ArcMap Add-in template. Enter a Name for the project, such as “VBA_to_CS_Tutorial”. Set the folder Location where you want your source code stored. Enter a Solution Name, such as “VBA_to_CS_Tut_Sol”. Click the OK button.

After a moment, the ArcGIS Add-Ins Wizard displays.

ArcGIS Add-In Wizard Welcome Page

Video Demonstration: ArcGIS Add-in Wizard, Welcome page (duration 0:26)

The Welcome page of the wizard provides for editing the basic information about the Add-in that will be displayed by the Add-in Manager in ArcGIS. You may edit values to your choice. Click the Next button.

ArcGIS Add-In Wizard Button Page

Video Demonstration: ArcGIS Add-in Wizard, Button page (duration 0:57)

Check the box next Button on the left side of the dialog under Add-in Types.

Enter the following values:
Class Name : StaggerOffsetButton
Caption: Stagger Offset Features
Image: (click the browse button and import the provided StaggerOffsetFeatures.png file).
Category: accept default, “Add-in Controls”.
On Demand: Checked
Tooltip: Stagger Offset Features: Offsets all features in selected layer.
Description: Stagger Offset: Offsets all feature in selected layer by a user-specified stagger amount on either side of the original position. Start an edit session before use.

Click the Finish button. The project framework is built and will open in Visual Studio. Initially, only the Config.esriaddinx file will open and be displayed in the IDE.

The Config.esriaddinx file is an XML format file used by ArcGIS to identify and configure Add-ins. It is managed by the wizards and you should not need to mess with it.

Add a Toolbar to the Project

Video Demonstration: Add a toolbar (duration 0:46)

Open the Solution Explorer if it is not visible (View | Solution Explorer). Right-click on the project name (“VBA_to_CS_Tutorial”) and select Add | New Item… from the context menu.

Locate and select the Desktop Add-Ins item in the Categories list. Under Templates, select Add-in component. Since we are adding a toolbar, you can ignore the value in the Name box, it will not be used. Click the OK button.

The ArcGIS Add-ins Wizard displays again, but this time displays only Add-in components.

Click the Add-in Command Bars item on the left. Select the Toolbar item.

Enter the following values:
Caption: Tutorial_Toolbar
Premier Toolbar: checked (so that toolbar is displayed by default)
Items: click Add Item underneath Reference ID and select the StaggerOffsetsButton.

Click the Finish button.

Expand this to view contents of the Config.esriaddinx file that includes the button and toolbar (+/-)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

<ESRI.Configuration xmlns="http://schemas.esri.com/Desktop/AddIns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Name>VBA_to_CS_Tutorial</Name>
  <AddInID>{34b94edb-b71a-4fde-bcdf-c344da8774d1}</AddInID>
  <Description>VBA_to_CS_Tutorial</Description>
  <Version>1.0</Version>
  <Image>Images\VBA_to_CS_Tutorial.png</Image>
  <Author>jeffh</Author>
  <Company>Qtools</Company>
  <Date>12/7/2010</Date>
  <Targets>
    <Target name="Desktop" version="10.0" />
  </Targets>
  <AddIn language="CLR" library="VBA_to_CS_Tutorial.dll" namespace="VBA_to_CS_Tutorial">
    <ArcMap>
      <Commands>
        <Button id="Qtools_VBA_to_CS_Tutorial_StaggerOffsetButton" class="StaggerOffsetButton" message="Stagger Offset: Offsets all feature in selected layer by a user-specified stagger amount on either side of the original position. Start an edit session before use." caption="Stagger Offset Features" tip="Stagger Offset Features: Offsets all features in selected layer." category="Add-In Controls" image="Images\StaggerOffsetButton.png" />
      </Commands>
      <Toolbars>
        <Toolbar id="Qtools_VBA_to_CS_Tutorial_Tutorial_Toolbar" caption="Tutorial_Toolbar" showInitially="true">
          <Items>
            <Button refID="Qtools_VBA_to_CS_Tutorial_StaggerOffsetButton" />
          </Items>
        </Toolbar>
      </Toolbars>
    </ArcMap>
  </AddIn>
</ESRI.Configuration>

Add Code to Test the Add-In

Video Demonstration: Add simple test code (duration 0:47)

Before starting with the VBA conversion and coding, we will test that the project framework produces an Add-in that works with ArcMap.

In the Solution Explorer, open the StaggerOffsetButton.cs file (double-click it). It will display in the Code Editor.

Expand this to see all the pre-filled code created by the wizard in the button class file (+/-)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

using System;
using System.Collections.Generic;
using System.Text;
using System.IO;
 
namespace VBA_to_CS_Tutorial
{
    public class StaggerOffsetButton : ESRI.ArcGIS.Desktop.AddIns.Button
    {
        public StaggerOffsetButton()
        {
        }
 
        protected override void OnUpdate()
        {
            Enabled = ArcMap.Application != null;
        }
 
        protected override void OnClick()
        {
            //
            //  TODO: Sample code showing how to access button host
            //
            ArcMap.Application.CurrentTool = null;
        }
    }
}

Locate the method named OnClick(). The Add-in wizard pre-filled it with some sample code.

19
20
21
22
23
24
25

protected override void OnClick()
{
    //
    //  TODO: Sample code showing how to access button host
    //
    ArcMap.Application.CurrentTool = null;
}

This is the entry point for your code when the Add-in’s button is clicked.

Our test will display a simple message box in ArcMap. The MessageBox class needs a reference to System.Windows.Forms. As you work with various objects and interfaces, you will need to add references to the assemblies that contain them, to your project.

Right-click on References in the Solution Explorer, and select Add Reference… from the context menu.
On the .NET tab page, locate and select System.Windows.Forms, click OK.

Once a reference to an assembly has been added to your project, you can “use” it in any file where you need it.

In the code window, scroll to the top of the StaggerOffsetButton.cs file. Add another line under the last using statement:
using System.Windows.Forms;

1
2
3
4
5

using System;
using System.Collections.Generic;
using System.Text;
using System.IO;
using System.Windows.Forms;

Now the MessageBox class is available to us.

Insert the following code to display a simple dialog box in ArcMap:
MessageBox.Show("It WORKS!!!", "VBA to CS Tutorial");

19
20
21
22
23
24
25
26
27

protected override void OnClick()
{
    //
    //  TODO: Sample code showing how to access button host
    //
    ArcMap.Application.CurrentTool = null;
 
    MessageBox.Show("It WORKS!!!", "VBA to CS Tutorial");
}

Run the Add-In in ArcMap Using Visual Studio Debugger

Video Demonstration: Test the Add-in in ArcMap (duration 0:46)

To compile the new Add-in, add it to the Add-ins folder, and launch ArcMap, either:
Click the little green right-pointing triangle button.
-or- Press F5.
-or- Select Start Debugging from the Debug menu.

Be patient for ArcMap to load. Once it opens, you should open the provided VBAtoCS_Tutorial_01_v10.mxd map. After the map opens fully, you will notice a small floating toolbar with a single button. Drag it to an empty space on a tool panel.

Hover over the button to see the tooltip. Click the button to display the “It WORKS!!!” dialog.

Select Add-In Manager from the Customize menu. Select the VBA_to_CS_Tutorial item on the left to view details about the Add-In.

Close ArcMap to return to Visual Studio and stop debugging.

Now that the framework for the Add-In is working, it’s simply a matter of reproducing the dialog form and coding with ArcObjects.

Tutorial Navigation | Previous: Part 3: Setting Up Visual Studio | Next: Part 5: Adding the Utility’s Dialog Form