ArcGIS API for Windows Phone

Feature layers are a special type of graphics layer that allow you to display features in a layer hosted by an ArcGIS Server map service, an ArcGIS Server feature service, or in a table served by the MapIt Spatial Data Service. As with graphics layers, feature layers contain and display graphic features, which consist of geometry and attributes. In addition, feature layers provide solutions when working on applications in the following areas:

Editing—Feature layers are the key to editing features on the web. You can only perform editing on feature layers that reference a feature service. See Editing features to learn more about this requirement and how to create a feature service.
Definition expressions—There may be times when you want to work with features that satisfy certain attribute criteria and disregard the rest. In this situation, you can set a where clause on the feature layer to retrieve only the features you need. In addition, ArcGIS Server feature layers have a default definition expression that comes from the definition query set in the source map document. You cannot request features outside of any definition expression set in the map document.
Time definitions—You can use a feature layer to isolate features that meet a certain temporal criteria (for example, to show only houses that were constructed before 1930). If your house layer is time aware, you can set a time definition on the feature layer to show only those houses with construction dates prior to 1930. See Time-aware layers for more information.
Selection—Feature layers support selection, which represents a subset of features that the user has chosen to isolate for viewing, editing, or analytical purposes. Users can add or remove features from the selection based on spatial or attribute criteria. The feature layer makes it easy to draw the selection set with a different type of symbol to differentiate them from other features. A selection set can be used as input for statistical calculations, geoprocessing tools, and graphing, opening the possibility for interactive geographic information system (GIS) analysis and exploration. For example, selections could allow a user to draw a polygon around a set of buildings, then tap a button to calculate the solar potential of those buildings. Selections also play an important role in editing workflows where the feature currently undergoing edits is displayed as selected. To make your selection, either call the Select() method on individual graphic features or use the Editor's Select command.
Note:
You cannot request features outside of any definition expression set in the map document or on the feature layer.

The following table highlights feature layer sources supported in the ArcGIS API for Windows Phone:

FeatureLayer source	Description
ArcGIS Server map service	Dynamic (non-cached) ArcGIS Server map services can contain feature layers. Each layer is represented by an explicit URL that references the map service name and layer ID assigned by the map service. The URL is usually retrieved using ArcGIS Services Directory. For example: http://serverapps.esri.com/ArcGIS/rest/services/California/MapServer/8 The California map service contains a layer with county features assigned the unique ID 8.
ArcGIS Server feature service	ArcGIS Server feature services reference individual feature layers. Each layer is represented by an explicit URL that references the feature service name and layer ID assigned by the service. The URL is usually retrieved using ArcGIS Services Directory. For example: http://serverapps.esri.com/ArcGIS/rest/services/California/FeatureServer/8 The California feature service contains a feature layer with county features assigned the unique ID 8. ArcGIS Server feature services support editing when the feature layer is hosted in an ArcSDE geodatabase. Use a feature service if you want to take advantage of symbols and feature templates from the service's source map document.
MapIt	MapIt includes a REST-ful web service called the Spatial Data Service. It provides access to tables in databases hosted by a database instance, such as SQL Server. A table can be spatially-enabled, which means it has a column that contains geometry. For example: http://serverapps.esri.com/SDS/databases/Demo/dbo.USStates_Geographic The Demo database contains a spatially enabled table dbo.USStates_Geographic. Editing and time awareness are not supported with MapIt layers at this time.

FeatureLayer source

Description

ArcGIS Server map service

Dynamic (non-cached) ArcGIS Server map services can contain feature layers. Each layer is represented by an explicit URL that references the map service name and layer ID assigned by the map service. The URL is usually retrieved using ArcGIS Services Directory.

For example:

http://serverapps.esri.com/ArcGIS/rest/services/California/MapServer/8

The California map service contains a layer with county features assigned the unique ID 8.

ArcGIS Server feature service

ArcGIS Server feature services reference individual feature layers. Each layer is represented by an explicit URL that references the feature service name and layer ID assigned by the service. The URL is usually retrieved using ArcGIS Services Directory.

For example:

http://serverapps.esri.com/ArcGIS/rest/services/California/FeatureServer/8

The California feature service contains a feature layer with county features assigned the unique ID 8.

ArcGIS Server feature services support editing when the feature layer is hosted in an ArcSDE geodatabase. Use a feature service if you want to take advantage of symbols and feature templates from the service's source map document.

MapIt

MapIt includes a REST-ful web service called the Spatial Data Service. It provides access to tables in databases hosted by a database instance, such as SQL Server. A table can be spatially-enabled, which means it has a column that contains geometry.

For example:

http://serverapps.esri.com/SDS/databases/Demo/dbo.USStates_Geographic

The Demo database contains a spatially enabled table dbo.USStates_Geographic.

Editing and time awareness are not supported with MapIt layers at this time.

Note:

Feature layers have a maximum count of features that they return. By default, feature layers in ArcGIS Server 9.3.1 return 500 features. Feature layers in ArcGIS Server 10 and later, as well as MapIt, return 1,000 features by default. These default maximums can be customized by the manager of the server.

Feature layers have several properties that enable functionality that is not available with graphics layers. The following table highlights some of the key members included with FeatureLayer:

FeatureLayer member	Description
Url property	Address of a layer in an ArcGIS Server map service or table hosted by a MapIt Spatial Data Service (see the previous table for examples). Feature layers are automatically populated with features from the source.
Where property	Query that defines which features in the specified layer are displayed. If not specified, all features will be retrieved (using a default query of 1=1).
Mode property	Defines the technique for retrieving features from a service. The available modes are as follows: Snapshot—Retrieves all the features from the layer immediately after the layer is added to the map. This eliminates any need to return to the server for information but can become cumbersome if the layer contains many features. The browser can become overwhelmed by the number of features it needs to draw, or the service may reach its limit of how many features it can return at once. Use snapshot mode only with smaller datasets or when dealing with temporal data. OnDemand—Retrieves features as they are needed, requesting only those features within the current view extent. On demand mode requires more round trips between the client and server and should not be used for showing temporal animations. However, it protects you from retrieving more features than you need. SelectionOnly—Does not initially request any features. Features are added only when a selection is made. Selection only mode is useful when you cannot or do not want to bring all features into the client, but you want to highlight one or more features for a certain reason. In most cases, this mode is used in conjunction with a dynamic map service layer to display the location of selected features.
OnDemandCacheSize property	Defines the number of features outside the current map extent to store in client-side cache when Mode = OnDemand. If a feature has been retrieved and resides in cache, it will not be requested again unless it's removed from the cache (the number of features in the cache is surpassed). The cache is not maintained across sessions.
SelectionColor property	Defines a color or visual brush to display selected graphic features in a feature layer. Each graphic feature maintains a Selected property. The SelectedGraphics and SelectionCount properties (implemented on GraphicsLayer) return information on selected graphics.
TimeExtent property	References the time instance or range represented within the feature layer. This property is defined by an ArcGIS Server map or feature service and is read-only.
DisableClientCaching property	By default, a feature layer uses browser caching to improve performance. If the data underlying the feature layer changes (for example, the table hosted by MapIt's Spatial Data Service is being updated with new content) and you want to see the changes immediately, set this property to true.
Update method	This method re-queries the data underlying the feature layer. If layer or table contents have changed on the server, you can call this method to see changes in the feature layer on the client. Tip: You may need to disable client caching.

Adding a feature layer

As with graphics layers, you'll usually declare feature layers in XAML. They should be inserted inside a Map control element below any base layers. The code in this section assumes you have already created a Windows Phone application with an ArcGIS API for Windows Phone Map control (see Creating a map for details).

Add a reference to the System.Runtime.Serialization assembly to your project.

In the XAML, declare a FeatureLayer with an ID of MyFeatureLayer in the Map element. Place it after the base layer so that it draws on top of the base layer.

<esri:Map x:Name="MyMap" Extent="-130,10,-70,60">
    <esri:Map.Layers>
        <esri:ArcGISTiledMapServiceLayer ID="StreetMapLayer"
            Url="http://server.arcgisonline.com/ArcGIS/rest/services/ESRI_StreetMap_World_2D/MapServer"/>
        <esri:FeatureLayer ID="MyFeatureLayer" >
        </esri:FeatureLayer>
    </esri:Map.Layers>
</esri:Map>

Provide the URL of the map service layer that the feature layer will use. To find the service URL, use the ArcGIS Services Directory. See Discovering services for more information. The following code specifies the cities layer of the ESRI StatesCitiesRivers USA service:
```
<esri:FeatureLayer ID="MyFeatureLayer"
    Url="http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Specialty/ESRI_StatesCitiesRivers_USA/MapServer/0" >
</esri:FeatureLayer>
```
The Where property defines a filter to apply to the specified map service layer. Only features with attributes that satisfy the filter expression will be drawn. The filter specified in the following code will make it so that the feature layer only includes features with a value greater than 75000 in the POP1990 field. This corresponds to cities with a 1990 population of more than 75,000.
Tip:
To display all the features in the specified layer, define a filter expression that is always true, such as 1 = 1.
```
<esri:FeatureLayer ID="MyFeatureLayer"
    Url="http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Specialty/ESRI_StatesCitiesRivers_USA/MapServer/0" 
    Where="POP1990 > 75000" >
</esri:FeatureLayer>
```
The Renderer property defines a renderer to apply to all the features in the layer. To specify this property, you first have to declare a symbol and renderer in your XAML. Symbols are included in the ESRI.ArcGIS.Client.Symbols namespace of the ESRI.ArcGIS.Client assembly. To declare a symbol, map an XML namespace to the ESRI.ArcGIS.Client.Symbols CLR namespace by inserting the following code as an attribute of the phone:PhoneApplicationPage element in the XAML:
```
xmlns:esriSymbols="clr-namespace:ESRI.ArcGIS.Client.Symbols;assembly=ESRI.ArcGIS.Client"
```

Declare a symbol and a renderer as resources in the XAML. Typically, such resources are declared as resources of the root layout element, which is a Grid named LayoutRoot by default. Insert the following code above the Map control to declare a green diamond marker symbol:

<Grid x:Name="LayoutRoot" Background="Transparent">
    <Grid.RowDefinitions>
        <RowDefinition Height="Auto"/>
        <RowDefinition Height="*"/>
    </Grid.RowDefinitions>
    <Grid.Resources>
        <esriSymbols:SimpleMarkerSymbol x:Key="MyMarkerSymbol" Color="Green" Style="Diamond" Size="14" />
        <esri:SimpleRenderer x:Key="MySimpleRenderer" Symbol="{StaticResource MyMarkerSymbol}" />
    </Grid.Resources>

Associate the renderer with the FeatureLayer. Use the x:Key of the renderer when binding it.

<esri:FeatureLayer ID="MyFeatureLayer"
    Url="http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Specialty/ESRI_StatesCitiesRivers_USA/MapServer/0" 
    Where="POP1990 > 75000" 
    Renderer="{StaticResource MySimpleRenderer}" >
</esri:FeatureLayer>

Run the Windows Phone application. All the U.S. cities with a 1990 population of more than 75,000 are marked with a green diamond as shown in the following screen shot:

Clustering features

While adding a feature as described in the previous section results in a map with the cities marked, there are two main issues with displaying the cities this way. First, there are many areas of the country where the city symbols overlap, making it impossible to see how many cities are displayed. Second, a relatively large number of graphics are displayed. Depending on the processing power of the phone on which the application is running, this can introduce performance problems in drawing the graphics.

These issues can be alleviated by adding a Clusterer to the FeatureLayer. See Clustering for additional information on clustering features to provide a more presentable interface and user experience.

In cases such as the one shown above, this will aggregate multiple point graphics into fewer point graphics, each of which displays a number showing how many features it represents. After applying a SimpleClusterer with a custom gradient, the cities layer appears as shown in the following screen shot:

While it still has the same green diamond symbolizing a single city, the areas with many cities with a 1990 population greater than 75,000 now show clusters that display the number of city results in that location.

Including specific fields

With feature layers, you also have the ability to specify the fields the layer's graphics will include. The fields specified will be populated with the corresponding values from the feature layer's map service layer. The fields are specified as strings within the OutFields property.

To specify strings as XAML elements, you must first map an XML namespace to the CLR namespace that contains the String class. This class is contained in the System namespace of the mscorlib assembly. Insert the attribute shown in the following code as an attribute of the phone:PhoneApplicationPage element in the XAML.
```
xmlns:sys="clr-namespace:System;assembly=mscorlib"
```

To include the CITY_NAME and POP1990 fields, specify the OutFields property as shown in the following code. The values of the fields specified here can be displayed by using data binding to bind them to data controls.

<esri:FeatureLayer ID="MyFeatureLayer"
    Url="http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Specialty/ESRI_StatesCitiesRivers_USA/MapServer/0" 
    Where="POP1990 > 75000" >
    <esri:FeatureLayer.OutFields> 
        <sys:String>CITY_NAME</sys:String> 
        <sys:String>POP1990</sys:String> 
    </esri:FeatureLayer.OutFields>
</esri:FeatureLayer>

1/23/2012