Adding layers

The ArcGIS API for Silverlight provides a set of predefined map layer types to add to a Map control. Predefined layer types include the following:

• Map service layers, such as ArcGIS Server and Bing Maps
• Feature layers, which represent graphic features in layers hosted by an ArcGIS Server map service
• Graphics layers for native graphic feature display
• Element layers to include Silverlight user interface (UI) elements and media on a map

Layers are added to a Map control's layer collection via the Layers property. The following are items to consider when adding layers to a map:

• Layers are drawn bottom to top, so the first layer in the layer collection is drawn first (on the bottom) and each subsequent layer is drawn on top of it, in the order listed. See the following diagram:
• The first layer with a valid spatial reference defines the spatial reference for the map.

Map service layers

Map service layers come in two varieties, tiled and dynamic. Tiled service layers provide access to a set of map image tiles organized into predefined scale levels and hosted on a remote server. Dynamic service layers provide access to map and image services that generate map images on-the-fly.

The following table lists the map service layer types included with the ArcGIS API for Silverlight and descriptions. Use the layer types to add layers to your map.

Service host	Map service layer type	Description
ArcGIS Server	ArcGISTiledMapServiceLayer	ArcGIS Server cached map service hosting a set of map image tiles.
ArcGIS Server	ArcGISDynamicMapServiceLayer	ArcGIS Server noncached map service that generates map images on-the-fly. Noncached map services provide dynamic access to both vector and raster data sources.
ArcGIS Server	ArcGISImageServiceLayer	ArcGIS Server image service that generates map images on-the-fly. Image services provide dynamic access to raster data sources.
Bing Maps	TileLayer	Bing Maps map imagery layer. It provides access to precached roads and aerial imagery.

Feature layers

Feature layers represent layers that contain features (geometry and attributes) and are hosted by a service. The FeatureLayer type provides a convenient class to reference a feature layer in an ArcGIS Server map service. The Url property of FeatureLayer defines the HTTP endpoint to a service that provides access to the layer. Graphic features are retrieved from the service and rendered on the client using graphic capabilities native to the ArcGIS API for Silverlight. See Feature layers for more information on creating and defining feature layer properties.

How to add an ArcGIS Server map service layer

The following example shows the XAML of the map in a Silverlight application that contains an ArcGIS API for Silverlight Map control with three different ArcGIS Server map service layers. See the Creating a map topic for information on how to create a map and reference its layer collection. All ArcGIS Server layer types in the ArcGIS API for Silverlight are included in the ESRI.ArcGIS.Client.dll in the ESRI.ArcGIS.Client namespace.

Note:

The following code requires an XML namespace reference to the ESRI.ArcGIS.Client namespace in the assembly of the same name:

<esri:Map x:Name="MyMap" >
  <esri:Map.Layers>
    <esri:ArcGISTiledMapServiceLayer ID="StreetMapLayer" 
      Url="http://server.arcgisonline.com/ArcGIS/rest/services/ESRI_StreetMap_World_2D/MapServer" />
    <esri:ArcGISImageServiceLayer ID="SanFranciscoImageLayer"
      Url="http://serverapps.esri.com/ArcGIS/rest/services/SamplesNET/SanFranciscoImage/MapServer" />
    <esri:ArcGISDynamicMapServiceLayer ID="CaliforniaLayer" 
      Url="http://serverapps.esri.com/ArcGIS/rest/services/California/MapServer" />
  </esri:Map.Layers>
</esri:Map>

1. Add an ArcGIS Server map service layer. In the previous example code, ArcGISTiledMapServiceLayer, ArcGISImageServiceLayer, and ArcGISDynamicMapServiceLayer elements are added to the map's layer collection.
2. Add the ID attribute to the layer element. Define a unique value to identify the layer.
3. Add the Url attribute to the layer element. Define a URL to the appropriate service type. Use the Services Directory application to navigate to an ArcGIS Server site and determine the service type (map or image). If adding a map service, determine if it has a cache. Cached map services will contain tile information.

Note:

• If the map service is secured, you might need to generate a token and add it to the layer via the Token attribute. See the Secure services topic for more information.
• The map's SnapToLevels property determines if the map will be rendered only at predefined scale levels. By default, Map.SnapToLevels is false, which allows the Map control to render map tiles between scale levels. If true, tile information from the first ArcGIS tiled map service layer in the map's layer collection is used to define scale levels.
• Multilayer caches are not supported.
• The background color for an ArcGIS dynamic map service layer will always be transparent.
• Use the Opacity property to define variable transparency for a layer. Layer opacity is applied on the client using the Silverlight platform capabilities.

Use layer extent to set initial map extent

When a map service layer is initialized, two properties that store layer-specific extents will be available: InitialExtent and FullExtent. Handle the Initialized event on the layer in the code-behind and use either layer extent property to define the map extent. Use the following XAML and code-behind examples as a guide:

<esri:ArcGISDynamicMapServiceLayer ID="CaliforniaLayer"
  Url="http://serverapps.esri.com/ArcGIS/rest/services/California/MapServer"
  Initialized="CaliforniaLayer_Initialized" />

private void CaliforniaLayer_Initialized(object sender, EventArgs e)
{
  Layer layer = sender as Layer;
  MyMap.ZoomTo(layer.FullExtent);
}

1. Add the Initialized attribute to the layer in XAML. Define a handler method name (it will be created for you in the code-behind).
2. In the handler method, the sender parameter will always be the initialized layer. You can cast it to the abstract ESRI.ArcGIS.Client.Layer type in this case since it defines the FullExtent property.
3. Set the extent of the map to the initial extent of the layer. You can set the extent of the map using the ZoomTo or PanTo methods. Both accept any ArcGIS API for Silverlight geometry type (in the ESRI.ArcGIS.Client.Geometry namespace). In this case, pass the Envelope returned from the layer's InitialExtent property.

Handle layer initialization failure

At times, initialization of a layer may fail. This can be caused by any number of issues. Some of the more common problems are as follows:

• The Url property is incorrect.
• The service is not available.
• The site that hosts the service needs a cross-site policy file (clientaccesspolicy.xml or crossdomain.xml).
• The service is secured and requires a token or credentials.

By default, when a layer fails to initialize, it will not display in a map. To listen for initialization failure, handle the InitializationFailed event and check the exception returned via the layer's InitializationFailure property.

<esri:ArcGISDynamicMapServiceLayer ID="CaliforniaLayer" 
  Url="http://serverapps.esri.com/ArcGIS/rest/services/California/MapServer"
  InitializationFailed="CaliforniaLayer_InitializationFailed" />

private void CaliforniaLayer_InitializationFailed(object sender, EventArgs e) 
{
  Layer layer = sender as Layer;
  string exceptionMessage = layer.InitializationFailure.Message;
  MyTextBlock.Text = exceptionMessage;
}

1. Add the InitializationFailed attribute to the layer in XAML. Define a handler method name (it will be created for you in the code-behind).
2. In the handler method, the sender parameter will always be the layer that failed to initialize. You can cast it to the abstract ESRI.ArcGIS.Client.Layer type in this case since it defines the InitializationFailure property.
3. The InitializationFailure property references the initialization exception. Interrogate the exception contents to determine the problem. In this example, the exception message displays in a TextBlock in the Silverlight application.