Migrating from ArcGIS Explorer 500 to ArcGIS Explorer 900

Summary
This topic assumes you have experience customizing ArcGIS Explorer 500 or prior, and aims to help you revise and redeploy your customization for use in ArcGIS Explorer 900.

In this topic

ArcGIS Explorer 900 Customization points

The ArcGIS Explorer 900 API is a new API designed for greater flexibility and ease of programming. Objects that actually exist in ArcGIS Explorer application such as Application, View, Map, Layers, Table, Geodatabase, and Geometry so that programming customizations is a logical process. The ArcGIS Explorer 500 API allowed developers to extend ArcGIS Explorer by means of developing tasks. The ArcGIS Explorer 900 API replaces the task with six Add-Ins:

Button

A Button displays on the Ribbon, and runs code when the user clicks the button. Buttons derive from the abstract class Button and can override Enabled, OnClick, and OnUpdate. Buttons are placed on the ribbon at runtime.

CheckBox

A checkBox displays on the ribbon and runs code when the box is checked or unchecked. CheckBoxes derive from the CheckBox abstract class and can override OnClick and OnUpdate. CheckBoxes are placed on the ribbon at runtime.

ComboBox

A comboBox displays on the ribbon and runs code when an item from the drop down list is selected. ComboBoxes derive from the ComboBox abstract class and can override OnSelectionChanged. ComboBoxes can specify a caption and an image that are used to display the combo box on the ribbon. ComboBoxes are placed on the ribbon at runtime.

DockWindow

A DockWindow is a dockable window that displays in the application and behaves like other built-in dockable windows, for example the Find window. DockWindows derive from the abstract class DockWindow that derives from System.Windows.Forms.UserControl, providing a surface on which to place other Windows Forms controls to provide a user interface. DockWindows appear as separate child windows of the application that can be docked or floated, a button is used to show and activate the DockWindow.

Gallery

A Gallery displays on the ribbon, and runs code when the user clicks an item in the gallery.  Galleries derive from the abstract class Gallery and can override OnClick. Galleries are placed on the Ribbon and populated with gallery items at runtime.

Extension

An extension is a class that does not rely on user-interaction, but instead can be used to run code in response to the application starting up or shutting down. Another use of an extension is to add a timer and to run code periodically while the application is running without requiring user interaction, for example to show and update graphics on the map. Extensions derive from the abstract class Extension and can override OnStartup and OnShutdown. Extensions are automatically started when the application starts and their lifetime is tied to the lifetime of the application. Extensions have no user interface. Extensions are useful for custom functionality that runs in the background.

Migrating from Task Development

Tasks that have been developed with the ArcGIS Explorer 500 or prior API will continue to work with the corresponding version of ArcGIS Explorer, but will not work for ArcGIS Explorer 900.
Tasks that have been developed with a previous version of the ArcGIS Explorer API are typically composed of two classes, the TaskUI user interface class, and the Task class that executes code on a background thread. Data was passed from Task to TaskUI by using the ParameterSet class.
  • If you wish to replicate the look and feel of the TaskUI part of the old task, you should consider developing a DockWindow Add-In for ArcGIS Explorer 900.
  • To replicate the behavior of the Task class of the old task, you should consider developing a Button, DockWindow or Extension add-in and also make use of the new Background worker class, which can be found in the ArcGIS Explorer Threading namespace.
The ArcGIS Explorer 900 API has five new namespaces, namely:
The Data, Geometry, Mapping, and Threading namespaces are contained in the assembly ESRI.ArcGISExplorer.dll, and the Application namespace is contained in the ESRI.ArcGISExplorer.Application.dll assembly.

Dealing with changes to the task execution model

The ArcGIS Explorer 500 application defined a specific model for task execution, allowing multiple instances of a task to be initiated, report feedback, and finally to report results. The Results pane listed tasks currently executing, and also listed any Result objects produced by the task (for example the Find Address or Find Directions tasks). Tasks which only required input from the user or interaction with the map showed results within the task pane itself, also providing an option to add results to the Results pane (for example the Create Notes or Measure tasks).
The main difference in ArcGIS Explorer 900 is the absence of the Results pane. To migrate a task, first decide which of the scenarios below best describes the required workflow for your function:
  1. The user should wait for the function to complete before proceeding.
    Migrate the code from your task to a new add-in project using the most appropriate classes (Button, CheckBox, ComboBox, DockWindow, Gallery or Extension). Additionally, make use of the ProgressHelper (part of the ESRI.ArcGISExplorer.Application namespace) if required to show feedback to the user if some functions take a while to complete.
  2. The user can continue working and interacting with the map while the function is working, and can check the results of the function at a later stage.
    Migrate the code from your task to a new add-in project using the most appropriate classes (Button, CheckBox, ComboBox, DockWindow, Gallery or Extension). Use a BackgroundWorker class (part of the ESRI.ArcGISExplorer.Threading namespace) to perform any lengthy operations on a worker thread; the main UI thread is then freed up, allowing the user to continue working with other application functionality; passing data to the BackgroundWorker is now achieved by using the event handler arguments. Show any results of the function by, for example, populating a list in a dockable window; see the Find dockable window for an example of this type of workflow. Implement additional user interface elements to add results in to the map as Notes, Graphics or Layers, if required; again, the Find dockable window demonstrates this model of interaction. See the Threading namespace overview for more information on using the BackgroundWorker class.
In ArcGIS Explorer 500, tasks were defined and saved in the NMF file, along with a ParameterSet which could be used to contain initial settings for the TaskUI or Task by reading the saved parameters. There is no direct equivalent in ArcGIS Explorer 900, because the architecture does not save add-in information in NMF files. Consider using standard .NET application and user settings instead. See the Application Settings Overview topic on MSDN at http://msdn.microsoft.com/en-us/library/k4s6c3a0.aspx for more information.

ArcGIS Explorer API Comparison

The following table lists ArcGIS Explorer 500 classes and indicates the broadly equivalent class in ArcGIS Explorer 900. Note that due to changes in the behavior and architecture of the application, some classes have no direct equivalent.
ArcGIS Explorer 500 Class
ArcGIS Explorer 900 Class
AddressResult
Note
DatabaseLayer
FeatureLayer
E2
Application
Envelope
Envelope
Feature
Row
FeatureCursor
RowCollection
FeatureSet
RowCollection
Field
Column
FieldCollection
ColumnCollection
Geometry
Geometry
GroupLayer
Folder
ImageSet
Symbol
Layer
Layer
LayerCollection
LayerCollection or Layer
LayerResult
KMLLayer or RasterLayer
LocalLayer
KMLLayer or RasterLayer
LocalVectorLayer
FeatureLayer
Menudef
no equivalent
ParameterSet
no equivalent
PlaceResult
Note
Point
Point
PointCollection
no equivalent
Polygon
Polygon
Polyline
Polyline
Result
Note
ResultInfo
no equivalent
ResultManager
MapItemCollection
ServerLayer
ServiceLayer or GeoRSSLayer
ShellResult
Link
SkinInfo
no equivalent
StyleManager
Symbol
Task
BackgroundWorker
TaskContext
no equivalent
TaskUI
DockWindow, Gallery, Button, CheckBox, or ComboBox
TaskUICenter
no equivalent
TaskUICollection
no equivalent
View
MapDisplay
View3D
MapDisplay
XMLHelper
ToXMLString methods added to classes

Adding Content to ArcGIS Explorer

The ArcGIS Explorer 900 API provides comprehensive support for adding layers to the application. The most notable change to the ArcGIS Explorer 500 layer model, is the replacement of the LocalLayer class with two new classes, a KMLLayer class for representing KML content, and a RasterLayer class for representing Raster content.  The LocalVectorLayer and DatabaseLayer classes have been replaced with a new FeatureLayer class that can be used to represent a layer stored in an ArcSDE database, a file Geodatabase or a Shapefile.  The ServerLayer class continues to support Map and Globe services, WMS services, IMS services and the GeoRssLayer class supports  GeoRSS feeds.
When working with the ArcGIS Explorer 500 API, content could be integrated with the application using one of several Result classes (e.g. PlaceResult, AddressResult, etc.).  The ArcGIS Explorer 900 API has simplified the multiple result model with a single Note class.  A Note has an associated Graphic and Popup. The graphic (and associated Geometry) represent the note location on the map display, the Popup class represents the content of the popup window, associated with the note, that is displayed when prompted by user interaction.  When replicating the behavior of Results using the ArcGIS Explorer 900 API, other MapItem classes also provide useful functionality, for example, the Link and Folder classes which, respectively, enable you to hyperlink to content elsewhere, and group related content in logical containers.
A new PackageLayer class has been added to the API to support adding content to ArcGIS Explorer published using the layer packaging capabilities introduced with ArcGIS Desktop 9.3.1 applications.

Navigating ArcGIS Explorer

ArcGIS Explorer 900 introduces an additional two-dimension (2D) view mode, enabling you to navigate in either two-dimensions or three-dimensions (3D). The Explorer map window supports two display modes: You can view the content of your map in 3D mode which gives you a 3D global perspective where you can control the location, altitude and pitch relative to the surface of the earth. Or you can view your map in 2D mode which gives you a planimetric perspective where you are looking straight down on a projected map surface.
The ArcGIS Explorer 500 navigation model was based on a relationship between an observer location and target location. Together the observer and target determined the current view of the globe, and the properties of the current view were represented via the View3D class. This concept of observer and target location has been preserved with ArcGIS Explorer 900.  Together these two locations now determine a Viewpoint, and properties of the current view are represented with an instance of the Viewpoint class.  To complement the new 2D view mode, and envelope can now be used to construct a Viewpoint. A Viewpoint cannot store both a 2D envelope alongside a 3D observer\target location—you must choose the Viewpoint mode on instantiation.
As an ArcGIS Explorer developer you can check whether the map is currently two-dimensional or three-dimensional using the ViewMode property on the MapDisplay class. It should be noted that the behavior associated with some method calls will vary depending on the current ViewMode, however, this behavior change is managed by the application and should be of little concern when programming Add-Ins.

Searching Content in ArcGIS Explorer

When working with the ArcGIS Explorer 500 API, map content could be queried using a combination of classes, namely, the FeatureSet, Feature, and Field classes. The ArcGIS Explorer 900 API replaces this feature-centric model with a relational data model, comprising Table, Row and Column classes. It is envisioned that the new data model will provide you with greater flexibility when querying data via the API. The ArcGIS Explorer 500 API contained useful helper methods on Layer classes that provided query and search capabilities, the equivalent of this functionality has moved to the new Table class, which provides several methods for searching the contents of tables. The Table class represents both spatial and non-spatial data. If you want to undertake advanced searches against map content, the Filter class provides access to several constraints you might choose to apply to your searches.
One notable new feature in the Explorer 900 API is the ability to bind a Table to any .NET control that supports data binding, such as a DataGridView control.  To do this you create a new TableBindingAdapter class, pass in the Table object then set the appropriate binding source property on the control.

Visualizing Content in ArcGIS Explorer

The ArcGIS Explorer 500 API allowed developers to symbolize content with symbols stored in an ESRI Server Style file created by ArcGIS Desktop or Engine.  The ArcGIS Explorer 900 API removes this dependency on the Server Style file, and allows a larger choice of symbology out of the box.  In ArcGIS Explorer 500, symbols were applied to Layers and Results by name, and a list of symbol names in all currently referenced style files could be retrieved from the StyleManager class; in ArcGIS Explorer 900 the Symbol class provides a series of static properties to create new Symbol objects to represent any of the supported Symbols, which can then be applied to MapItems.
ArcGIS Explorer 500 exposed two events that enabled developers to draw graphics with OpenGL; this functionality is not supported in the ArcGIS Explorer 900 application; however ArcGIS Explorer 900 adds the concept of a Graphic, which is way to draw to the map using existing symbology—graphics are not persisted to the map document and are ideal for drawing moving objects.

ArcGIS Explorer 900 Security

In ArcGIS Explorer 500 and prior, permissions were controlled by the home server. A task could be downloaded from a path specified in an NMF, and you could browse to an NMF in order to add a new Task to the application. The home server could prevent downloads by using a model of security zones by which you could restrict where your users could download tasks from, i.e. trusted sites, intranet or internet zones: http://resources.esri.com/help/9.3/explorer/TaskDownloadSecurity.html

In ArcGIS Explorer 900, permissions are no longer controlled by the home server. Instead, application configurations replace the home server concept and allow you to host various applications that different users in an organization can use, rather than different home servers to which users connect.

ArcGIS Explorer can connect to an application configuration over http or over UNC. In either case, Explorer uses the information from the application configuration to configure itself for the end-user. You can make changes to the configuration, and each time a user starts Explorer connected to it, they’ll see the latest version of the application.
Additionally, by using an application configuration, you can control the following permissions:
  • The ability to open a map other than the application’s default map
  • The ability to save changes to a map that’s open
  • The ability to add content to a map (i.e. services, local data, results, etc)
  • The ability to print a map
  • The ability to access and modify application options (such as what map is open by default, proxy server configuration, etc).
  • The ability to manage add-ins in the application.