How to work with GIS Services

Summary
This topic describes the supported GIS service types and how to connect to them using the ServiceLayer and GeoRssLayer classes.

In this topic:
What are GIS Services
Working with the ServiceLayer class
Working with the GeoRssLayer class
To use the code in this topic, add references to System.Drawing.dll, ESRI.ArcGISExplorer.dll, and ESRI.ArcGISExplorer.Application.dll. Add the following namespace references via using (C#) or Imports (VB .NET) statements:
  • ESRI.ArcGISExplorer.Mapping
  • ESRI.ArcGISExplorer.Data
  • ESRI.ArcGISExplorer.Application

What are GIS Services

ArcGIS Server and ArcIMS are ESRI products that enable organizations to put maps, data, and tools on the Internet. ArcGIS Servers can also be accessed over your local area network. Open Geospatial Consortium, Inc. (OGC), Web Mapping Service (WMS) is an OpenGIS standard specification for interactive mapping based on requesting map images from a server over the Internet. OGC WMS client support in ArcGIS Explorer enables you to access these services over the Internet and add them to your maps as layers. The ArcGIS Explorer application programming interface (API) represents these service types with the ServiceLayer class. ArcGIS Explorer also supports GeoRSS services that provide syndicated, geographically tagged content and these are represented by the GeoRssLayer class.
 

Working with the ServiceLayer class

Approaches to creating a ServiceLayer

 
There are two different ways to create a ServiceLayer object as illustrated in the table below:
Approach
Steps
Pros and Cons
Create a ServiceLayer , then manually connect to data.
  1. Set up ServiceConnectionProperties object.
  2. Create a ServiceLayer.
  3. Connect a ServiceLayer.
  • Highly flexible. You decide when to connect and disconnect the ServiceLayer.
  • Easy to trap connection issues.
  • Slightly more complicated approach.
Single step to create a ServiceLayer and connect to data. 
  1. Use the appropriate static method on the ServiceLayer class for a particular service type.
  • Simple, can add layer in a single line of code.
  • Needs to catch connection exceptions.
  • Less flexible.

 
In summary, the first approach provides the developer with the flexibility to determine when a layer should be connected to a data source whereas the second provides easy to use convenience methods.

Working with ArcGIS Server services

When working with ArcGIS Server services consideration must be given to the fact that ArcGIS Explorer supports both a 2D and 3D display. The table below shows the support for each service type by display mode:
 
2D Display
3D Display
2D map service
Yes
Yes, but may not perform as well as in 2D
3D globe service
No, will not be displayed
Yes
Image service
Yes
Yes, but may not perform as well as in 2D

 
It is common for both a 2D map service and a 3D globe service to be published for the same data, primarily for performance reasons. If they have been given the same name, other than the map service having an _2D suffix, then ArcGIS Explorer is capable of automatically determining the appropriate service to use for the current display mode. For example, if you are in the 3D display and you use the GIS Services wizard to connect to ArcGIS Online (http://services.arcgisonline.com/ArcGIS/Services) you will see a number of services which have the same name but the _2D suffix. In these cases if you programmatically create a ServiceLayer for a globe service then add it to the 3D display, then you do not need to create another ServiceLayer when the display mode changes because ArcGIS Explorer will internally switch to using the map service of the same name.

Connecting to an ArcGIS Server 2D map service

To connect to an ArcGIS Server 2D map service both a URL to the service and the name of the map service must be supplied.  The following code example shows the first approach where a ServiceLayer is created, then manually connected to the service using the Connect method:
[C#] 
//Define the connection properties to the ESRI_ShadedRelief_World_2D map service
ServiceConnectionProperties connProps = new ServiceConnectionProperties
                                (ServiceType.MapServer, new Uri(
                                "http://services.arcgisonline.com/arcgis/services"), 
                                "ESRI_ShadedRelief_World_2D");
//Create a new ServiceLayer
ServiceLayer serverLayer = new ServiceLayer(connProps);
//Try to connect the layer to the service
bool connected = serverLayer.Connect();
//Check to see whether the connection was successful
if (connected)
{
    //Add the layer to the map.
   
        ESRI.ArcGISExplorer.Application.Application.ActiveMapDisplay.Map.ChildItems.Add(serverLayer);
}

else
{
    //Investigate connection issue.
    ConnectionStatus status = serverLayer.ConnectionStatus;
    if (status.HasError)
    {
        System.Diagnostics.Debug.Print(status.ErrorString);
    }
}
[VB.NET] 
'Define the connection properties to the ESRI_ShadedRelief_World_2D  map service
Dim connProps As ServiceConnectionProperties = New ServiceConnectionProperties(ServiceType.MapServer, _
                                               New Uri("http://services.arcgisonline.com/arcgis/services"), _
                                               "ESRI_ShadedRelief_World_2D ")
'Create a new ServiceLayer
Dim srviceLayer As ServiceLayer = New ServiceLayer(connProps)
'Try to connect the layer to the service
Dim connected As Boolean = srviceLayer.Connect()
'Check to see whether the connection was successful
If (connected) Then
    'Add the layer to the map.
    ESRI.ArcGISExplorer.Application.Application.ActiveMapDisplay.Map.ChildItems.Add(srviceLayer)
Else
    'Investigate connection issue.
    Dim status As ConnectionStatus = srviceLayer.ConnectionStatus
    If (status.HasError) Then
        System.Diagnostics.Debug.Print(status.ErrorString)
    End If
End If
The ServiceConnectionProperties class holds connection information relating to any of the supported service types by only setting the properties that are appropriate for a particular service type. For example, the connection to an ArcGIS Server map service can be defined using the Url and ServiceName properties. 
Tips:
  • When connecting to an ArcGIS Server map service, specify a MapServer ServiceType when creating the ServiceConnectionProperties object.
  • You can use the IsConnected property to check if a layer is connected to a service and the ConnectionStatus property to investigate connection problems.
  • If the service has security applied, specify the username and password using the SetUsernamePassword method.
  • For map services containing multiple layers you can use the ChildItems property to return a collection of ServiceChildLayer objects. See the Connecting to a WMS service section for an example of changing the visibility of a sub-layer.
The following code example shows the second approach where a ServiceLayer is created and connected to the underlying data source using the OpenMapServer convenience method:
[C#] 
try
{
    //Create and connect to the ESRI_ShadedRelief_World_2D map service 
    ServiceLayer sl = ServiceLayer.OpenMapServer(new Uri(
        "http://services.arcgisonline.com/arcgis/services"), 
        "ESRI_ShadedRelief_World_2D");
    //Add layer to the map
   
        ESRI.ArcGISExplorer.Application.Application.ActiveMapDisplay.Map.ChildItems.Add(sl);
}

catch (Exception ex)
{
    System.Diagnostics.Debug.Print(ex.Message);
}
[VB.NET] 
Try
'Create and connect to the GeoEye_Imagery_World_2D map service
Dim sl As ServiceLayer = ServiceLayer.OpenMapServer(New Uri("http://services.arcgisonline.com/arcgis/services"), _
                         "ESRI_ShadedRelief_World_2D")
'Add layer to the map
ESRI.ArcGISExplorer.Application.Application.ActiveMapDisplay.Map.ChildItems.Add(sl)
Catch ex As Exception
System.Diagnostics.Debug.Print(ex.Message)
End Try
Tips:
  • It's good practice to use a try/catch block when using this approach as a connection failure will result in an exception being thrown.
  • If the service has security applied, specify the username and password using the appropriate constructor overload.

Connecting to an ArcGIS Server 3D globe service

To connect to an ArcGIS Server 3D globe service you need to specify a URL to the service, the service name and a subservice name which is refers to an individual layer. The code example below demonstrates both connection approaches:
[C#] 
//Approach 1 - Instantiate a ServiceLayer and connect explicitly.
ServiceLayer serviceLayer1 = new ServiceLayer(new ServiceConnectionProperties
                                  (ServiceType.GlobeServer, new Uri(
                                  "http://services.arcgisonline.com/arcgis/services"), 
                                  "NASA_CloudCover_World", "Surface"));
bool connected = serviceLayer1.Connect();
//or use...
//Approach 2 - Instantiate and connect with a single method call.
ServiceLayer serviceLayer2 = ServiceLayer.OpenGlobeServer(new Uri(
    "http://services.arcgisonline.com/arcgis/services"), 
    "NASA_CloudCover_World", "Surface");
[VB.NET] 
'Approach 1 - Instantiate a ServiceLayer and connect explicitly.
Dim serviceLayer1 As ServiceLayer = New ServiceLayer(New ServiceConnectionProperties(ServiceType.GlobeServer, _
                                    New Uri("http://services.arcgisonline.com/arcgis/services"), _
                                    "NASA_CloudCover_World", "Surface"))
Dim connected As Boolean = serviceLayer1.Connect()
'or use...
'Approach 2 - Instantiate and connect with a single method call.
Dim serviceLayer2 As ServiceLayer = ServiceLayer.OpenGlobeServer(New Uri("http://services.arcgisonline.com/arcgis/services"), _
                                    "NASA_CloudCover_World", "Surface")
Tip: When using the first approach to connect to an ArcGIS Server globe service, specify a GlobeServer ServiceType when creating the ServiceConnectionProperties object.

Connecting to an ArcGIS Server image service

ArcGIS Server image services can be viewed in both the 2D or in the 3D display, although the performance is likely to be better in the 2D display mode.  To connect to an ArcGIS image service you need to specify a URL to the service and the service name as shown in the code example below:
[C#] 
ServiceLayer imgLayer1 = new ServiceLayer(new ServiceConnectionProperties
                                  (ServiceType.ImageServer, new Uri(@
                                  "http://sampleserver3.arcgisonline.com/ArcGIS/services"), @
                                  "Portland\CascadeLandsat"));
bool connected = imgLayer1.Connect();
// or use...
// Approach 2 - Instantiate and connect with a single method call.
ServiceLayer imgLayer2 = ServiceLayer.OpenImageServer(new Uri(@
    "http://sampleserver3.arcgisonline.com/ArcGIS/services"), @
    "Portland\CascadeLandsat");
[VB.NET] 
Dim imgLayer1 As ServiceLayer = New ServiceLayer(New ServiceConnectionProperties(ServiceType.ImageServer, _
                                New Uri("http://sampleserver3.arcgisonline.com/ArcGIS/services"), "Portland\CascadeLandsat"))
Dim connected As Boolean = imgLayer1.Connect()
' or use...
' Approach 2 - Instantiate and connect with a single method call.
Dim imgLayer2 As ServiceLayer = ServiceLayer.OpenImageServer(New Uri("http://sampleserver3.arcgisonline.com/ArcGIS/services"), "Portland\CascadeLandsat")

Connecting to an ArcIMS map service

ArcIMS map services can be viewed in both the 2D or in the 3D display, although the performance is likely to be better in the 2D display mode.  To connect to an ArcIMS map service you need to specify a URL to the service and the map service name as shown in the code example below:
[C#] 
//Approach 1 - Instantiate a ServiceLayer and connect explicitly.
ServiceLayer imsLayer1 = new ServiceLayer(new ServiceConnectionProperties
    (ServiceType.Ims, new Uri("http://www.geographynetwork.com"), "ESRI_Pop"));
bool connected = imsLayer1.Connect();
//or use...
//Approach 2 - Instantiate and connect with a single method call.
ServiceLayer imsLayer2 = ServiceLayer.OpenIms(new Uri(
    "http://www.geographynetwork.com"), "WWF_Threat");
[VB.NET] 
'Approach 1 - Instantiate a ServiceLayer and connect explicitly.
Dim imsLayer1 As ServiceLayer = New ServiceLayer(New ServiceConnectionProperties(ServiceType.Ims, New Uri("http://www.geographynetwork.com"), "ESRI_Pop"))
Dim connected As Boolean = imsLayer1.Connect()
'or use...
'Approach 2 - Instantiate and connect with a single method call.
Dim imsLayer2 As ServiceLayer = ServiceLayer.OpenIms(New Uri("http://www.geographynetwork.com"), "ESRI_Pop")
Tip: When using the first approach to connect to an ArcIMS map service, specify an Ims ServiceType when creating the ServiceConnectionProperties object.

Connecting to a Microsoft Bing Maps service

The ArcGIS Explorer API makes it easy for you connect to the Microsoft Bing Maps service as you only need to specify the service type as shown below in the code example: 
[C#] 
//Approach 1 - Instantiate a ServiceLayer and connect explicitly.
ServiceLayer bingLayer1 = new ServiceLayer(new ServiceConnectionProperties
    (BingMapsService.Road));
bool connected = bingLayer1.Connect();
//or use...
//Approach 2 - Instantiate and connect with a single method call.
ServiceLayer bingLayer2 = ServiceLayer.OpenBingMaps(BingMapsService.Hybrid);
[VB.NET] 
'Approach 1 - Instantiate a ServiceLayer and connect explicitly.
Dim bingLayer1 As ServiceLayer = New ServiceLayer(New ServiceConnectionProperties(BingMapsService.Road))
Dim connected As Boolean = bingLayer1.Connect()
'or use...
'Approach 2 - Instantiate and connect with a single method call.
Dim bingLayer2 As ServiceLayer = ServiceLayer.OpenBingMaps(BingMapsService.Hybrid)

Connecting to the OpenStreetMap service

The ArcGIS Explorer API makes it easy for you connect to the OpenStreetMap service (www.OpenStreetMap.org) as you only need to specify the service type or use the static OpenOpenStreetMap method as shown below in the code example:
[C#] 
//Approach 1 - Instantiate a ServiceLayer and connect explicitly.
ServiceLayer openStreetMapLayer1 = new ServiceLayer(new
    ServiceConnectionProperties(ServiceType.OpenStreetMap));
bool connected = openStreetMapLayer1.Connect();
//or use...
//Approach 2 - Instantiate and connect with a single method call.
ServiceLayer openStreetMapLayer2 = ServiceLayer.OpenOpenStreetMap();
[VB.NET] 
'Approach 1 - Instantiate a ServiceLayer and connect explicitly.
Dim openStreetMapLayer1 As ServiceLayer = New ServiceLayer(New ServiceConnectionProperties(ServiceType.OpenStreetMap))
Dim connected As Boolean = openStreetMapLayer1.Connect()
'or use...
'Approach 2 - Instantiate and connect with a single method call.
Dim openStreetMapLayer2 As ServiceLayer = ServiceLayer.OpenOpenStreetMap()

Connecting to a WMS service

WMS map services can be viewed in both the 2D or in the 3D display, although the performance is likely to be better in the 2D display mode.  To access all the layers in a WMS map service you need to specify a URL to the service and the map service name.  Optionally to connect to connect to an individual layer within the service you can additionally specify a subservice name, see code example below:
[C#] 
//Approach 1 - Instantiate a ServiceLayer and connect explicitly. 
//Example 1 - connect to an individual layer in the named service
ServiceLayer wmsLayer1 = new ServiceLayer(new ServiceConnectionProperties
                          (ServiceType.Wms, new Uri("http://nmcatalog.usgs.gov/catalogwms/base"), 
                          "The National Map", "BOUNARIES"));
bool connected1 = wmsLayer1.Connect();
//Example 2 - Connect to the named WMS service which includes multiple layers
ServiceLayer wmsLayer2 = new ServiceLayer(new ServiceConnectionProperties
                          (ServiceType.Wms, new Uri("http://nmcatalog.usgs.gov/catalogwms/base"), 
                          "The National Map"));
bool connected2 = wmsLayer2.Connect();
[VB.NET] 
'Approach 1 - Instantiate a ServiceLayer and connect explicitly.
'Example 1 - connect to an individual layer in the named service
Dim wmsLayer1 As ServiceLayer = New ServiceLayer(New ServiceConnectionProperties(ServiceType.Wms, New Uri("http://nmcatalog.usgs.gov/catalogwms/base"), "The National Map", "BOUNARIES"))
Dim connected1 As Boolean = wmsLayer1.Connect()
'Example 2 - Connect to the named WMS service which includes multiple layers
Dim wmsLayer2 As ServiceLayer = New ServiceLayer(New ServiceConnectionProperties(ServiceType.Wms, New Uri("http://nmcatalog.usgs.gov/catalogwms/base"), "The National Map"))
Dim connected2 As Boolean = wmsLayer2.Connect()
Tip: When using the first approach to connect to a WMS map service, specify a WMS ServiceType when creating the ServiceConnectionProperties object.
Depending on the configuration of the map service, it may be possible to access the individual layers within a map service.  Access to these layers can be checked in the application by right-clicking on a service layer, choosing 'Properties' and then selecting 'sub-layers' from the dialog window. The programmatic equivalent of this is to return the ServiceChildLayer objects from the ServiceLayer using the ChildItems property.  In the code example below the sub-layers of 'The National Map' ServiceLayer are accessed and their visibility set:
[C#] 
//Access the individual layers and set the Transportation layer not to be visible
foreach (ServiceChildLayer lyr in wmsLayer2.ChildItems)
{
    if (lyr.Name == "TRANSPORTATION")
    {
        lyr.Visible = false;
    }
    else
    {
        lyr.Visible = true;
    }
}
[VB.NET] 
'Access the individual layers and set the Transportation layer not to be visible
For Each lyr As ServiceChildLayer In wmsLayer2.ChildItems
    If lyr.Name = "TRANSPORTATION" Then
        lyr.Visible = False
    Else
        lyr.Visible = True
    End If
Next

Working with the GeoRssLayer class

Connecting to a GeoRSS feed

To connect to a GeoRss feed you simply need to specify a URL and use one of the two connection approaches as shown below:
[C#] 
//Approach 1 - Instantiate a GeoRssLayer and connect explicitly.
GeoRssLayer rssLayer1 = new GeoRssLayer(new Uri(
                                        "http://earthquake.usgs.gov/eqcenter/catalogs/eqs7day-M5.xml"), Symbol.Marker.Placemark.Star);
bool connected = rssLayer1.Connect();
//or use...
//Approach 2 - Instantiate and connect with a single method call.
GeoRssLayer rssLayer2 = GeoRssLayer.Open(new Uri(
    "http://feeds2.feedburner.com/RsoeEdis-EmergencyAndDisasterInformation?format=xml"));
[VB.NET] 
'Approach 1 - Instantiate a GeoRssLayer and connect explicitly.
Dim rssLayer1 As GeoRssLayer = New GeoRssLayer(New Uri("http://earthquake.usgs.gov/eqcenter/catalogs/eqs7day-M5.xml"), Symbol.Marker.Placemark.Star)
Dim connected As Boolean = rssLayer1.Connect()
'or use...
'Approach 2 - Instantiate and connect with a single method call.
Dim rssLayer2 As GeoRssLayer = GeoRssLayer.Open(New Uri("http://feeds2.feedburner.com/RsoeEdis-EmergencyAndDisasterInformation?format=xml"))
Tip: Use the RefreshInterval property to determine how often the layer will check the feed for updates.