ArcGIS API for Silverlight

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 or an ArcGIS Server feature service. As with graphics layers, feature layers contain and display graphic features, which consist of geometry and attributes. In addition, feature layers can provide solutions in the following circumstances:

Editing—Feature layers are the key to editing features on the web. The editing controls included in the ArcGIS Toolkit library are designed to work with feature layers. 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 expressions 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.
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 click 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 Silverlight:

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://sampleserver3.arcgisonline.com/ArcGIS/rest/services/Petroleum/KSFields/FeatureServer/0 This sample service represents oil and gas fields in the State of Kansas. The Petroleum feature service contains a feature layer with current Kansas field production features assigned the unique ID 0. 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.

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://sampleserver3.arcgisonline.com/ArcGIS/rest/services/Petroleum/KSFields/FeatureServer/0

This sample service represents oil and gas fields in the State of Kansas. The Petroleum feature service contains a feature layer with current Kansas field production features assigned the unique ID 0.

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.

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 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 (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 ("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 the number of features it can return at once. Use snapshot mode only with smaller datasets or when dealing with temporal data. On demand—Retrieves features as they are needed, requesting only the features within your 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. Selection only—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 (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, and 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 your feature layer changes (that is, the feature service is being updated with new content) and you want to see the changes upon the next request to the service, set this property to true.
Update method	This method re-queries the data underlying your feature layer. If layer 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. If you have not already done so, create a Silverlight application with a map (see Creating a map for details).

Note:

The code in this topic requires references to the ESRI.ArcGIS.Client and System.Runtime.Serialization assemblies. The UserControl of the page (for example, MainPage.xaml) needs to have the following XML namespace declaration:

xmlns:esri="http://schemas.esri.com/arcgis/client/2009"

In the Map element, declare a FeatureLayer with an ID of MyFeatureLayer as shown in the following code sample:

<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 URL, use the ArcGIS Services Directory. See Discovering Services for more information. The following code specifies the cities layer of the ESRI_StatesCitiesRivers_USAservice:

<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"
      Url="http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Specialty/ESRI_StatesCitiesRivers_USA/MapServer/0" >
    </esri:FeatureLayer>
  </esri:Map.Layers>
</esri:Map>

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: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"
      Url="http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Specialty/ESRI_StatesCitiesRivers_USA/MapServer/0"
      Where="POP1990 > 75000" >
    </esri:FeatureLayer>
  </esri:Map.Layers>
</esri:Map>

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 a renderer as resources in your XAML. Typically, such resources are declared as resources of the root layout element, which is a Grid by default. Assuming this is the case in your Silverlight application, you can insert the following code above the Map control to declare a green diamond marker symbol and a renderer that consumes it:

<Grid.Resources>
  <esri:SimpleMarkerSymbol x:Key="MyMarkerSymbol" Color="Green" Style="Diamond" Size="14" />
  <esri:SimpleRenderer x:Key="MySimpleRenderer" Symbol="{StaticResource MyMarkerSymbol}" />
</Grid.Resources>
<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"
      Url="http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Specialty/ESRI_StatesCitiesRivers_USA/MapServer/0"
      Where="POP1990 > 75000" >
    </esri:FeatureLayer>
  </esri:Map.Layers>
</esri:Map>

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

<Grid.Resources>
  <esri:SimpleMarkerSymbol x:Key="MyMarkerSymbol" Color="Green" Style="Diamond" Size="14" />
  <esri:SimpleRenderer x:Key="MySimpleRenderer" Symbol="{StaticResource MyMarkerSymbol}" />
</Grid.Resources>
<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"
      Url="http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Specialty/ESRI_StatesCitiesRivers_USA/MapServer/0"
      Where="POP1990 > 75000" Renderer="{StaticResource MySimpleRenderer}" >
    </esri:FeatureLayer>
  </esri:Map.Layers>
</esri:Map>

Run the 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

There are two issues with displaying the cities as green diamonds, as shown in the example of adding a feature layer. 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 computer on which the application is running, this can introduce performance problems in drawing the graphics.

These issues can be alleviated by setting the ClusterFeatures property of the feature layer to true. 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. The following code shows an example of setting the ClusterFeatures:

<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.Clusterer>
    <esri:FlareClusterer 
      FlareBackground="#99FF0000" 
      FlareForeground="White" 
      MaximumFlareCount="9" />
  </esri:FeatureLayer.Clusterer>
</esri:FeatureLayer>

After applying the clusterer, the cities layer in the application will appear similar to the following screen shot:

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. Add the XML namespace declaration as follows:

xmlns:sys="clr-namespace:System;assembly=mscorlib">

To include the CITY_NAME and POP1990 fields, specify the OutFields property as shown in the following sample code. The values of the fields specified here can be displayed by using Silverlight data binding to bind them to MapTips or other data controls (for example, DataGrids).

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

9/12/2012