Represents an item of map content referencing geographic data held in storage or provided by a service.

Namespace: ESRI.ArcGISExplorer.Mapping

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

Syntax

C#
public class Layer : MapItem

Visual Basic (Declaration)
Public Class Layer _ Inherits MapItem

Remarks

The Layer classes are a subset of MapItems that reference geographic data. When a Layer is added to the map, the related data is draped over the basemap or, if applicable, used as a terrain elevation source in 3D. Geographic data can be stored in a variety of formats typically in a file or geodatabase.

Layer is an abstract class that defines properties and methods shared by all types of Layer class which give you control over:

connecting to and disconnecting from an underlying data source
the visibility and transparency of the Layer in the map
the Layer refresh interval (how often the Layer accesses the underlying data to check for changes)
the caching policy for the Layer (and the ability to clear the current cache)
the behavior of the Layer in 3D display mode

In order to support multiple data formats there are several different Layer types. Each Layer type references a different type of data and has a single property that stores connection details for the data source. The Layer types also provide parameterized constructors that enable you to specify the connection information when you instantiate a Layer. Using the constructors will not implicitly connect the Layer.

Layer Type	Data Source Property	Data Source Description
FeatureLayer	FeatureLayer.DataSourceProperties	Vector data held in an ESRI shapefile or geodatabase
RasterLayer	RasterLayer.DataSourceProperties	Raster data held in a georeferenced image file or ESRI geodatabase
ServiceLayer	ServiceLayer.ServiceConnectionProperties	Data provided by a service (ArcGIS Server 2D and 3D, ArcIMS, WMS or Bing maps)
GeoRssLayer	GeoRssLayer.Url	Data provided by a GeoRSS feed
KmlLayer	KmlLayer.Path	Data held in a KML or KMZ file.
PackageLayer	PackageLayer.Path	Data held in layer package or layer file

In order for the data to be displayed on a map, the Layer must be in a connected state. There are two ways to connect a Layer to data:

1. Instantiate a Layer and connect explicitly.

Create a new derived Layer type, populate the data source properties and call Layer.Connect()
Each Layer type provides parameterized constructors to allow you to specify the connection information when you instantiate a Layer.
If the connection properties specified are incorrect, the Layer will remain disconnected but no exception will be thrown; use the Layer.ConnectionStatus property to diagnose why the Layer could not be connected.

2. Instantiate and connect with a single method call.

Every derived Layer type has static methods prefixed with "Open". These methods are provided for convenience and allow you to both instantiate a Layer and connect to its underlying data with a single method call.
The Open methods take Layer connection parameters, and if successful return a connected Layer object.
In contrast to the Connect method, the Open methods will throw an exception 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.

If a Layer 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 a Layer has been connected, you can access the coordinate system and geographical extent for the layers underlying data.

Examples

The code below illustrates how to populate the data source properties for each derived Layer type and attempts to connect to the underlying data source. If the connection is successful, the Layer is added to a map. If unsuccessful, the connection error is logged.

CopyC#

using System;
using System.Collections.Generic;
using System.Text;
using Microsoft.VisualStudio.TestTools.UnitTesting;

// Import these namespaces to highlight Application and Point name clashes.
using System.Windows.Forms;
using System.Drawing;

// Required additional using statements.
using ESRI.ArcGISExplorer.Data;
using ESRI.ArcGISExplorer.Mapping;

namespace ExamplesCS.Mapping
{
  class LayerConnectionExample
  {
    private void CheckConnectionStatus(Layer layer)
    {
      //Investigate connection issue using the layer connection status property
      ConnectionStatus status = layer.ConnectionStatus;
      if (status.HasError)
      {
        //Print a human-readable error message using the connection status
        System.Diagnostics.Debug.Print("Error message: " + status.ErrorString);

        //If there was an exception print out the call stack
        if(status.ErrorException != null)
          System.Diagnostics.Debug.Print("Call stack: " + status.ErrorException.StackTrace);
      }
    }

    public void Layer_Connections()
    {
      Map map = ESRI.ArcGISExplorer.Application.Application.ActiveMapDisplay.Map;

      //FeatureLayer: vector data held in an ESRI shapefile or geodatabase
      //Create a DataSourceProperties object that holds the connection information to the feature class
      DataSourceProperties featureLayerDataSourceProps = new DataSourceProperties(@"C:\Data\Forestry.gdb", "road_hazards");
      //Create a feature layer
      FeatureLayer featureLayer = new FeatureLayer(featureLayerDataSourceProps);
      //Connect the layer to the feature class
      bool isConnected = featureLayer.Connect();

      if (isConnected)
        //Add the layer to the map
        map.ChildItems.Add(featureLayer);
      else
        CheckConnectionStatus(featureLayer);


      //RasterLayer: raster data held in a georeferenced image file or ESRI geodatabase
      //Create a DataSourceProperties object that holds the connection information to the raster data source
      DataSourceProperties rasterLayerDataSourceProps = new DataSourceProperties(@"C:\Data\Scotland.gdb", "NORTHGORMS_HO");
      //Create a raster layer
      RasterLayer rasterLayer = new RasterLayer(rasterLayerDataSourceProps);
      //Connect the layer to the raster data source
      isConnected = rasterLayer.Connect();
      if (isConnected)
        map.ChildItems.Add(rasterLayer);
      else
        CheckConnectionStatus(rasterLayer);


      //ServiceLayer: data provided by a service (ArcGIS Server, ArcIMS, WMS, Virtual Earth)
      //Create a URI object for ArcGIS Online
      Uri serverUri = new Uri("http://services.arcgisonline.com/Server/Services");
      //Define service name for Map Service
      string serviceName = "ESRI_Imagery_World_2D";
      //Create a ServiceConnectionProperties object that holds connection information for the service
      ServiceConnectionProperties serviceLayerConnectionProps = new ServiceConnectionProperties(ServiceType.MapServer, serverUri, serviceName);
      ServiceLayer serviceLayer = new ServiceLayer(serviceLayerConnectionProps);
      isConnected = serviceLayer.Connect();
      if (isConnected)
        map.ChildItems.Add(serviceLayer);
      else
        CheckConnectionStatus(serviceLayer);


      //GeoRssLayer: data provided by a GeoRSS feed
      Uri geoRssUri = new Uri("http://feeds.bbc.co.uk/weather/feeds/rss/5day/world/6697.xml");
      GeoRssLayer geoRssLayer = new GeoRssLayer(geoRssUri);
      isConnected = geoRssLayer.Connect();
      if (isConnected)
        map.ChildItems.Add(geoRssLayer);
      else
        CheckConnectionStatus(geoRssLayer);


      //KmlLayer: data held in a KML file
      string pathToKmlFile = @"C:\Data\KmlExample.kml";
      KmlLayer kmlLayer = new KmlLayer(pathToKmlFile);
      isConnected = kmlLayer.Connect();
      if (isConnected)
        map.ChildItems.Add(kmlLayer);
      else
        CheckConnectionStatus(kmlLayer);


      // PackageLayer: data held in layer package or layer file
      string pathToPackageLayer = @"C:\Data\LpkExample.lpk";
      PackageLayer packageLayer = new PackageLayer(pathToPackageLayer);
      isConnected = packageLayer.Connect();
      if (isConnected)
        map.ChildItems.Add(packageLayer);
      else
        CheckConnectionStatus(packageLayer);
    }

  }



}

CopyVB.NET

Imports System
Imports System.Collections.Generic
Imports System.Text
Imports Microsoft.VisualStudio.TestTools.UnitTesting

' Import these namespaces to highlight Application and Point name clashes.
Imports System.Windows.Forms
Imports System.Drawing

' Required additional using statements.
Imports ESRI.ArcGISExplorer.Data
Imports ESRI.ArcGISExplorer.Mapping


Class LayerConnectionExample
    Private Sub CheckConnectionStatus(ByVal layer As Layer)
        'Investigate connection issue using the layer connection status property
        Dim status As ConnectionStatus = layer.ConnectionStatus
        If status.HasError Then
            'Print a human-readable error message using the connection status
            System.Diagnostics.Debug.Print("Error message: " + status.ErrorString)

            'If there was an exception print out the call stack 
            If status.ErrorException IsNot Nothing Then
                System.Diagnostics.Debug.Print("Call stack: " + status.ErrorException.StackTrace)
            End If
        End If
    End Sub

    Public Sub Layer_Connections()
        Dim map As Map = ESRI.ArcGISExplorer.Application.Application.ActiveMapDisplay.Map

        'FeatureLayer: vector data held in an ESRI shapefile or geodatabase
        'Create a DataSourceProperties object that holds the connection information to the feature class
        Dim featureLayerDataSourceProps As New DataSourceProperties("C:\Data\Forestry.gdb", "road_hazards")
        'Create a feature layer
        Dim featureLayer As New FeatureLayer(featureLayerDataSourceProps)
        'Connect the layer to the feature class
        Dim isConnected As Boolean = featureLayer.Connect()

        If isConnected Then
            map.ChildItems.Add(featureLayer)
        Else
            CheckConnectionStatus(featureLayer)
            'Add the layer to the map
        End If


        'RasterLayer: raster data held in a georeferenced image file or ESRI geodatabase
        'Create a DataSourceProperties object that holds the connection information to the raster data source
        Dim rasterLayerDataSourceProps As New DataSourceProperties("C:\Data\Scotland.gdb", "NORTHGORMS_HO")
        'Create a raster layer
        Dim rasterLayer As New RasterLayer(rasterLayerDataSourceProps)
        'Connect the layer to the raster data source
        isConnected = rasterLayer.Connect()
        If isConnected Then
            map.ChildItems.Add(rasterLayer)
        Else
            CheckConnectionStatus(rasterLayer)
        End If


        'ServiceLayer: data provided by a service (ArcGIS Server, ArcIMS, WMS, Virtual Earth)
        'Create a URI object for ArcGIS Online
        Dim serverUri As New Uri("http://services.arcgisonline.com/Server/Services")
        'Define service name for Map Service
        Dim serviceName As String = "ESRI_Imagery_World_2D"
        'Create a ServiceConnectionProperties object that holds connection information for the service
        Dim serviceLayerConnectionProps As New ServiceConnectionProperties(ServiceType.MapServer, serverUri, serviceName)
        Dim serviceLayer As New ServiceLayer(serviceLayerConnectionProps)
        isConnected = serviceLayer.Connect()
        If isConnected Then
            map.ChildItems.Add(serviceLayer)
        Else
            CheckConnectionStatus(serviceLayer)
        End If


        'GeoRssLayer: data provided by a GeoRSS feed
        Dim geoRssUri As New Uri("http://feeds.bbc.co.uk/weather/feeds/rss/5day/world/6697.xml")
        Dim geoRssLayer As New GeoRssLayer(geoRssUri)
        isConnected = geoRssLayer.Connect()
        If isConnected Then
            map.ChildItems.Add(geoRssLayer)
        Else
            CheckConnectionStatus(geoRssLayer)
        End If


        'KmlLayer: data held in a KML file
        Dim pathToKmlFile As String = "C:\Data\KmlExample.kml"
        Dim kmlLayer As New KmlLayer(pathToKmlFile)
        isConnected = kmlLayer.Connect()
        If isConnected Then
            map.ChildItems.Add(kmlLayer)
        Else
            CheckConnectionStatus(kmlLayer)
        End If


        ' PackageLayer: data held in layer package or layer file
        Dim pathToPackageLayer As String = "C:\Data\LpkExample.lpk"
        Dim packageLayer As New PackageLayer(pathToPackageLayer)
        isConnected = packageLayer.Connect()
        If isConnected Then
            map.ChildItems.Add(packageLayer)
        Else
            CheckConnectionStatus(packageLayer)
        End If
    End Sub

End Class

Examples

The code below shows how to use the static Open methods to return a connected Layer.

CopyC#

//The static Open methods will return an instance of a concrete layer type.

//If the connection information specified is incorrect, an exception will be thrown, therefore
//use a try... catch block to handle the exception.
try
{
  //Open a FeatureLayer based on a File Geodatabase feature class
  FeatureLayer featureLayer = FeatureLayer.OpenFileGeodatabaseTable(@"C:\Data\Forestry.gdb", "road_hazards");
}
catch (ESRI.ArcGISExplorer.ConnectionException ex)
{
  System.Diagnostics.Debug.Print(ex.Message);
}


try
{
  //Open a RasterLayer based on a File Geodatabase raster
  RasterLayer rasterLayer = RasterLayer.OpenFileGeodatabaseRaster(@"C:\Data\Scotland.gdb", "NORTHGORMS_HO");
}
catch (ESRI.ArcGISExplorer.ConnectionException ex)
{
  System.Diagnostics.Debug.Print(ex.Message);
}


try
{
  //Open a ServiceLayer based on an ArcGIS Server map service
  ServiceLayer serviceLayer = ServiceLayer.OpenMapServer(new Uri("http://services.arcgisonline.com/Server/Services"), 
                                                                                "ESRI_Imagery_World_2D");
}
catch (ESRI.ArcGISExplorer.ConnectionException ex)
{
  System.Diagnostics.Debug.Print(ex.Message);
}


try
{
  //Open a GeoRssLayer based on a GeoRSS feed
  GeoRssLayer geoRssLayer = GeoRssLayer.Open(new Uri("http://feeds.bbc.co.uk/weather/feeds/rss/5day/world/6697.xml"));
}
catch (ESRI.ArcGISExplorer.ConnectionException ex)
{
  System.Diagnostics.Debug.Print(ex.Message);
}


try
{
  //Open a KmlLayer based on a KML file
  KmlLayer kmlLayer = KmlLayer.Open(@"C:\Data\KmlExample.kml");
}
catch (ESRI.ArcGISExplorer.ConnectionException ex)
{
  System.Diagnostics.Debug.Print(ex.Message);
}


try
{
  //Open a PackageLayer based on a layer package file
  PackageLayer packageLayer = PackageLayer.Open(@"C:\Data\LpkExample.lpk");
}
catch (ESRI.ArcGISExplorer.ConnectionException ex)
{
  System.Diagnostics.Debug.Print(ex.Message);
}

CopyVB.NET

'The static Open methods will return an instance of a concrete layer type.


'If the connection information specified is incorrect, an exception will be thrown, therefore
'use a try... catch block to handle the exception.
Try
  'Open a FeatureLayer based on a File Geodatabase feature class
  Dim featureLayer As FeatureLayer = featureLayer.OpenFileGeodatabaseTable("C:\Data\Forestry.gdb", "road_hazards")
Catch ex As ESRI.ArcGISExplorer.ConnectionException
  System.Diagnostics.Debug.Print(ex.Message)
End Try


Try
  'Open a RasterLayer based on a File Geodatabase raster
  Dim rasterLayer As RasterLayer = rasterLayer.OpenFileGeodatabaseRaster("C:\Data\Scotland.gdb", "NORTHGORMS_HO")
Catch ex As ESRI.ArcGISExplorer.ConnectionException
  System.Diagnostics.Debug.Print(ex.Message)
End Try


Try
  'Open a ServiceLayer based on an ArcGIS Server map service
  Dim serviceLayer As ServiceLayer = serviceLayer.OpenMapServer(New Uri("http://services.arcgisonline.com/Server/Services"), "ESRI_Imagery_World_2D")
Catch ex As ESRI.ArcGISExplorer.ConnectionException
  System.Diagnostics.Debug.Print(ex.Message)
End Try


Try
  'Open a GeoRssLayer based on a GeoRSS feed
  Dim geoRssLayer As GeoRssLayer = geoRssLayer.Open(New Uri("http://feeds.bbc.co.uk/weather/feeds/rss/5day/world/6697.xml"))
Catch ex As ESRI.ArcGISExplorer.ConnectionException
  System.Diagnostics.Debug.Print(ex.Message)
End Try


Try
  'Open a KmlLayer based on a KML file
  Dim kmlLayer As KmlLayer = kmlLayer.Open("C:\Data\KmlExample.kml")
Catch ex As ESRI.ArcGISExplorer.ConnectionException
  System.Diagnostics.Debug.Print(ex.Message)
End Try


Try
  'Open a PackageLayer based on a layer package file
  Dim packageLayer As PackageLayer = packageLayer.Open("C:\Data\LpkExample.lpk")
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..::.FeatureLayer

      ESRI.ArcGISExplorer.Mapping..::.GeoRssLayer

      ESRI.ArcGISExplorer.Mapping..::.KmlLayer

      ESRI.ArcGISExplorer.Mapping..::.PackageLayer

      ESRI.ArcGISExplorer.Mapping..::.RasterLayer

      ESRI.ArcGISExplorer.Mapping..::.ServiceLayer

Syntax

Remarks

Examples

Examples

Inheritance Hierarchy

See Also