Building your first ArcGIS Mobile application for Windows

This walkthrough is for developers who wish to learn about creating and deploying a simple ArcGIS Mobile application for the Windows desktop environment. It uses step-by-step instructions to demonstrate how to create an application using the ArcGIS Mobile Map Control, the ArcGIS Mobile assembly and parts of ADO.NET.

Project description

The application will display map data using a Map Control, provide basic navigation tools such as zoom and pan, and include an identify function to show feature attributes. Once you complete this walkthrough, you can extend the application with additional functionality, or use what you learned to build your own application. While this walkthrough is written in C#, the same functionality can be used with VB.NET.

Concepts

Even though this walkthrough does not require previous experience with ArcGIS Mobile, there are some important concepts you should understand before starting. As a prerequisite, please read the Mobile SDK conceptual documentation, found in this help, to gain an understanding of the mobile framework and architecture. Using the ArcGIS Mobile class diagrams while proceeding through this walkthrough will help you learn about the classes and their relationships. You can find the class diagrams in the Mobile Assembly book of the ArcGIS Mobile Developer Help. In addition, you should have a good understanding of Visual Studio .NET 2008 and how to create a Windows application.

Where to get the sample

The sample is available for download from here.

ArcGIS Mobile SDK components

The ArcGIS Mobile SDK provides several Visual Studio components to help you develop mobile applications. The primary components that you will work with are the MobileServiceConnection, MobileCache, SyncAgent and the Map. The MobileServiceConnection component represents the MobileService published on an ArcGIS Server, the MobileCache represents a local copy of that data compressed and stored in a folder set with the StoragePath property, and the SyncAgents represents the flow of data between them. While this sample can run without a connection to a server, it is important to understand the role each of these components play in the ArcGIS Mobile system. Notice how the components are linked together and operate as a group to reflect the unique tasks each of them perform. The local data used in this walkthrough was previously extracted from a web service that was published with mobile capabilities. You do not need to create a mobile web service to complete this walkthrough or have a mobile device. The Map component will display the contents of the included MobileCache without connecting to a server. Additional components are used to navigate the map and identify attribute information for given features. For more information on the components used in this walkthrough, please refer to the ArcGIS Mobile Developer Help.

Requirements

In order to complete this walkthrough you will need the following installed on your machine:

Go to the Developer Requirements topic for more details and links to downloads and instructions.

Implementation

In this walkthrough, you will create a simple application that allows you to connect to a mobileservice, open a mobilecache and display the layers in a map control. Then you will add additional controls that will let you navigate the map and identify features within the layers.

Steps:
  1. Creating a new project using Visual Studio 2008
    1. Start Visual Studio .NET 2008.
    2. On the main menu, go to File > New > Project.
    3. In the New Project dialog box, under Project Types, expand Visual C#, click Windows and select Windows Forms Application from the Templates pane.
    4. Select .NET Framework 3.5, from the dropdown list at the top of the dialog.
    5. Enter a project name.
    6. Click OK. This will create a new project for you.

    New Project Dialog creating a C# based Windows Forms Application

  2. Adding a Map Control

    The ArcGIS Mobile controls are added to the Visual Studio toolbox when you install the ArcGIS Mobile SDK. They are located within the ArcGIS Mobile Controls tab within the toolbox. To use the controls within your application you can drag and drop them from the Toolbox to your windows form.

    Within the following section, you will add a Map component to the application and configure it.

    1. Double-Click, or Drag-and-Drop the Map component from the toolbox onto the form.
    2. Resize the Map to fill the desired area as indicated by the screen shot below.

    Visual Studio IDE with the Map control added to the form

    When the Map component is added to the form, a MobileCache component will be added to your project automatically. Your form should now contain a Map, called Map1, and a MobileCache component called mobileCache1.

  3. Configure the components

    You can configure the components via their properties in the IDE or though code. The steps below can be used to set the properties, or you can use the code listed in the next section.

    1. Right click the Map Control and choose DataSources... on the context menu to display the DataSources Collection Editor dialog.
    2. Within the DataSources Collection Editor dialog, ensure that the mobileCache1 is in the members list and is selected. If it is not there, use the Add button to add it.
    3. Select the StoragePath property and type in C:\temp\MapCache. You will need to copy the MapCache data folder from the sample data folder to the temp folder on your computer, before starting the application.

      DataSource Collection Editor Dialog

    You now need to add code to initialize the Map Control with the data layers from the mapcache on disk. If you have a valid mobile service additional steps are required to create a new mapcache, and retrieve data from the server while the application is running.

    1. Create a form load event. (Double-click on the Form)
    2. Switch to code view and add the using statements below to include the ArcGIS Mobile assembly.

      using ESRI.ArcGIS.Mobile;using
ESRI.ArcGIS.Mobile.MobileServices;

    3. Add the following code to the form1_load event:

      { 
try 
  { 
  mobileCache1.StoragePath = @"C:\temp\MapCache";
  //Uncomment these lines if you are using your own service 
  //mobileCache1.DeleteCache(); 
  //mobileServiceConnection1.Url = @"http://YOURSERVERNAME/ArcGIS/services/YOURSERVICENAME/MobileServer";
  MobileCacheSyncAgent mobileSync = new MobileCacheSyncAgent(mobileCache1, mobileServiceConnection1);
  MobileCacheSyncResults mobileResults = new MobileCacheSyncResults(); 
  //get the schema to determine list of layers 
  //mobileServiceConnection1.CreateCache(mobileCache1);
  mobileCache1.Open(); 
  mobileSync.Synchronize(); 
  map1.DataSources.Add(mobileCache1);
  } 
catch 
  {
  MessageBox.Show("Cannot open map cache");
  }

    This code will use the MobileCache component to retrieve data for the current map extent and draw it to the display.

    Compile the application by going to Build > Build Solution.

    NoteNote:

    Before running the application, you need to copy the map data from the samples data directory to your computer's C:\Temp folder. Using Windows Explorer navigate to C:\Temp and paste the MapCache folder from your download folder.

    You may now run the application. At this stage, the form should display layers from the mapcache in the map control.

  4. Interacting with the Map

    Map actions are components designed to listen and react to events raised by the mouse, keyboard, and other input devices against the map surface. For instance the pan mouse action listens to the MouseDown, MouseMove, and MouseUp events to begin, execute, and complete the panning action.

    Now that we have the data drawing in the display, we will add navigation capabilities.

    A map can have multiple map actions associated with it. However, by design only one is active or current. For instance, a map can have zoom in, zoom out, pan, identify, and sketch actions available, but at any given time, only one action is executed. In this section, you will add MapActions to the collection held by the map control and add a context menu to control the MapAction being executed. Navigating a map is an essential part of any mapping application and there are many different ways to implement it, a context menu is being used in this walkthrough to keep the mapping application as compact as possible, while providing maximum usability.

    MapAction Collection Editor Dialog

    1. From Properties window of the Map control, find the MapActions item and click the button appearing in the cell next to (Collection). In the MapAction Collection Editor window, use the Add button to add the Following MapActions. The Add button becomes a dropdown list when a right mouse click is used to expand the button. Add PanMapAction, ZoomInMapAction and ZoomOutMapAction to the collection as shown in the graphic above.
    2. Allow the MapActions to use their default properties and press the OK button to add the collection to the Map control.
    3. Find the ContextMenuStrip control on the Menus & Toolbars tab of the Visual Studio toolbox doubleclick or drag & drop it to add it to the Form components.
    4. Select the Context Menu and add 3 items, Pan, Zoom In , and Zoom Out as shown below.

      Visual Studio IDE with a Context menu added to the form

    5. Double click on each of the context menu items to create a code block for the Click Event for each menu item.
    6. Add the following code to the Click Events

      private void panToolStripMenuItem_Click(object sender, EventArgs e)
{ 
  map1.CurrentMapAction = panMapAction1;
}
private void zoomInToolStripMenuItem_Click(object sender, EventArgs e)
{
  map1.CurrentMapAction = zoomInMapAction1;
} 
private void zoomOutToolStripMenuItem_Click(object sender, EventArgs e) 
{
 map1.CurrentMapAction = zoomOutMapAction1;
}

    7. From the Properties window of the Map control, find the ContextMenuStrip item and click the cell to get the dropdown list contain the newly created ContextMenuStrip1 and select it.
    8. Compile and run your application.

    Your application should now be in a state where it will compile and run. In this state, you should be able to change the mouse action by simply right clicking on the map and selecting the desired context menu item. The selected MapAction or navigation type should allow you to Pan and Zoom on the map display.

  5. Adding Identify Capability

    Similar to the functionality within other ArcGIS applications, you can identify features inside the MapControl by querying the location identified by the mouse. In this section, we will add some custom code to enable identify.

    1. Select the ContextMenuStrip control from the Design view of the Form and add another menu item with the text Identify.
    2. Double click on the Identify menu item to create a code block for the Click event.
    3. Add the following code to the Click event.

      private void identifyToolStripMenuItem_Click(object sender, EventArgs e) 
{
  map1.CurrentMapAction = null; 
}

    4. Add a mousedown event to the Map Control. With the Map Control active in the form, click Events in the Properties window. Find the MouseDown event in the list of events and double click it. This will create a code block for the event.
    5. Adding this using namespace statement at the start of your class will be required to compile your new code, when the following is added.

       using ESRI.ArcGIS.Mobile.Geometries;

    6. Add the following code to the MapControl_MouseDown event.

      private void map1_MouseDown(object sender, MapMouseEventArgs e)
{
if (e.Button == MouseButtons.Right)
  return;
if (map1.CurrentMapAction != null)
  return;
Cursor.Current = Cursors.WaitCursor; 
MapMouseEventArgs me = e as MapMouseEventArgs; 
Envelope qEnv = new Envelope(me.MapCoordinate, me.MapCoordinate);
double mapTolerance = map1.ToMap(3);
qEnv.Resize(mapTolerance, mapTolerance);
QueryFilter qFilter = new QueryFilter(qEnv, GeometricRelationshipType.Intersect);
string txtResult = "Identify Results: ";
int intFields;


foreach (MobileCacheLayer MCLayer in mobileCache1.Layers)
 {
 //Only Feature layers are used in identify 
 if (MCLayer is FeatureLayer)
   {
   txtResult += "\r\n Layer " + MCLayer.Name;
   FeatureLayer FLayer;
   //cast the MobileServiceLayer to a featureLayer
   FLayer = (FeatureLayer)MCLayer;
   using (FeatureDataReader featReader = FLayer.GetDataReader(qFilter)) 
     {
      intFields = featReader.FieldCount;
      while (featReader.Read())
       {
       for (int i = 0; i < intFields; i++)
         txtResult += "\r\n" + featReader.GetName(i) + ": " + featReader.GetValue(i).ToString();
       } 
     }
   }
 }
Cursor.Current = Cursors.Default;
MessageBox.Show(txtResult);
}

    7. Compile and run the application.

Copyright © 1995-2011 Esri. All rights reserved.
9/20/2011