Represents a layer based on spatial data provided by an ArcGIS Server (map, globe or image), ArcIMS, WMS or Bing maps service.

Namespace:  ESRI.ArcGISExplorer.Mapping

Assembly:  ESRI.ArcGISExplorer (in ESRI.ArcGISExplorer.dll) Version: 2.0.0.1500 (2.0.0.1500)

Syntax

C#
public sealed class ServiceLayer : Layer, 
	IMapItemParent
Visual Basic (Declaration)
Public NotInheritable Class ServiceLayer _
	Inherits Layer _
	Implements IMapItemParent

Remarks

The layer classes are a subset of MapItems that reference geographic data. A ServiceLayer enables spatial data provided by a service to be added to the map and displayed by the ArcGIS Explorer application. Typically service data consists of georeferenced images generated by a map service using spatial data. Client applications, like ArcGIS Explorer, can request images from a map service.

When a connected ServiceLayer is added to the map, the related data is requested from the service and draped over the basemap. In the case of ArcGIS Server 3D globe services the service data is used as an elevation source in 3D. The layer must be in a connected state before data can be displayed. There are two ways to connect a layer to data:

1. Instantiate a ServiceLayer and connect explicitly.

  • Create a new ServiceLayer, populate the ServiceConnectionProperties property and call ServiceLayer.Connect()
  • A constructor is also provided to allow you to specify the service connection properties when you instantiate a layer. If the properties specified are incorrect, the service layer will remain disconnected but no exception will be thrown; use the ConnectionStatus property to diagnose why a layer could not be connected.
  • The ServiceConnectionProperties class encapsulates connection information for several types of service: ArcGIS Server 2D, and ArcGIS Server 3D, ArcGIS Sever image service, ArcIMS (Internet Map Server), Web Map Service (WMS) and Bing maps. There are parameterized constructors that enable you to instantiate a ServiceConnectionProperties object for each type of service.

2. Instantiate and connect with a single method call.

  • Use the static methods prefixed with "Open" to both instantiate a ServiceLayer and connect to its underlying service with a single method call.
  • There are several static methods that are named according to the type of data source you are referencing: OpenMapServer (ArcGIS Server 2D), OpenGlobeServer (ArcGIS Server 3D), OpenImageServer (ArcGIS Server image service), OpenIMS, OpenWMS, OpenBingMaps.
  • The parameters for each method indicate the connection information required when connecting to the type of service, for example the OpenMapServer method requires the URL to an ArcGIS Server instance and the name of the service.
  • If successful the Open methods return a connected ServiceLayer object. In contrast to the Connect method, an exception will be thrown if the connection parameters specified are incorrect. Therefore it is a good idea to wrap a call to the Open method with a try... catch block if you are unsure of the data source to which you are connecting.
  • The connection information you specify will be stored in the ServiceLayer.ServiceConnectionProperties property; the ServiceConnectionProperties class encapsulates connection information for the service types: ArcGIS Server 2D, 3D and image, ArcIMS (Internet Map Server), Web Map Service (WMS) and Bing maps.

If a ServiceLayer is added to the map in an unconnected state, no data will be displayed. The layer will still appear in the ArcGIS Explorer contents window with an exclamation mark to indicate the layer is not connected. Once connected, you can access data dependent properties such as the geographical extent of the layer.

Services are often published with one or more layers of information. Each constituent layer is represented by a ServiceChildLayer object. Although the ServiceLayer.ChildItems property is a MapItemCollection, it will always return a collection of ServiceChildLayer objects and you cannot add to the collection.

Examples

The code below demonstrates two different approaches to creating a ServiceLayer for an ArcGIS Server globe service. In the first example a ServiceLayer object is created using the connection information specified in a ServiceConnectionProperties object, then connected manually using the Connect method. In contrast, the second example shows how to both create and connect a ServiceLayer in a single call using the static OpenGlobeServer method.
CopyC#
{
  //Example 1 - Instantiate a ServiceLayer and connect explicitly.
  //**************************************************************

  //Define the connection properties to the Surface subservice in the NASA_Cloudcover_World globe service
  ServiceConnectionProperties connProps = new ServiceConnectionProperties(ServiceType.GlobeServer,
                                               new Uri("http://services.arcgisonline.com/arcgis/services"),
                                               "NASA_Cloudcover_World",
                                               "Surface");

  //Create a new ServiceLayer
  ServiceLayer serviceLayer1 = new ServiceLayer(connProps);

  //Set the layer name
  serviceLayer1.Name = "Clouds 1";

  //Try to connect the layer to the service
  bool connected = serviceLayer1.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(serviceLayer1);
  }
  else
  {
    //Investigate connection issue.
    ConnectionStatus status = serviceLayer1.ConnectionStatus;
    if (status.HasError)
    {
      System.Diagnostics.Debug.Print(status.ErrorString);
    }
  }

  //Example 2 - Instantiate and connect with a single method call.
  //**************************************************************
  try
  {
    //Create a new service layer and connect it to the Surface subservice of the NASA_Cloudcover_World globe service
    ServiceLayer serviceLayer2 = ServiceLayer.OpenGlobeServer(new Uri("http://services.arcgisonline.com/arcgis/services"),
                                                                                     "NASA_Cloudcover_World", "Surface");

    //Set the layer name
    serviceLayer2.Name = "Clouds 2";

    //Add the layer to the map
    ESRI.ArcGISExplorer.Application.Application.ActiveMapDisplay.Map.ChildItems.Add(serviceLayer2);
  }
  catch (ESRI.ArcGISExplorer.ConnectionException ex)
  {
    System.Diagnostics.Debug.Print(ex.Message);
  }
}
CopyVB.NET
'Example 1 - Instantiate a ServiceLayer and connect explicitly.
'**************************************************************


'Define the connection properties to the Surface subservice in the NASA_Cloudcover_World globe service
Dim connProps As ServiceConnectionProperties = New ServiceConnectionProperties(ServiceType.GlobeServer, _
                                              New Uri("http://services.arcgisonline.com/arcgis/services"), _
                                              "NASA_Cloudcover_World", "Surface")

'Create a new ServiceLayer
Dim serviceLayer1 As ServiceLayer = New ServiceLayer(connProps)

'Set the layer name
serviceLayer1.Name = "Clouds 1"

'Try to connect the layer to the service
Dim connected As Boolean = serviceLayer1.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(serviceLayer1)
Else
  'Investigate connection issue.
  Dim status As ConnectionStatus = serviceLayer1.ConnectionStatus
  If status.HasError Then
    System.Diagnostics.Debug.Print(status.ErrorString)
  End If
End If

'Example 2 - Instantiate and connect with a single method call.
'**************************************************************
Try
  'Create a new service layer and connect it to the Surface subservice of the NASA_Cloudcover_World globe service
  Dim serviceLayer2 As ServiceLayer = ServiceLayer.OpenGlobeServer(New Uri("http://services.arcgisonline.com/arcgis/services"), _
                                                                                     "NASA_Cloudcover_World", "Surface")

  'Set the layer name
  serviceLayer2.Name = "Clouds 2"

  'Add the layer to the map
  ESRI.ArcGISExplorer.Application.Application.ActiveMapDisplay.Map.ChildItems.Add(serviceLayer2)
Catch ex As ESRI.ArcGISExplorer.ConnectionException
  System.Diagnostics.Debug.Print(ex.Message)
End Try

Inheritance Hierarchy

System..::.Object

  ESRI.ArcGISExplorer.Mapping..::.MapItem

    ESRI.ArcGISExplorer.Mapping..::.Layer

      ESRI.ArcGISExplorer.Mapping..::.ServiceLayer

See Also