ArcGIS Mobile SDK - Walk-through: Creating a project extension

Complexity: Beginner Data Requirement: Installed with software

Introduction

Note: This walk-through can be considered as a manual way for creating a new task using application framework. At the end of the document it provides necessary information regarding a descriptive xml file that you need to create and deploy to mobile device. Besides this option, we also ship a few project templates that you can leverage to create task or project extension. The template will automatically create an assembly to be used by Mobile Project Center instead of using the ame file. Please refer to Using Project Templates document for more details.

ArcGIS Mobile provides an extensible application framework for those who want to extend the out-of-box mobile application. The application can be extended by either adding new functionalities to existing tasks, or by creating new tasks that embed specific business logic for field operation. This walkthrough will focus on building project extension that adds functions to existing task. Depending on your specific needs, application framework allows you access different function areas within existing tasks. For example, you might want to write a custom geometry collection method that validates geometry being collected in collect feature task, or you might want to connect to a bluetooth rangefinder to read offset information for a feature you are interested, and so on and so forth.

Project Description

By default the MapPage has a default context associated with it. The default context has a default map action (normally it's Pan map action). We will add a ZoomInOutMapAction to the MapPage so that user can activate this map action temporarily for map navigation. Once navigation is done, the MapPage's active map action will be restored to its previous map action. After completing this exercise, you should have better understanding on what's involved in extending existing tasks and how to hook up your custom function to the application.

Concepts

If you haven't done so, you will find it very helpful to read the overview document for application framework before you start with this walkthrough. The overview document gives you a big picture for the application framework and its design/architecture. To walk through this tutorial, we assume you have a good understanding of Visual Studio .NET 2008, and know how to create a class library for Windows Mobile 5/6 platforms.

Note that for extending ArcGIS mobile application, Visual Studio .NET 2005 is no longer supported.

Requirements

To follow this walkthrough, you need to have a development machine and a mobile device (or emulator) running windows mobile 5/6 Pocket PC operating system. See below for detailed requirements. To learn more about how to setup your development machine and mobile device/emulator, click here.

Development Machine

Visual Studio .NET 2008 W/ SP1
.Net Compact Framework 2.0 SP2
ArcGIS mobile core framework for Windows mobile
ArcGIS mobile application framework
Windows Mobile 5 SDK for pocket pc/ smartphone, or Windows Mobile 6 professional/standard SDK refresh
ActiveSync 4.5 (XP) or Windows Mobile Device Center (Vista/Windows 7)

Mobile Device (or Emulator)

Windows Mobile 5 pocket pc/smartphone, or Windows Mobile 6 professional/standard
.Net Compact Framework 2.0 SP2
ArcGIS Mobile application
ArcGIS Mobile core framework runtime
ArcGIS Mobile application framework runtime

Preparations

To develop and test your project extension, you will need to have a mobile project with data loaded on your device or emulator. If you don't already have it, please follow the steps below.

Prepare a map document with your data
Publish the document as a mobile service on an ArcGIS server, this can be done through server manager or ArcCatalog
Use mobile project center to create a mobile project that consumes the mobile service you published on previous step
Use mobile application to download the mobile project to your device or emulator, and get data for it

If you are developing with Microsoft emulator, make sure the emulator is connected and cradled correctly through Device Emulator Manager within Visual Studio.

Steps:

Creating a new project using Visual Studio .NET 2008
1. Start Visual Studio .Net 2008
2. On the File menu, point to New, then click Project.
3. In the New Project dialog, expand Visual C# under Project Types. 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 "ZoomExtension" as project name and specify the location to store the project. Click OK to proceed.
6. For the target platform, choose Windows Mobile 6 Professional SDK.
7. For the .NET Compact Framework version, select .NET Compact Framework Version 2.0.
8. For the Templates to use, choose Class Library. Click OK, this will create an empty new project for you.
Adding References to ArcGIS Mobile Application Framework
Now the first thing you want to do is to add references to both the core framework and application framework. Right-click on References node in Solution Explorer, and choose to Add References...
Select both ESRI.ArcGIS.Mobile and ESRI.ArcGIS.Mobile.Client. Click OK to proceed.
Since we need to use a menu item, let's also add System.Windows.Forms namespace from .Net Compact Framework.
Creating Extension Class
Visual Studio has created a Class1.cs file by default. Let's rename it to ZoomInOutMapActionExtension.cs. Visual Studio will ask you if you want to perform a rename for all references to the code element "class1", click Yes. Now double-click the renamed file to open it, you will see the class name has already been renamed to "ZoomInOutMapActionExtension".
In code window, add references to application framework, the core framework, and System.Windows.Forms namespace.
```
using ESRI.ArcGIS.Mobile.MapActions;
using ESRI.ArcGIS.Mobile.Client;
using System.Windows.Forms;
```
Inherenting ProjectExtension and IDisposable
Let's make ZoomInOutMapActionExtension class inherit from ProjectExtension and IDisposable classes.
```
  public class ZoomInOutMapActionExtension : ProjectExtension, IDisposable
  {
  }
```
Click on ProjectExtension, you can select Implement abstract class 'ProjectExtension' menu item. Do the same thing for IDisposable.
This will automatically create Initialize, Uninitialize, and OnOwnerInitialized methods for you. Do the same thing for IDisposable, which will create Dispose method from IDisposable.
The Initialize method is called by the Project when the Project is initializing. At this point you are guaranteed that all other Tasks and Extensions have been instantiated.
Creating ZoomInOutMapAction and Signing up for StatusChanged Event
At application level, we will define a few variables to hold ZoomInOutMapAction, a help string, and a menu item.
```
    ZoomInOutMapAction m_zoomInOutMapAction;
    MenuItem m_stylusZoomMenuItem;
```
Then create a constructor for the project extension, and instantiate m_zoomInOutMapAction.
```
   public ZoomInOutMapActionExtension()
    {
      // Create ZoomInOutMapAction
      m_zoomInOutMapAction = new ZoomInOutMapAction();
    }
```
Creating Menu Item and Adding it to the MapPage
Next, we need to create a menu item and insert it into the default context menu on MapPage, and set a help string for the ZoomInOutMapAction when it's clicked. The best place to do this is inside of the Initialize method, which is called by the project when the project is initializing. At this point you are guaranteed that all other tasks and extensions have been instantiated.
We also need to listen to the menu item's click event, and when that is fired, we set temporary map action to the ZoomInOutMapAction. After the map action is completed, the map action for the MapPage will be reset to the map action that is currently active.
```
    protected override void Initialize()
    {
      // create a new menu item
      m_stylusZoomMenuItem = new MenuItem();
      m_stylusZoomMenuItem.Text = "Stylus Zoom In/Out";
      m_stylusZoomMenuItem.Click += new EventHandler(MenuItemClick);

      // add the menu item to the MapPage's Default items
      MapPage.DefaultUpperItems.Insert(0, m_stylusZoomMenuItem);
    }

    void MenuItemClick(object sender, EventArgs e)
    {
      // when the menu item is clicked, set temporary map action to the ZoomInOutMapAction
      // after the map action is Completed, the map action will be reset to the map action
      // that is currently active
      MapPage.SetTemporaryMapAction(m_zoomInOutMapAction);
    }
```
This should do most part of what we need. However, don't forget to detach events from application level objects when the project gets uninitialized. The best place to achieve this is through the Uninitialize method. In this case, we will remove the menu item and help text from the MapPage's default context.
Note: As guidelines for best practice, you should code defensively because Uninitialize method may be called by the application even if Initialize or OnOwnerInitialized methods are never called.
```
    protected override void Uninitialize()
    {
      // remove menu item
      MapPage.DefaultUpperItems.Remove(m_stylusZoomMenuItem);
    }
```
The OnOwnerInitialized method will be called by the project when it's initialized. At this point, all other tasks and project extensions will have been initialized. Since we are doing nothing here, we can clear out the code.
```
    protected override void OnOwnerInitialized()
    {
    }
```
Disposing ZoomInOutMapAction
We need to call Dispose on any objects that implement IDisposable. In this case, we will dispose the ZoomInOutMapAction.
```
    public void Dispose()
    {
      if (m_zoomInOutMapAction != null)
        m_zoomInOutMapAction.Dispose();
    }
```
Preparing and Deploying ArcGIS Mobile Extension
Option 1: Preparing an ArcGIS Mobile Extension file (.ame)
If you already have a mobile project loaded on your testing device or emulator, you can create an ame file to describe your extension assembly and deploy it to your device so that mobile application knows where/what to load.
For project extension, a simplest .ame file would follow the format as shown below. Potentially it could be more complicated with other information included, and can be read or written by the application (if you implement IXmlSerializable).
```
<Extensions>
  <ProjectExtensions>
    <ProjectExtension assemblyQualifiedName=<namespace>.<class name>, <assembly name>"/>
		</ProjectExtensions>
</Extensions>
```
In our case, the .ame file should look like the following:
```
<Extensions>
  <ProjectExtensions>
    <ProjectExtension assemblyQualifiedName="ZoomExtension.ZoomInOutMapActionExtension, ZoomExtension"/>
  </ProjectExtensions>
</Extensions>
```
Save this file with your visual studio project. Name it "ZoomExtension.ame". Make sure that you copy the ame file to your mobile project folder. For example, if you have a mobile project stored at \My Documents\ArcGIS Mobile\RedlandsHydroDistribution\ folder, you should put your ame file here.
Note:
You can use a text editor or any program you feel most comfortable with to create/edit the ame file.
Option 2: Preparing an Assembly for Mobile Project Center and Include it in Your Mobile Project
Similar to the walk-through for creating your first task, you can prepare an assembly for Mobile Project Center before you author a mobile project, and use Mobile Project Center to include your extension assembly in the mobile project you author.
Please refer to Step 5 Option 2 in walk-through for creating your first task document for more details.
Build the project to make sure there is no typo error or anything else.
Deploying Assembly/.ame to Emulator or Device
Before mobile application can load the extension, you will need to deploy both the assembly and the ame file to your device or emulator. Follow the steps below for deployment.
Deploy the assembly to the same folder as the ArcGIS Mobile Application executable. By default the path is \Program Files\ArcGIS Mobile\10. To achieve this within visual studio, change the project's Output File Folder to %CSIDL_PROGRAM_FILES%\ArcGIS Mobile\10.
To build and deploy the project extension, right-click on the project name in Solution Explorer and select Deploy. Visual Studio will prompt you for deployment target. Choose Windows Mobile 6 Professional Device or the one that matches your device/emulator.
Note that if you choose an emulator, please make sure the emulator is connected and docked with your development machine.
If deployment is successful, you should be able to see the assembly on your device/emulator under \Program Files\ArcGIS Mobile\10.
Have a Test Drive
Now it's time to test drive your project extension. Note that if the mobile application is already running on your emulator/device, you will need to exit the application otherwise it won't be able to load the extension.
Launch the mobile application, choose your mobile project. Once the project is loaded, click the View Map task to see the MapPage.
You will notice that there is a new menu item being added to the top of the right soft menu. If you click on it, the MapPage will be temporarily associated with the ZoomInOutMapAction we created, and you can use your stylus to drag on map to zoom in or out continuously. Once this operation is completed, the MapPage's current map action will be restored.
After you activate the ZoomInOutMapAction by clicking on the menu item, if you click on the help tip menu item, you will see the help string has been changed as we expected.

9/20/2011