ArcGIS Mobile SDK - Walk-through: Creating your first project extension for Windows application

Complexity: Beginner Data Requirement: Installed with software

In this walk-through, you will be guided 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.

During this walk-through, you will follow these steps:

Creating a new class library project with Visual Studio .NET 2008
Creating an App Menu project extension
Adding a menu item to the application menu
Creating an About this Project page
Deploying the project extension to the ArcGIS Mobile for Windows application
Trying the App Menu project extension

Where to get the sample

Downloadthe AppMenuExtension sample.

Prerequisites

Visual Studio .NET 2008 with SP1
.NET Framework 3.5 SP1
ArcGIS Mobile for Windows Application and Mobile API assemblies
When running the ArcGIS Mobile 10 setup on a Visual Studio 2008 development machine, all these mobile components are installed and configured.

Creating a class library project with Visual Studio .NET 2008

Steps:

Start Visual Studio .NET 2008 and click File Menu > New > Project.
Click Windows under Visual C# in the Project types pane of the New Project dialog box.
Choose .NET Framework 3.5 from the drop-down list at the top right of the dialog box.
Choose Class Library in the Templates pane.
Name the project AppMenuExtension, specify the location for the project, then click OK.
Add references to the ArcGIS Mobile, application framework, and Windows WPF libraries as well.
- ESRI.ArcGIS.Mobile
- ESRI.ArcGIS.Mobile.Client
- PresentationCore
- PresentationFramework
- WindowsBase

Creating an AppMenuExtension project extension

By default, Visual Studio creates a Class1.cs file for this new class library project. Change the name to AppMenuExtension.cs by right-clicking the Class1.cs file and renaming it. Choose Yes when you are prompted to rename the file. Double-click to open the file in Visual Studio.

Steps:

Add a reference to the application library. Then make the AppMenuExtension class inherit from the ProjectExtension class in the application framework.
```
using ESRI.ArcGIS.Mobile.Client;
...
public class AppMenuExtension : ProjectExtension
```
Implement an abstract class for the ProjectExtension class. Point to ProjectExtension and choose Implement abstract class 'ProjectExtension'.
Visual Studio creates the Initialize(), OnOwnerInitialized(), and Uninitialize() methods for you. These functions are called when the project is initializing, initialized, or about to close.

Add a menu item to the application menu.

Add a private member variable for the new menu item.

private MenuItem ami;

Insert the following codes 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.

// disable/enable menuitem
private bool AboutProjectCommandCanExecute()
{
    return true;
}

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.

// 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 About this Project page

Steps:

Add a WPF user control to this project and name it AboutThisProjectPage.
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: an .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.
Add an .xaml name space—MobileClient—and map it to the application framework library.
Change UserControl to MobileClient:MobileApplicationPage. Use MobileApplicationPage as its base class.
```
<MobileClient:MobileApplicationPage>
...
</MobileClient:MobileApplicationPage>
```

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.
Add a reference to the application framework library.
```
using ESRI.ArcGIS.Mobile.Client
```

Change the page's base class to MobileApplicationPage.

public partial class AboutThisProjectPage : MobileApplicationPage

Set the page title and subtitle.

Add these two lines to the class constructor:

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

Add an icon to the project and change its Build Action property to Resource in the file Properties panel.

Add these two lines to the constructor:

// page icon
Uri uri = new Uri("pack://application:,,,/AppMenuExtension;Component/Tips72.png");
this.ImageSource = new System.Windows.Media.Imaging.BitmapImage(uri);

Add a Back button.

On the bottom of a page is the navigation bar. You could add a Back button, a Forward button (Next, Accept, or Finish) for page navigation, and a page menu in the middle of this bottom bar. In this walk-through, you only add a Back button. Insert this line in the constructor:

this.BackCommands.Add(this.BackCommand); // back button

//Override back button function
protected override void OnBackCommandExecute()
{
   MobileApplication.Current.Transition(this.PreviousPage);
}

Populate project information to the text box. This just lists information about map extent and map layers. Insert the following codes in the class constructor:

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

  prjinfo += "Layers: \r\n";
  foreach (DataSourceInfo dsinfo in MobileApplication.Current.Project.DataSourceInfos)
  {
    if (dsinfo is MobileCacheInfo)
    {
      LayerInfoCollection flinfos = (dsinfo as MobileCacheInfo).LayerInfos;
      foreach (LayerInfo flinfo in flinfos)
      {
        if(flinfo is FeatureLayerInfo)
        prjinfo += "LayerName=" + flinfo.Name
                + ", Visibile=" + flinfo.Visible.ToString()  
                + "\r\n";
      }
    }

    prjinfo += "\r\n";
}

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

Deploying 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. There are two ways to do this: using an .ame file or adding a new task to a mobile project within Mobile Project Center. Here you are going to use the first approach. The second approach is explained in the "Using ArcGIS Mobile Visual Studio project templates" section.

Steps:

Copy the assembly AppMenuExtension.dll to the Windows application bin folder or the application Extensions folder:
- Location 1: <Install Dir>\ArcGIS\Mobile10.0\bin
- Location 2: C:\Documents and Settings\All Users\Application Data\ESRI\ArcGIS Mobile\Extensions\ (for Windows XP:) or C:\ProgramData\ESRI\ArcGIS Mobile\Extensions\ (for Windows Vista or 7)
  Note:
  The mobile installer does not create the extensions folder. You need to manually create this folder if you want to deploy your extension assembly at this location.
Create an ArcGIS Mobile application extension file (.ame).
An ame file describes the assembly's name, name space, class name, and settings as necessary. The .ame file could be put into a mobile project folder (where you find the .amp file). When the mobile application opens the project, it reads the .ame file and loads the App Menu extension from the specified assembly. The content of the .ame file is merged into the project .amp file and is deleted when the project is closed.
The .ame file also can be deployed to the mobile application Extensions folder (location 2 above). It is available at the application level, meaning that it is loaded by the application no matter which mobile project is opened. The .ame file is an .xml file written in the format as shown below:
```
<Extensions>
<ProjectExtensions>
    <<ProjectExtension assemblyQualifiedName="namespace.class_name, assembly_name"/>  
</ProjectExtensions>
</Extensions>
```
For the App Menu extension, create the .ame file as below and copy it over to a mobile project folder.
```
<Extensions>
<ProjectExtensions>
    <ProjectExtension assemblyQualifiedName="AppMenuExtension.AppMenuExtension, AppMenuExtension"/>
</ProjectExtensions>
</Extensions>
```
To have the Windows application load the extension assembly successfully, you need to make sure the assembly's name space, class name, and assembly file name are spelled correctly here. (Name space and class name are case sensitive.)
The .ame file also can be deployed to the Extensions folder (location 2 above). Then this extension will be available at the application level, and you see the menu from all projects.

Trying the App Menu project extension

Steps:

Launch the ArcGIS Mobile for Windows application and open the project. Notice the About this project menu item appears in the application menu.
Tap About this project and navigate to the About this Project page.
Tap Back to return to the previous page.

This walk-through explains how to develop a simple mobile project extension for the ArcGIS Mobile for Windows application by creating a .NET assembly from scratch and deploy it using an .ame file. To give you a better development experience, a Visual Studio project template is provided to generate a C# project for an extension and a project to create a Mobile Project Center (MPC) extension. With the MPC extension, you could add your extension to a mobile project directly when creating a mobile project in MPC, without handling the .ame file. Refer to "Using ArcGIS Mobile Visual Studio project templates" for details.

9/20/2011