ArcGIS API for Windows Phone

The ArcGIS API for Windows Phone provides a set of predefined map layer types to add to a Map control. Pre-defined 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 or tables hosted by MapIt
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 from 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 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 API for Windows Phone. 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.
	ArcGISDynamicMapServiceLayer	ArcGIS Server noncached map service that generates map images on-the-fly. Noncached map services provide dynamic access to both raster and vector data sources.
	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.

Adding an ArcGIS Server map service layer

The following example shows the XAML for the ContentPanel of a simple Windows Phone application that contains an ArcGIS API for Windows Phone 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 API for Windows Phone are included in the ESRI.ArcGIS.Client.dll in the ESRI.ArcGIS.Client namespace.

<Grid x:Name="ContentPanel" Grid.Row="1">
    <esri:Map x:Name="MyMap" Extent="-130, 30, -110, 50">
        <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/ImageServer" />
            <esri:ArcGISDynamicMapServiceLayer ID="CaliforniaLayer" 
                Url="http://serverapps.esri.com/ArcGIS/rest/services/California/MapServer" />
        </esri:Map.Layers>
    </esri:Map>
</Grid>

The code section demonstrates the following steps:

Add an ArcGIS Server map service layer by adding an ArcGISTiledMapServiceLayer, ArcGISImageServiceLayer or ArcGISDynamicMapServiceLayer element to the map's layer collection.
Add the ID attribute. Define a unique value to identify the layer.
Add the Url attribute. Define a URL to the appropriate service type. Use the Services Directory application (see Discovering services) 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 contain tile information.

When adding a service layer, you need to keep the following in mind:

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 each 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.

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 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 Windows Phone. See the Feature layers topic for more information on creating and defining feature layer properties.

Graphics layers

Graphics layers allow you to dynamically display graphics on a map. A graphics layer could, for example, be used to hold polygons drawn by a user or display features that satisfy a user-defined query. See Creating a graphics layer and other topics in the Graphics area of this help system for more information on working with graphics layers.

Using layer extent to set initial map extent

In Creating a map the extent of the map was set on startup by specifying the minimum and maximum x and y values. However, you may instead want to set the initial extent based on the extent of one of the layers. To do so, handle the Initialized event on the layer in the code-behind and use the extent of the layer to define the map extent.

Add the Initialized attribute to the layer in XAML to associate the Initialize event on the layer with the event handler. Define a handler method name (it will be created for you in the code-behind). See the following:

<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"/>
    </esri:Map.Layers>
</esri:Map>

In the code-behind, write the event handler to get the extent of the layer and use it to set the extent on the Map control. See the following:
```
private void CaliforniaLayer_Initialized(object sender, EventArgs e)
{
    Layer layer = sender as Layer;
    MyMap.ZoomTo(layer.FullExtent);
}
```
1. In the handler method, the sender parameter is always the initialized layer. You can cast it to the abstract ESRI.ArcGIS.Client.Layer type in this case, since it defines the extent property of interest.
2. Set the extent of the map to the extent of the layer. You can set the extent of the map using the ZoomTo or PanTo methods. Both accept any ArcGIS API for Windows Phone geometry type (in the ESRI.ArcGIS.Client.Geometry namespace). In this case, pass the Envelope returned from the layer's FullExtent property.
Note:
You need a using statement for the ESRI.ArcGIS.Client assembly to use the previous code. See the following:
using ESRI.ArcGIS.Client;

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 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.

Add the InitializationFailed attribute to the layer in XAML. Define a handler method name (it will be created for you in the code-behind). See the following:

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

In the code-behind, write the event handler to determine why the initialization failed and report the problem. See the following:
```
private void CaliforniaLayer_InitializationFailed(object sender, EventArgs e)
{
    Layer layer = sender as Layer;
    string exceptionMessage = layer.InitializationFailure.Message;
    MyTextBlock.Text = exceptionMessage;
}
```
1. In the handler method, the sender parameter is always 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 you're interested in.
2. 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 application.
Note:
- You need a using statement for the ESRI.ArcGIS.Client assembly to use the previous code. See the following:
  using ESRI.ArcGIS.Client;
- You also need a text block named MyTextBlock in your Windows Phone application.