The ArcGIS Silverlight API provides a set of pre-defined map layer types to add to a Map control. Layer types include 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 or tables hosted by MapIt, graphics layers for native graphic feature display, and element layers to include Silverlight UI elements and media on a map.

Layers are added to a Map controls layer's collection via the Layers property. There are a few 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.
  
  
  
  
• 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 pre-defined 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 and descriptions included with the ArcGIS Silverlight API. You will use the layer types to add layers to your Map.

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 or a spatial table using a MapIt Spatial Data Service. The Url property of a FeatureLayer defines the HTTP endpoint to a service which provides access to the layer or table. Graphic features are retrieved from the service and rendered on the client using graphic capabilities native to the ArcGIS API for Silverlight/WPF. See the FeatureLayer discussion 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 markup for a simple Silverlight application that contains an ArcGIS Silverlight API Map control with three different ArcGIS Server map service layers. Use 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 Silverlight API are included in the ESRI.ArcGIS.Client.dll in the ESRI.ArcGIS.Client namespace.

<UserControl x:Class="SilverlightApp.Page"
 xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 
    xmlns:esri="clr-namespace:ESRI.ArcGIS.Client;assembly=ESRI.ArcGIS.Client">
    <Grid x:Name="LayoutRoot" Background="White">

		<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>
       
    </Grid>
</UserControl> 
        

1. Add an ArcGIS Server map service layer. Add an ArcGISTileMapServiceLayer, ArcGISImageServiceLayer or ArcGISDynamicMapServiceLayer element to the map layers collection.
   
   
2. Add the ID attribute. Define a unique value to identify the layer.
   
   
3. Add the Url attribute. Define a url to the appropriate service type. Use the Services Directory application to navigate 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.

Notes:

• If the map service is secured, you may 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 only be rendered 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 ArcGISTiledMapServiceLayer in the Map's layer collection is used to define scale levels.
• Multi-layer caches are not supported.
• The background color for an ArcGISDynamicMapServiceLayer 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 then use either layer extent to define the Map extent. Use the following XAML and code-behind examples as a guide.

XAML

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

Code-Behind

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

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 extent property we're interested in.
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 Silverlight API geometry type (in the ESRI.ArcGIS.Client.Geometry namespace). In this case we'll pass the Envelope returned from the layer's InitialExtent property.

Handle layer initialization failure

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

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

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

XAML

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

Code-Behind

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 we're interested in.
3. The InitializationFailure property references the initialization exception. Interrogate the exception contents to determine the problem. In this example, the exception message is displayed in a TextBlock in the Silverlight application.