Building your first ArcGIS Mobile application for Windows Mobile Smartphone

This walkthrough is for developers who wish to learn about creating and deploying a simple ArcGIS Mobile application for the Windows Mobile Smartphone platform. 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

This 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. This walkthrough is written in C# and will be deployed to the Windows Mobile 5.0 Smartphone emulator installed with Windows Mobile SDK.

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 Mobile 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 and the Map. The MobileServiceConnection component represents the MobileService published on an ArcGIS Server, while the MobileCache represents a local copy of that data compressed and stored in a folder set with the StoragePath property. 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 for the Windows Mobile Smartphone platform that allows you to open a mobile map cache and display the map 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 Smart Device and select Smart Device Project from the Templates pane.
    4. Select .NET Framework 2.0, from the dropdown list at the top of the dialog.
    5. Enter a project name.

      New Project Dialog creating a C# based Smart Device Project

    6. Click OK. This will bring up the Add New Smart Device Project dialog.
    7. For the Target Platform select Windows Mobile 5.0 SmartPhone SDK.
    8. For the .NET Compact Framework version select .NET Compact Framework Version 2.0.
    9. In the Templates pane click Device Application.
    10. Click OK. This will create a new project for you.

      Add New Smart Device Project Dialog

    Since the application was created as Windows Mobile Smartphone Application, Visual Studio will create the proper solution files and structure, and display a form for a Smartphone device.

  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 simply drag and drop them from the Toolbox to your windows form.

    Visual Studio IDE with the Map control added to the form

    1. Double-Click, or Drag-and-Drop the Map component from the toolbox onto the form.
    2. In the Properties Window change the Dock property to Fill so that the mapcontrol will utilize the full display area of the device as indicated by the screen shot above.

    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 set the the location of the MobileCache.

    Add code to specify where the mobilecache is located on disk, and then open it, which also draws the map to the display.

    1. Doing this as part of the Form's Load event process is a common practice, in the Properties window of the Form select the Event tab and Double-Click on the Load event property.
    2. Add the using statements below to the existing list of using statements to include the ArcGIS Mobile assembly.

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

    3. Add the following code to the class for the Form1_Load() method.

      private void Form1_Load(object sender, EventArgs e)
{ 
  // Specify the storage location on disk  
  mobileCache1.StoragePath = Environment.GetFolderPath(Environment.SpecialFolder.Personal) + @"\MapCache";
  if (!mobileCache1.IsValid) 
  {
    MessageBox.Show("Map Cache is not valid!"); 
    return;
  }
  try 
  {
    mobileCache1.Open(); 
  }
  catch
  { 
    MessageBox.Show("Cannot open map cache");
  }
}

  4. Adding Map navigation

    You can easily add map navigation features such as pan and zoom to your application using the RockerPanZoom MapAction. This provides a set of navigation functions driven by the Smartphone rockerpanel, without requiring any custom code.

    The new application running on a Smartphone

    1. Right click the Map Control and choose MapActions... on the context menu to display the MapAction Collection Editor dialog.
    2. Within the MapActions window use the Add button to add the rockerPanZoomMapActions to the Members list.
    3. Click OK to dismiss the menu and add the MapAction.
    NoteNote:

    The rockerPanZoomMapAction only provides the basic map navigation options. The keypad can be used to provide access to the additional navigation actions, with a minimal amount of coding.

  5. Application exit code

    Unlike PocketPC or Windows applications, Smartphone application forms do not present an OK or X in the top right corner to close the form. You will need to add code to close your application. For this walkthrough, you will close the application by pressing soft key 1.

    1. Return to the designer view for your form.
    2. Click the menu area above Soft Key 1 in the designer view to create a new menu entry (MenuItem1).
    3. Type Exit for the text property.
    4. Double click the menu item to create a code stub.
    5. Enter the following code in menuItem1_Clickevent.

      private void menuItem1_Click(object sender, EventArgs e)
{
  this.Close();
}

    The new form with a Soft Key Exit button added

  6. Compile the application

    Go to Build > Build Solution.

  7. Configuring the Windows Mobile Smartphone Emulator

    You will use the Windows Mobile 5.0 Smartphone Emulator to test the application, but first you must start the emulator and virtually cradle it.

    1. From the Visual Studio menu, choose Tools > Device Emulator Manager.
    2. In the Device Emulator Manager dialog, locate the Windows Mobile 5.0 Smartphone Emulator, right click and select Connect. This will start the device emulator.
    3. Right click again on the Windows Mobile 5.0 Smartphone Emulator entry and select Cradle. This will cradle the emulator via ActiveSync or Windows Mobile Device Center. Select a Guest partnership if asked for the type of ActiveSync relationship.
      TipTip:

      If ActiveSync does not automatically connect to the device, you can try to manually connect in ActiveSync by selecting File > Connection Settings, then click the Connect button and follow the wizard.

      Device Emulator Manager Dialog

  8. Install ArcGISMobile runtime

    In order to run this sample application, you will need to copy or deploy the ArcGIS Mobile runtime to the device emulator. This runtime deployment is required for all Mobile emulators or devices and utilizes a CAB file deployment. The steps below will copy the runtime CAB file to the emulator and then open it to install the ArcGIS Mobile runtime. This may not be required for your situation, as the runtime will deploy automatically to connected device after installing ArcGIS Mobile. If not installed follow these steps.

    1. From the MicroSoft ActiveSync menu click Explore to open the Windows Explorer.
    2. Use the Explorer to navigate to the ArcGIS Mobile runtime file; <ArcGIS_Mobile_Install_Location>\Mobile10.0\Install\AGMRuntime.cab.
    3. Copy the AGMRuntime.cab file.
    4. Navigate to the emulator's Start Menu folder. <Device>\Windows\Start Menu.
    5. Create a New Folder and name it ArcGISMobile.
    6. Paste the AGMRuntime.cab into the new ArcGISMobile folder.
    7. From the Emulator select the Start Menu then ArcGISMobile.
    8. Install the runtime by selecting it.
  9. Deploy the ArcGIS Mobile data cache

    In order to run this sample application, you will also need to copy or deploy the ArcGIS Mobile data cache to the device emulator. From the Tools menu in ActiveSync, click Explore Device and navigate to \My Documents and paste the Mapcache folder included in the sample download.

  10. Run the application

    The Smartphone emulator does not have a file explorer to locate and run the executable when deployed, for this exercise, you can run the application via the debugger. From the Visual Studio menu choose Debug > Start Debugging. If asked, deploy the application to the emulator. The application should start after it copies the required files to the emulator. Close the application via Soft Key 1. Rather than using, the debugger to run the application you can copy the application's executable to the ArcGISMobile folder you previously created. Experiment with the application. Zoom and pan the map via the rocker keys.

    The new application running on a Smartphone


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