How to create a MapControl application

Summary This topic shows how to create a map viewer application using the MapControlApplication template, which is available in the Visual Studio integrated development environment (IDE) integration tools. It then steps through a few basic changes you can make to the application. This topic is for those new to using ArcGIS Engine or the .NET application programming interface (API).

Adding data at run time
Adding data at design time

Customizing the ToolbarControl
Running the application with an ArcGIS Desktop license

Using the MapControlApplication template

The MapControlApplication template is a quick way to start developing in .NET using ArcGIS Engine resources. You can use the template as the starting point for your .NET map viewer or as a learning tool to improve your understanding of geographic information system (GIS) development using the ArcGIS libraries. This topic shows how to use the template to create a .NET map viewer.

Creating the basic application

Do the following steps to create the basic MapControl application:

Start Visual Studio, click the File menu, select New, and click Project. The New Project dialog box appears.
On the Projects type pane, click the Visual Basic or Visual C# node (depending on the language you are using), click the ArcGIS node, then click Extending ArcObjects.
Select MapControl Application on the Templates area.
Name the project, click the Browse button to find the location where you want to save the project, then click OK. See the following screen shot:

You now have a complete MapControl application that you can compile and run. There is a MapControl, TOCControl, and a ToolbarControl with some tools already on it. There is also a File menu with basic document options, as well as an exit option. See the following screen shot:

Reviewing the application

Now that you have created a basic application, you can review the project and its files to understand what was done.

Review the references (in the Solution Explorer for C# or on the References tab under My Project for VB .NET). All the necessary references for the application have been added.
Depending on the language you are using, MainForm.cs or MainForm.vb is the form that contains the MapControl, TOCControl, ToolbarControl, and LicenseControl.

When you view the form's code, you can see that it already has the necessary imports (VB .NET) or using (C#) statements. It also has text added on the status bar.
By looking at the LicenseControl properties, you can see that the application is set to check only for an ArcGIS Engine license.
On the property pages for the ToolbarControl and TOCControl, you can see that the MapControl (axMapControl1) has been buddied with each of those controls.
Notice the MainForm Dispose method. It ensures that any ESRI libraries that have been used are unloaded in the correct order. Failure to do this can result in random crashes upon exit due to the operating system (OS) unloading the libraries in the incorrect order.

CreateNewDocument.cs or CreateNewDocument.vb (depending on the language you are using) is the code behind the command allowing you to create a document.

Adding data to the application

You can add data to the application at run time or design time. If you want your map viewer to open with a dataset, add the data at design time.

Adding data at run time

Do the following steps to add data at run time:

Click the Open button on the ToolbarControl.
On the dialog box, browse to and select the document (.mxd, .mxt, or .pmf) to open it. You can also click the Add Data button on the ToolbarControl. If you use the Add Data button, browse to a shapefile, geodatabase, raster, server, or schematic data file.

Adding data at design time

Do the following steps to add data at design time:

Right-click the MapControl in MainForm and choose Properties. The Properties dialog box appears.
Specify the path to open the document or click the Open button.

Customizing the ToolbarControl

Do the following steps to add a command to the ToolbarControl in Visual Studio:

Right-click the ToolbarControl in MainForm and choose Properties. The Properties dialog box appears.
Click the Items tab, click Add, then browse to the location of the command you want to add. You can also click Add From File on the Controls Commands dialog box if you want to add a custom command.
With the Properties dialog box still open and the Items tab selected, you can remove a command item by right-clicking the item and clicking Delete.
You can also customize the style of the ToolbarControl on the Items tab by setting the Item Appearance, Icon Size, and Text Alignment options.

Running the application with an ArcGIS Desktop license

Since the application is set by default, it requires an ArcGIS Engine Runtime license. However, if you want it to run on a machine with ArcGIS Desktop (ArcView, ArcEditor, or ArcInfo), or to check for and consume a floating ArcGIS Desktop license, update the LicenseControl to verify the other licenses as well.

Do the following steps to run the application with a license:

Right-click the LicenseControl and choose Properties. The Properties dialog box appears.
Select the check boxes of the licenses you want to use when the application runs.

The application always uses the lowest level of licensing that is available. For example, if a machine has an ArcGIS Engine and ArcEditor license, the application uses the ArcGIS Engine license. If there are ArcView and ArcInfo floating licenses available and both of those options were selected in the LicenseControl, the application uses the ArcView license.