Skip To Content

Use a MapView to display a map

In this topic

A MapView control serves as a container for a single Map. The Map can contain zero or several layers. A MapView and its associated Map and layers can be defined entirely using XAML in your UI, or by creating these objects programmatically in your code.

This topic illustrates some of the options for displaying a map in your application. For an overview of these classes, see the Maps and layers topic.

Display a map with XAML

A MapView, the Map, and the layers the map contains can all be created at design time using XAML in your UI. Objects that control the layer display, such as symbols and renderers, can also be defined this way. Before writing the XAML to define your map, you need to make sure XML namespace references are in place for all required namespaces in the Esri.ArcGISRuntime assembly. See Add ArcGIS Runtime SDK references for an overview.

XML namespace references

The following are some of the namespaces you'll commonly need and examples of classes they contain:

The following example illustrates defining XML namespace references for all of the namespaces listed above:

xmlns:esri="using:Esri.ArcGISRuntime.Controls"
xmlns:layers="using:Esri.ArcGISRuntime.Layers"
xmlns:data="using:Esri.ArcGISRuntime.Data"
xmlns:symbol="using:Esri.ArcGISRuntime.Symbology"
xmlns:geometry="using:Esri.ArcGISRuntime.Geometry"

Define a simple map

The MapView control is the top-level container used to display a map. The following example shows a MapView that contains a Map with a single layer (specifically, an ArcGISTiledMapServiceLayer). This XAML would appear inside a container element on your page, such as a Grid or StackPanel.

<esri:MapView x:Name="MyMapView">
   <esri:Map x:Name="MyMap">
      <layers:ArcGISTiledMapServiceLayer ID="BaseMap" 
              ServiceUri="http://services.arcgisonline.com/ArcGIS/rest/services/World_Street_Map/MapServer"/>
   </esri:Map>
</esri:MapView>

Add layers with XAML

Layers display in the map in the order in which they are defined in the XAML. The first layer defined is drawn first (on the bottom), the second drawn on top of the first, and so on. This order can be important if you have features in a layer that may be obscured by features in layers above.

The following example adds a FeatureLayer to the map defined above. This layer will draw on top of the BaseMap layer.

<esri:MapView x:Name="MyMapView">
   <esri:Map x:Name="MyMap">
      <layers:ArcGISTiledMapServiceLayer ID="BaseMap" 
              ServiceUri="http://services.arcgisonline.com/ArcGIS/rest/services/World_Street_Map/MapServer"/>
      <layers:FeatureLayer ID="Earthquakes">
           <data:ServiceFeatureTable Mode="OnDemand"
                 ServiceUri="http://sampleserver3.arcgisonline.com/ArcGIS/rest/services/Earthquakes/EarthquakesFromLastSevenDays/MapServer/0"/>
      </layers:FeatureLayer>
   </esri:Map>
</esri:MapView>

Tip:

In the code above, notice that all elements have either a name (x:Name) or ID property value assigned to them. Providing values for these properties is not required but is highly recommended. If you need access to your MapView or Map, define an x:Name value. To allow programmatic access to a layer, provide a value for ID. The following code, for example, is only possible because values have been provided for these properties:

var quakeLayer = MyMap.Layers["Earthquakes"] as FeatureLayer;
// -- or --
var quakeLayer = MyMapView.Map.Layers["Earthquakes"] as FeatureLayer;

Define an initial extent

Unless you provide an explicit extent at which your map should initially display, it will use the extent defined by the first (bottom) layer in the map. If your first layer is a base layer containing data at a national or world scale, for example, and you want to initially display the map at the extent of an operational layer, you need to provide a ViewpointCenter or ViewpointExtent for the InitialViewpoint property of the Map.

The following example defines an initial extent for the Map. Since the first layer in the map defines the default spatial reference, the coordinates are specified in Web Mercator, the same spatial reference as the BaseMap layer.

<esri:Map.InitialViewpoint>
    <esri:ViewpointExtent XMin="-13075816.40" 
                   YMin="4014771.46" 
                   XMax="-13073005.67" 
                   YMax="4016869.78"/>
 </esri:Map.InitialViewpoint>
The map is initially shown at the specified extent

You can define an initial extent in any coordinate system you want by providing a value for the SpatialReferenceID property of the ViewpointCenter or ViewpointExtent. Doing so does not affect the spatial reference of the Map.

The following example defines an InitialViewpoint for the map using a ViewpointCenter in a geographic spatial reference (WGS 84).

<esri:Map.InitialViewpoint>
    <esri:ViewpointCenter X="-117.445" Y="33.9" SpatialReferenceID="4326" Scale="250000"/>
 </esri:Map.InitialViewpoint>

The map view control provides map navigation out-of-the-box using actions such as mouse clicks and drags, rolling the mouse wheel, and using touch gestures. This built-in behavior allows users to explore the map without additional tools cluttering the UI. MapView also provides methods for navigating the map programmatically. See Navigate the map for more information.

Additional elements, such as symbols and renderers, can be created in your XAML. For more information and examples, see Symbols and renderers.

Display a map using code

Instead of defining your map at design time using XAML, you may prefer (or find it necessary) to create maps and layers programmatically. Even if you do create your initial map using XAML, it's likely that you'll want to work with the map at run time to modify its characteristics or contents. A common workflow is to create an initial map using XAML and also provide tools that programmatically alter the map at run time (add, remove, or symbolize layers, for example).

The following example assumes that an empty MapView has been added to the page at design time and has been given the name MyMapView (<esri:MapView x:Name="MyMapView"/>, for example). This code creates a Map that contains a single layer and has an initial extent specified. The map will be assigned to the Map property of the MapView, at which point it will be displayed on the page.

// create a new Map 
var myMap = new Esri.ArcGISRuntime.Controls.Map();

// create a new layer (world street map tiled layer)
var uri = new Uri("http://services.arcgisonline.com/arcgis/rest/services/World_Street_Map/MapServer");
var baseLayer = new Esri.ArcGISRuntime.Layers.ArcGISTiledMapServiceLayer(uri);
// (give the layer an ID so it can be found later)
baseLayer.ID = "BaseMap";

// add the layer to the Map
myMap.Layers.Add(baseLayer);

// set the initial view point
var mapPoint = new Esri.ArcGISRuntime.Geometry.MapPoint(-117.445, 33.9, 
    Esri.ArcGISRuntime.Geometry.SpatialReferences.Wgs84);
var initViewPoint = new Esri.ArcGISRuntime.Controls.ViewpointCenter(mapPoint, 250000);

myMap.InitialViewpoint = initViewPoint;

// assign the Map to the MapView's Map property
this.MyMapView.Map = myMap;

Note:

A MapView can contain zero or one Map objects. Assigning a new value to the Map property will replace the current map (if one exists) with the new one.

Work with map layers

A Map contains a collection of layers. You can add layers to, and remove layers from, this collection. You can also reorder the collection or reference individual items that you want to modify.

A layer's ID property is the key to referencing it in the map. The following example pulls a layer from the map's collection using an ID value that was assigned when the layer was created. It verifies that the layer is the correct type (FeatureLayer), and assigns a new renderer to the layer.

// create a new marker symbol (red 'x')
var simpleMarkerSym = new Esri.ArcGISRuntime.Symbology.SimpleMarkerSymbol 
{ 
Color = Colors.Red, Style = Esri.ArcGISRuntime.Symbology.SimpleMarkerStyle.X 
};

// create a new renderer that uses the symbol above
var simpleRenderer = new Esri.ArcGISRuntime.Symbology.SimpleRenderer { Symbol = simpleMarkerSym };

// find the layer with the ID "TacoShops" and cast it to FeatureLayer 
var featureLayer = MyMapView.Map.Layers["TacoShops"] as Esri.ArcGISRuntime.Layers.FeatureLayer;

// if the layer was found (and is a FeatureLayer), set the new renderer
if (featureLayer != null)
{
    featureLayer.Renderer = simpleRenderer;
}
FeatureLayer with a new renderer applied

For additional information about working with layers programmatically, see the Add layers with code topic.

See Symbols and renderers for more information about applying symbology to features in the map.

Use data binding to display a map

Data binding provides a mechanism that ties information coming from another object, such as a custom class in your app, to UI elements for display. As an example, you might have a customer class that is initialized with information from a database when the app starts. Data binding allows you to display the current properties of your customer object and have them update real-time as they change in the underlying database. Data binding can also work the other way, pushing changes made in the UI (text typed into a TextBox, for example) to the corresponding field in the database.

This XAML binding basics article provides a good overview of the rich set of data binding functionality provided by XAML. Data binding plays a key role in the implementation of the Model-View-ViewModel (MVVM) design pattern, an overview of which can be found in this article: MVVM Pattern Made Simple. See the MVVM design pattern tutorial to learn how to use MVVM with ArcGIS Runtime SDK for .NET.

Assign a data context

A data context provides a data source that binding can work with. In the example described previously, a customer object would serve as the data context for all controls in the UI, and each control would then be bound to a specific property of customer. A data context can be assigned to any FrameworkElement in your UI and will apply to all child elements it contains. If you set the data context on a Grid control, for example, all elements inside the grid can use that data context for binding. Several data contexts can be defined (and nested) within your UI, in which case the most local data context for a particular element will be used to resolve data bindings.

Note:

Data binding will work without defining a data context for container controls but will require that you specify the data source explicitly for each control you want to bind.

To provide the appropriate data context for your MapView, the first step is to create a class that defines a property of type Esri.ArcGISRuntime.Controls.Map. The following example shows a simple class (MyViewModel) that defines a single property called Map. This property returns an Esri.ArcGISRuntime.Controls.Map and can therefore be bound to the Map property of a MapView. When the class is instantiated, a new Map is created, a layer is added, and the initial extent is set. At run time, the local copy of the map (_map) can be manipulated, and the changes will appear in the UI thanks to the data binding.

class MyViewModel
{
    // a Map property that a MapView can bind to
    private Esri.ArcGISRuntime.Controls.Map _map;
    public Esri.ArcGISRuntime.Controls.Map Map
    {
        get { return _map; }
        set { this._map = value; }
    }

    // constructor
    public MyViewModel()
    {
        // on instantiating the class, create the map (data binding will be responsible for displaying it in the view)
        this._map = new Esri.ArcGISRuntime.Controls.Map();

        // create a new layer (world street map tiled layer)
        var uri = new Uri("http://services.arcgisonline.com/arcgis/rest/services/World_Street_Map/MapServer");
        var baseLayer = new Esri.ArcGISRuntime.Layers.ArcGISTiledMapServiceLayer(uri);
        // (give the layer an ID so it can be found later)
        baseLayer.ID = "BaseMap";

        // add the layer to the Map
        this._map.Layers.Add(baseLayer);

        // set the initial view point
        var mapPoint = new Esri.ArcGISRuntime.Geometry.MapPoint(-117.445, 33.9, 
            Esri.ArcGISRuntime.Geometry.SpatialReferences.Wgs84);
        var initViewPoint = new Esri.ArcGISRuntime.Controls.ViewpointCenter(mapPoint, 250000);

        this._map.InitialViewpoint = initViewPoint;
    }
}

The data context for any FrameworkElement is set with the DataContext property. Since you want the data context to be available as soon as your controls are displayed, the constructor for your page is a good place to set the data context. The following example creates a new instance of the MyViewModel class and assigns it as the data context for the entire page:

public MainPage()
{
    this.InitializeComponent();

    // create a new MyViewModel (the class constructor builds the map)
    var viewModel = new MyViewModel();

    // use it to set the data context for the page(and all controls it contains)
    this.DataContext = viewModel;
}

Define data binding

With the data context in place, data bindings are easy to define in your XAML. For any property in your UI that you want to bind, you simply need to point to the corresponding property on the data context object. To display the Name property from a data context object of type Customer in a TextBlock control, for example, you would use syntax like the following:

<TextBlock Text="{Binding Name}"/>
Tip:

If a data binding can't be resolved, perhaps because the data context is missing or the binding property doesn't exist, the binding is ignored. No exceptions are thrown for an erroneous binding. To track down binding problems, check the Output window in Visual Studio while debugging your app.

To bind a map to a MapView, you need to first set the data context of the map view (or its container) to an object that has a property of type Esri.ArcGISRuntime.Controls.Map, and bind the Map to that property. The following example defines such a binding using the MyViewModel class from an earlier example:

<esri:MapView x:Name="MyMapView" Map="{Binding Map}"/>

Related topics