Walk-through: Creating a new task

Complexity: Beginner Data Requirement: Installed with software

Introduction

ArcGIS Mobile provides a framework for the out-of-box hand-held application. It allows developers to customize the application by extending existing functions or implementing new functions that embed new business logic. In this walk-through we will show you how to create a simple task for the out-of-box mobile application. Specifically, you will learn how to add the new task to the SelectTaskPage with a name and a description. When the task is tapped, the application will navigate users to a new page. The new page will have a customized look and feel. By using a built-in menu item, your user can go back to SelectTaskPage.

Prerequisites

It would be helpful if you understand the task-based, workflow-driven design of the application before you start extending it. You may also find it useful to take a quick look at the ArcGIS Mobile Application framework overview (Windows Mobile) to get an idea about the architecture of the application framework for Windows Mobile platform.

To follow this walk-through, you should have basic knowledge of how to create a class library for Windows Mobile 5/6 applications.

Note: Visual Studio .NET 2005 is no longer supported for extending the mobile application.

Requirements

To follow this walk-through, 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 set up your development machine and mobile device/emulator, click here.

Development machine

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

Mobile device (or emulator)

  1. Windows Mobile 5 Pocket PC/smartphone, or Windows Mobile 6 professional/standard
  2. .Net Compact Framework 2.0 SP2
  3. ArcGIS Mobile application
  4. ArcGIS Mobile core framework runtime
  5. ArcGIS Mobile application framework runtime

Preparations

Keep in mind that the mobile application consumes mobile projects created and hosted on an ArcGIS Server. To test the new task you develop, you need to have a mobile project already loaded on your mobile device or emulator. If you haven't done so, please follow the steps outlined below:

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

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

Steps:
  1. 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 box, 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 drop-down list at the top of the dialog box.
    5. Enter HelloWorldTask as the project name and specify the location to store the project. Click OK to proceed.

      This is required

    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.

      This is required

  2. 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...

    This is required

    Add ESRI.ArcGIS.Mobile.Client to your project.

    This is required

  3. Creating a Hello World Page

    As aforementioned, we need to have our HelloWorld task listed on the task page, and when it's tapped, the mobile application will show a HelloWorld page with a default menu item.

    Right click on HelloWorldTask project, choose to Add > Windows Form... to add a new windows form.

    This is required

    On the Add New Item dialog, make sure you click Windows Forms under Visual C# Items category on the left panel, and choose Windows Form from Templates list box. Choose to add a new Inherited Form, and name it HelloWorldPage.cs. Click Add button.

    This is required

    You will see the Inheritance Picker dialog box as shown below.

    This is required

    Click Browse... button and navigate to where the application framework assembly is located, and pick it.

    This is required

    Visual Studio will show all classes you can inherit from. Select Page class and click OK.

    This is required

    Right click on HelloWorldPage.cs and select View Code.

    This is required

    In the HelloWorldPage.cs file, add the following name space for the application framework.

    using ESRI.ArcGIS.Mobile.Client;

    Note that the HelloWorldPage now inherits from ESRI.ArcGIS.Mobile.Client.Page class. The Page class provides the same look and feel as many other pages in the out-of-box application. It contains a title bar, an icon, and a left soft menu item which by default, will navigate user to previous page.

    This is required

    Optionally, you can maximize the form window so that the texts (showing "ArcGIS Mobile") for the window will disappear and leave more room on the form for your application. To achieve this, select the form on designer, and set its WindowState property to Maximized.

    This is required

    Let's add a title to HelloWorldPage. Click on the title bar on the form, and change the text to the Hello World Page.

    This is required

  4. Create A New Task

    By default, Visual Studio creates a Class1.cs file for us when we create the project. Let's rename it to HelloWorldTask.cs. If you are prompted for renaming the file name, choose Yes. Double-click to open the file.

    First thing to do is to add a reference to the application library.

    using ESRI.ArcGIS.Mobile.Client;

    Then, we need to make HelloWorldTask class inherit from Task class in application framework.

      public class HelloWorldTask : Task
      {
      }

    Now put your mouse on Task, and select Implement abstract class 'Task' menu item.

    This is required

    This will create an Execute method for you. When a task on the task page is clicked, the Execute method will be executed. What we want here is to navigate user to the HelloWorldPage that we prepared in previous step. To do that, the application framework provides a static class MobileApplication, which provides a Transition method that can take a form that inherits from Page class. We want to first set the cursor to the WaitCursor, and ask the MobileApplication to transition to the HelloWorldPage, then reset the cursor to its default type when the transition is done.

    Add the following name space to work with the cursor.

    using System.Windows.Forms;

    Here is what the Execute method should look like:

        public override void Execute()
        {
          try
          {
            Cursor.Current = Cursors.WaitCursor;
            MobileApplication.Current.Transition(new HelloWorldPage());
          }
          finally
          {
            Cursor.Current = Cursors.Default;
          }
        }

    Before you complete this, set up the title/descriptions and icons for the new task.

    To customize task name and description, we can do it within its constructor.

        public HelloWorldTask()
        {
          Name = "Hello World Task";
          Description = "This is my Hello World task";
        }

    You can also assign an icon to the task and it will be displayed with the task name and description on task page. The application library expects an icon with size 32 by 32 pixel. If you don't want to go the extra mile, the extensible application framework will use a default icon. We will use the default icon here.

  5. Preparing and Deploying ArcGIS Mobile Task

    Option 1: Preparing and Deploying ArcGIS Mobile Extension File

    If you already have a mobile project created and deployed to your testing mobile device with data, you can follow this step to let application recognize and load your task assembly.

    Before ArcGIS mobile application loads your task assembly, it needs to know the name of the assembly, and the fully qualified name of the task class within the assembly. This is made possible by providing the application an ArcGIS Mobile Extension file (.ame) as shown below. It has all information in XML format, and should be deployed to either the application executable folder or under a specific mobile project's folder. If deployed to application executable folder, it will be loaded no matter which mobile project is opened. If deployed to a specific mobile project's folder, it will only be loaded when that specific project is opened by application.

    Note that the AME file will be loaded for the first time, and all contents will be appended to the mobile project configuration file. The AME file itself will be physically removed from your device.

    As shown below, the AME file has the following format.

    <Extensions>
        <Tasks>
            <Task assemblyQualifiedName="<namespace>.<class name>, <assembly name>"/>
        </Tasks>
    </Extensions>

    In our case, create the ame file like the following:

    <Extensions>
        <Tasks>
            <Task assemblyQualifiedName="HelloWorldTask.HelloWorldTask, HelloWorldTask"/>
        </Tasks>
    </Extensions>

    Save the file as HelloWorldTask.ame with your visual studio project.

    For testing purpose, make sure you copy it to your device or emulator and put it under one of your mobile project. For example, if you have a mobile project located at \My Documents\ArcGIS Mobile\RedlandsHydroDistribution\, that's where you should put the ame file.

    Option 2: Preparing an Assembly for Mobile Project Center and Include it in Your Mobile Project

    If you use Mobile Project Center to create a mobile project, and need to include your task assembly in the mobile project configuration file, please use this option to create a Mobile Project Center assembly before you author the mobile project.

    Mobile Project Center is used to create mobile projects, and needs to know if you have a custom task or project extension that needs to be included in the project configuration file. To make this possible, you will create an assembly in Visual Studio that describes your task or project extension assembly, and optionally implement any UI that you would like user to customize your task or project extension class. As a simple example, you may want to allow user to specify a query filter when including a custom query task in your mobile project, and use it as default query filter when the task is executed by client.

    To create the assembly for Mobile Project Center, the easiest way is to leverage the out-of-box project templates.

    1. Launch Visual Studio 2008, click File > New > Project...
    2. Choose ArcGIS Mobile under C# language from Project Type list, choose Task from Templates list, and provide HelloWorldTask as task name. Then click OK button.

      This is required

    3. Visual Studio will create three empty projects for you. One is for the task project for Windows Mobile, one for Windows, and the third one for Mobile Project Center. Since we have manually created our HelloWorldTask, you can safely delete HelloWorldTask_Win and HelloWorldTask_WM projects.
    4. Double-click HelloWorldTask_ProjectCenter.xaml.cs to open it in editor. Right-click on CustomArcGISMobileTask namespace and choose to refactor it to "HelloWorldTask". Click Apply on preview dialog.

      This is required

      This is required

      This is required

      This is required

    5. Right-click HelloWorldTask_ProjectCenter class name in editor, and rename it to HelloWorldTask.

      This is required

    6. Update m_displayName to "Hello World Task" to make it more readable.

      This is required

    7. Updat Icon property to use the new task class name.

      This is required

    8. Update ReadXML method with new class name HelloWorldTask.

      This is required

    9. Open the property window for the project, and replace assembly name with HelloWorldTask.

      This is required

    10. Click Build tab on the project property window, and specify your ouput folder to be the Bin\Extensions under your ArcGIS Mobile install path. This ensures that if you build the project, the assembly will be placed in above folder. This folder will be searched by Mobile Project Center when you author mobile project.

      This is required

    11. Build your project to ensure that everything is going fine.
    12. Launch Mobile Project Center and create a new mobile project.
    13. Click Tasks button on left to bring up the Tasks list. Expand Add button to add HelloWorldTask. Follow the general guideline to add mobile service or other base map layers to your project. Up to now, you have included information about your task class in the mobile project configuration file.

      This is required
      This is required

    14. Save your mobile project. Use your testing device to download the project with data.
  6. Deploying the customized assembly to emulator/device
    1. Deploy the class library to the same folder as where the ArcGIS Mobile Application is located

      By default the path is \Program Files\ArcGIS Mobile\. To do this, let's change the Output File Folder to %CSIDL_PROGRAM_FILES%\ArcGIS Mobile\10.

      This is required
      This is required

    2. Build and Deploy the project

      To build the project, right-click on the project name inside of the Solution Explorer and select Build. To deploy the assembly to your emulator/device, right-click on the project name and choose Deploy. You should be prompted for where you want to deploy. Choose appropriate device or emulator depending on what you are using.

      This is required

    3. Check if deployment is successful

      To double-check if deployment is successful, you can use file explorer on your mobile device (emulator) to see if HelloWorldTask.dll exists under \Program Files\ArcGIS Mobile\10.

      This is required

    To learn more details on deployment, click here.

  7. Time for a Test-drive

    If the mobile application is already running on your emulator/device, it needs to be shut down otherwise the extension won't get loaded. Re-launch the application, choose the mobile project which you copied the .ame file to, and tap to open it. After the mobile project gets loaded, the application will find HelloWorldTask.ame file under the project folder and it will load it. Once the project is loaded, you will see the new task being added to the end of the task list on task page. If you didn't see it, try pressing arrow key on your device/emulator to go down to the end of the list.

    Tap on "Hello World Task", you will be taken to the custom HelloWorld page we built earlier. Click on Tasks menu item, you will be navigated back to task page.

    This is required
    This is required


9/20/2011