ArcGIS Runtime SDK for Windows Mobile - Creating your first project extension for a Windows application

Complexity: Beginner Data Requirement: Installed with software

In this walkthrough, you'll learn how to create a project extension for the Windows application. This project extension adds an About this project menu item to the application menu, which navigates to another page for information about the current project.

ArcGIS for Windows Mobile ships with two Visual Studio 2008 C# project templates to help you create Visual Studio projects for building a Windows application task or project extension. These templates are integrated with Visual Studio 2008 and can be used in the same way as the Visual Studio built-in project templates. A project created based on the template contains classes for your task or project extension, assembly reference, and project properties.

In this walkthrough, you'll create an App Menu extension using the Visual Studio project template and deploy it with Mobile Project Center (MPC).

The steps involved include the following:

Create a solution using the template for Visual Studio .NET 2008.
Add a menu item to the application menu.
Create an About this Project page.
Add the custom extension to a project with MPC.
Deploy the project extension to the ArcGIS Mobile for Windows application.
Test the App Menu project extension.

Where to get the sample

Download the AppMenuExtension sample.

Prerequisites

Software required for development;

Visual Studio .NET 2008 SP1.
.NET Framework 3.5 SP1.
ArcGIS Mobile for Windows application, Mobile API assemblies, and Visual Studio 2008 project templates for ArcGIS Mobile. All are installed and configured with the ArcGIS for Windows Mobile setup.

Creating an ArcGIS Mobile application project extension using a Visual Studio project template

Steps:

Start Visual Studio .NET 2008, and click File > New > Project.
Click ArcGIS Mobile under Visual C# in the Project types pane on the New Project dialog box.
Choose .NET Framework 3.5 from the drop-down list at the top right of the dialog box.
Choose Extension in the Templates pane.
Name the project AppMenuExtension, specify the location for the project, then click OK.
.
Since you do not need the Windows Mobile project, delete it from the solution.
Visual Studio creates three projects in the solution using this template: one for the Windows application, one for the Windows Mobile application, and one for MPC.
- The Windows and Windows Mobile projects are for developing assemblies used with the Windows application and Windows Mobile application.
- The MPC project is for developing an assembly for describing the application's AppMenuExtension assembly. MPC needs it to deploy the App Menu extension to mobile projects.

Review the AppMenuExtension_Win project. It contains an AppMenuExtensionClass derived from ProjectExtension, which is the base class for all extensions within the ArcGIS Mobile for Windows application. The template creates an extension skeleton with a TODO list for the required methods.

The Visual Studio template creates the Initialize(), OnOwnerInitialized(), and Uninitialize() methods for you. These functions are called when the project is initializing, initialized, or about to close. The code should look like the following:

public class AppMenuExtensionClass : ProjectExtension
  {
    protected override void Initialize()
    {
      // TODO:
      // Note: This method is called by the Project when it's initializing. At this point
      // all other Tasks and ProjectExtensions have been instantiated.
    }

    protected override void OnOwnerInitialized()
    {
      // TODO:
      // Note: This method is called by the Project when it's Initialized. At this point
      // all other Tasks and ProjectExtensions will have been Initialized
      // Do not add/remove ProjectExtensions to the Project or Application during this method.
    }

    protected override void Uninitialize()
    {
      // TODO: Dispose or Detach events from application level objects
      // Note: This method is called by the Project before the Project is closed.
    }
  }

Add a menu item to the application menu.

Add a reference to windows controls.
```
using System.Windows.Controls;
```
Add a private member variable for the new menu item.
```
private MenuItem ami;
```

Insert the following code to the OnOwnerInitialized() function, which adds a menu item to the application menu when opening the project:

protected override void OnOwnerInitialized()
{
    // access UI controls from UI thread via Dispatcher
    if (!MobileApplication.Current.Dispatcher.CheckAccess())
    {
        MobileApplication.Current.Dispatcher.BeginInvoke((System.Threading.ThreadStart)delegate()
        {
            OnOwnerInitialized();
        });
        return;
    }
         
    UICommand AboutProjectCommand = new UICommand("About this project", param => this.AboutProjectCommandExecute(), param => this.AboutProjectCommandCanExecute());

    ami = new MenuItem();
    ami.Header = "About this project";
    ami.Command = AboutProjectCommand;
    MobileApplication.Current.MenuItems.Add(ami);  
}

The AboutProjectCommandCanExecute() function is used to determine when the menu item is enabled. Here, make it always enabled.
AboutProjectCommandCanExecute() is the function linked to this About this project menu item. In this example, you are going to navigate the application to another page (About this Project page) to display information about the current project. You will create this page later.
```
// disable/enable menuitem
private bool AboutProjectCommandCanExecute()
{
    return true;
}
```

Add the following code for the execute method:

// menuitem command
private void AboutProjectCommandExecute()
{
    MobileApplication.Current.Transition(new AboutThisProjectPage());
}

Remove the menu item when it is uninitialized:

protected override void Uninitialize()
{
    // Remove the menu item we added in OnOwnerInitialized()
    MobileApplication.Current.MenuItems.Remove(ami);
    ami = null;
}

You have completed the project extension class. Next, you need to create the About this Project page.

Creating the About this Project page

Steps:

Add a mobile application page to this project and name it AboutThisProjectPage.
Use the page template by selecting the project and using the context menu to add a new item. Select ArcGIS Mobile in the categories, then Windows. Select page as the template to use and type AboutThisProjectPage for the name.
In the ArcGIS Mobile for Windows application, pages are derived from the MobileApplicationPage class. This class is a WPF user control. Visual Studio generates two files for this page: a .xaml file that defines its user interface (controls and layout) and a .cs file that contains function implementations.
Double-click the AboutThisProjectPage.xaml file to open it in Visual Studio.
The template has created a blank page for your customization and methods stubbed out for your code.

Since this page is only an empty page, add a text box to display project information. Remove the definition for height and width since the size will be controlled by the application. Now the About this Project page .xaml file should looks like this:

<MobileClient:MobileApplicationPage x:Class="CustomizationSamples.AboutThisProjectPage"schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:MobileClient="clr-namespace:ESRI.ArcGIS.Mobile.Client;assembly=ESRI.ArcGIS.Mobile.Client"
    >
    <Grid>
      <TextBox x:Name="prjInfoTB" Width="Auto" Height="Auto" HorizontalAlignment="Center"
               Foreground="{DynamicResource NormalTextBrush}"
               FontSize="{DynamicResource LargeFontSize}"
      >ProjectInfo</TextBox>
    </Grid>
</MobileClient:MobileApplicationPage>

Close the .xaml file and double-click the AboutThisProjectPage.xaml.cs file to open it.

Set the page title and subtitle.

Modify these two lines in the class constructor:

this.Title = "About This Project Page";  // title
this.Note = "Information about this"; // subtitle

Add a Back button.

Populate the project information to the text box. This lists information about the map extent. Insert the following code in the class constructor:

public AboutThisProjectPage()
{
    ...
  string prjinfo = "Map Extent: \r\n";
  prjinfo += MobileApplication.Current.Project.FullExtent.ToString() + "\r\n\r\n";

  prjinfo += "\r\n";
  prjInfoTB.Text = prjinfo;
}

You have completed the About this Project page. Compile the project and generate the assembly .dll.

Deploying the AppMenuExtension project extension

To have the Windows application load the App Menu extension in a mobile project, add this project extension to a mobile project using MPC. You can deploy one or more custom tasks or extensions (which are termed "capabilities" in MPC) that modify existing functionality or to embed new features into your project. When saving a mobile project, MPC copies the assemblies with the implementation of the tasks and/or extensions you have developed to the project folder.

Steps:

Copy the AppMenuExtension.dll assemblies to the MPC folders.
- Copy the Windows AppMenuExtension.dll from <working folder>\AppMenuExtension_Win\bin\Debug to C:\ProgramData\ESRI\MobileProjectCenter\Extensions\Win32 for Windows 7 machines.
  - For Windows XP machines, copy to: C:\Documents and Settings\All Users\Application Data\ESRI\MobileProjectCenter\Extensions\Win32 folder.
- Copy the MPC assembly AppMenuExtension.dll from the build location to the MPC folder. Your build location should be <working folder>AppMenuExtension\AppMenuExtension_ProjectCenter\bin\Debug, and the MPC folder for the Windows task C:\ProgramData\ESRI\MobileProjectCenter\Extensions.
Add the App Menu extension to a mobile project using MPC.
1. Ensure that MPC is shutdown so it can integrate your customization.
2. Launch MPC and create a project, or open an existing project.
3. Click Add on the Capabilities tab. The App Menu extension is listed here. Add it to the project and save the project.
4. Share your project with the HelloWorld task to ArcGIS Online or your own ArcGIS Server.

Testing the App Menu project extension

Steps:

Launch the ArcGIS Mobile for Windows application and download the project with your custom task. The About this project menu item appears in the application menu.
Click About this project, and navigate to the About this Project page.
Click Back to return to the previous page.

1/7/2015