Add layers with code

While you can create a map and all the layers it contains at design time using XAML, you will likely find the need to work with layers in the map programmatically. This topic describes how to add new layers to the map using code.

For a description of working with maps and layers using XAML, see Use the MapView to display a map.


Sharing a single layer instance simultaneously between multiple maps is not supported and is likely to cause stability or performance issues. See the Multiple maps topic for more information about working with multiple map views in your app.

Create a layer

There are several types of layers that you can include in your map, described in the Maps and layers topic. Each of these types of layers can be created at run time (programmatically) if needed. Depending on the type of layer you're creating, you'll need to provide values for different properties to successfully display the layer. Some layers, such as ArcGISTiledMapServiceLayer, display data based on an ArcGIS for Server REST endpoint for a tiled map service. Others, such as FeatureLayer, may display data from a remote source or from a local geodatabase. GraphicsLayer does not require a data source, as the graphics it contain are stored in memory. Once a layer has been created and values for required properties have been defined, you can add the layer for display in the map.

ArcGIS for Server layers

A variety of layers can be created that use a service hosted with ArcGIS for Server as a data source. Each of these layers require a value for the ServiceUri property to define the service end point URL. Another layer that can be based on ArcGIS for Server data, FeatureLayer, is covered in the feature layers section below.

The following code sample creates three new layers to display ArcGIS for Server services. The ServiceUri that defines the data source is passed into each layer's constructor.

// create a new tiled map service layer for the world street map service
var tiledUri = new Uri("");
var agsTiledLayer = new Esri.ArcGISRuntime.Layers.ArcGISTiledMapServiceLayer(tiledUri);

// create a new dynamic map service layer to show hurricane tracks
var dynUri = new Uri("");
var agsDynLayer = new Esri.ArcGISRuntime.Layers.ArcGISDynamicMapServiceLayer(dynUri);

// create a new image service layer to show imagery of Toronto, Canada
var imgUri = new Uri("");
var agsImageLayer = new Esri.ArcGISRuntime.Layers.ArcGISImageServiceLayer(imgUri);

// clear (remove) all current layers in the map

// add the new layers (will draw in this order)


The order in which layers draw is the same order in which they appear in the map's layer collection. The first layer added draws first, and subsequent layers added to the collection draw on top of previous layers.

Bing layers

A BingLayer is a tiled image map service layer that allows you to work with a cached map service resource exposed by Microsoft's Bing services. The BingLayer uses a set of SOAP proxies and value object types rather than REST. ArcGIS Runtime .NET SDK provides a set of implementation classes that utilize the proxies and value objects internally. Use of Bing services requires that you generate and provide a key when utilizing BingLayer components. You can obtain a key by visiting the Bing Maps Account Center.

The MapStyle property is used to indicate the type of map to display. Valid styles are Road, Aerial, or AerialWithLabels

The Culture property allows you to use maps that are labeled for a specific culture (language). US English ("en-US") is the default culture.

The following code sample shows how to create a new Bing map layer and assign the required key. The style is set to AerialWithLabels, and the culture to French.

var bingMapLayer = new Esri.ArcGISRuntime.Layers.BingLayer();
bingMapLayer.Key = "mYB!ngK3Y!";
bingMapLayer.MapStyle = Esri.ArcGISRuntime.Layers.BingLayer.LayerType.AerialWithLabels;
bingMapLayer.Culture = new System.Globalization.CultureInfo("fr-FR");
Bing Aerial layer with French labels


When using Bing Maps in your application, it's important to include attribution information. See the Branding Guidelines from Microsoft for more information.

Feature layers

A feature layer can display data from a single layer in an ArcGIS for Server service, or it can be based on a dataset stored locally in a geodatabase. Each feature in a feature layer has geometry and attribute information and is rendered individually in the map using native graphics. Functionality is dependent on whether the layer was created from a map service or feature service. Feature layers support editing capabilities, such as adding, deleting, or updating spatial and attribute characteristics of features.

For more information about editing features, see the Edit features topic.

Online feature layers

To create a layer that uses an ArcGIS for Server service as its data source, you need to specify the URL to the service endpoint, as discussed previously. To do so for a FeatureLayer, you create an associated ServiceFeatureTable that references the data source (service URI). The ServiceFeatureTable exposes other properties you may find useful, such as the desired OutFields, the Mode used to retrieve features from the server (described below), and a Where expression to filter features.

The following code sample creates a new ServiceFeatureTable, sets the ServiceUri, Mode, and Where properties, then uses it to create a new FeatureLayer:

// create a ServiceFeatureTable from the Incidents layer in the SF311 feature service
var gdbFeatureSvcTable = await Esri.ArcGISRuntime.Data.ServiceFeatureTable.OpenAsync(
     new Uri(""));

// define the query mode for retrieving features from the server
gdbFeatureSvcTable.Mode = Esri.ArcGISRuntime.Data.QueryMode.OnDemand;

// define a Where expression to only show open incidents
gdbFeatureSvcTable.Where = "Status = 2"; // incident is open

// create a feature layer from the table
var featureLayer = new Esri.ArcGISRuntime.Layers.FeatureLayer(gdbFeatureSvcTable);
featureLayer.ID = "IncidentsLayer"; // (assign an ID so it can be found later)
// add the feature layer to the map

Query mode options

When creating a FeatureLayer from an online data source (ServiceFeatureTable), you have two options, or query modes, for how features are retrieved from the remote service for display on the client. Depending on the nature and number of the features you want to work with, there may be performance ramifications for the mode you choose.

  • Snapshot—Retrieves all features currently in the ServiceFeatureTable.
  • OnDemand—Retrieves only those features needed to display the layer for the current map extent. As the extent changes, additional features are retrieved as needed.

Settings on the server can restrict the maximum number of features returned. In that case, only the maximum number of features are retrieved by the client rather than all features requested. While this is true for both query modes, it is less likely to be a problem when using the OnDemand mode since a subset of features is usually being requested.

In general, the OnDemand mode is better suited for layers that contain a large number of features. Since only the features required for the current extent are brought to the client, performance is improved by not wasting bandwidth on data that is not immediately required in the app.

OnDemand mode is the best option if your app needs to have all features for a layer immediately available in the client. It may also be the best option for layers that don't contain a large number of features. In that case, a single request is required to return the features, rather than perhaps several as the user changes the map extent. To re-query the online source (to bring in feature edits that may have been made, for example), use the RefreshFeatures method.

Offline feature layers

To use a FeatureLayer to display features from an offline source (a local geodatabase), you need to create a new GeodatabaseFeatureTable and point it to the geodatabase and table that represent the data source. Once in the map, there are no functional differences between an offline and online feature layer. Both offer the same functionality, including editing capabilities, and provide a seamless experience to your user.

See Create an offline map to learn how to create an offline data source (geodatabase) from an online feature layer.

// open a geodatabase on the local device
var gdb = await Esri.ArcGISRuntime.Data.Geodatabase.OpenAsync(@"C:\Temp\Cache\WildlifeLocal.geodatabase");
// loop thru all tables in the geodatabase
foreach (var table in gdb.FeatureTables.ToList())
    // create a new feature layer to display each table
    var lyr = new FeatureLayer
        ID = table.Name + "Offline", 
        DisplayName = table.Name,
        FeatureTable = table
    // add each layer to the map

Graphics layers

Graphics layers are app-defined layers designed for drawing dynamic features on the map. Each graphic is defined by its own individual geometry, attributes, and symbol so that many different geometry types can coexist in one graphics layer. The graphics can be used to hold polygons drawn by a user, display features that satisfy a user-defined query, or show a real-time Global Positioning System (GPS) location. All graphics in a graphics layer are stored in memory and are only available while the app is running.

For more information about graphics, see the Features and graphics topic.

The following code sample creates a new graphics layer, adds it to the map, and adds a single point at the center of the map's extent:

// create a new graphics layer, give it an ID
var graphicsLayer = new Esri.ArcGISRuntime.Layers.GraphicsLayer();
graphicsLayer.ID = "MyGraphicsLayer";

// add the graphics layer to the map

// create a symbol (large cyan circle) for displaying a point
var markerSym = new Esri.ArcGISRuntime.Symbology.SimpleMarkerSymbol();
markerSym.Color = Colors.Cyan;
markerSym.Size = 18;
markerSym.Style = Esri.ArcGISRuntime.Symbology.SimpleMarkerStyle.Circle;

// create a marker graphic for the center of the map's extent
var pointGraphic = new Esri.ArcGISRuntime.Layers.Graphic(MyMapView.Extent.GetCenter(), markerSym);

// add the graphic to the graphics layer for display on the map

For more information about adding graphics to a map, see Add graphics and text.

KML layers

Keyhole Markup Language (KML) is an XML format for describing geographic features for visualization in two dimensions (in a Map in other words) or three dimensions (in a Scene). KML files use a .kml extension for plain KML text files or .kmz for compressed files. In your ArcGIS Runtime apps, you can use the KmlLayer to read and display geographic information from a .kml or .kmz file, which can be stored locally or accessed from an online source.

The following example adds a KML layer to the map showing recent earthquakes.

// create a KML layer from an online file
var sourceUri = new Uri("");
var kmlLayer = new KmlLayer(sourceUri);

// Add the kml layer to the map

KML layer showing recent earthquakes

Find a layer

You may need to work with a layer that was added previously to your map. To get a reference to an existing layer in the map, you can use the layer's ID property. This is an especially common workflow for graphics layers, where you may be continuously adding, removing, or updating graphics in the layer as your app is running.

The following code sample references a layer with an ID value of MyGraphicsLayer. The layer is then cast to the GraphicsLayer type. If a layer with that ID doesn't exist, or is not of type GraphicsLayer, a null value is returned. If the layer is found, it is used to add a new graphic to the map. If it is not found, a new graphics layer is created and given the ID MyGraphicsLayer.

// find a graphics layer called "MyGraphicsLayer" in the map
var graphicsLayer = MyMapView.Map.Layers["MyGraphicsLayer"] 
                                                    as Esri.ArcGISRuntime.Layers.GraphicsLayer;

// if the layer doesn't exist, create it and add it to the map
if (graphicsLayer == null)
    graphicsLayer = new Esri.ArcGISRuntime.Layers.GraphicsLayer();
    graphicsLayer.ID = "MyGraphics";

    // add the graphics layer to the map

// ... code here to make a new graphic ...

// add the graphic to the graphics layer for display on the map

Related topics