Use ArcGIS basemaps

ArcGIS Online includes a suite of basemaps that provide reference maps for our world and context for your work. These maps are built from the best available data from a community of authoritative data providers and presented in multiple cartographic styles. These maps are designed to emphasize different views of our world, from physical to political. You can choose the basemap that is most appropriate for your app.

This tutorial describes the recommended technique for switching the basemap layers of your map. It introduces the basic properties of layers and explains how to work with them at design time in XAML or programmatically using C# or Visual Basic .NET (VB .NET). Your completed app will provide a drop-down selection to allow users to quickly change which basemap is displayed in the map when the app is running.


This tutorial requires a supported version of Microsoft Visual Studio and ArcGIS Runtime SDK for .NET. Refer to the appropriate topics in the guide for information on installing the SDK and system requirements.

Familiarity with Visual Studio and a basic understanding of XAML and C# or VB.NET is recommended.

Create a WPF app

You'll use Visual Studio to create a WPF app.

  1. Open a supported version of Microsoft Visual Studio.
  2. Choose File > New > Project (or click New Project on the Start page) to create a project.
  3. Click Windows Desktop > WPF Application in the New Project dialog box (you can create your project in either C# or VB .NET).

    Visual Studio 2015 organizes project types slightly differently. You'll find WPF Application projects under Windows > Classic Desktop


    ArcGIS Runtime SDK for .NET provides a project template for creating your mapping app, called ArcGIS Runtime 10.2.7 for .NET App. Creating your project from the template will add the appropriate references and a page with a map view containing a single base layer. In this tutorial, you'll build your app from a blank template.

  4. Choose a folder location for your new project and name it Basemaps.

    Visual Studio New Project dialog box

  5. Click OK to create the project.

    Your project opens in Visual Studio and contains a single WPF window called MainWindow.xaml.

  6. Next, you'll add a reference to the ArcGIS Runtime SDK for .NET API assembly.
  7. Right-click the References node under the Basemaps project listing in the Visual Studio Solution Explorer window, and click Add Reference in the context menu.
  8. Check the listing for the Esri.ArcGISRuntime assembly under Assemblies > Extensions.

    Visual Studio Reference Manager dialog box

  9. Click OK to add the reference to ArcGIS Runtime for .NET.

    Visual Studio project references

  10. The Esri.ArcGISRuntime library contains the Map control and all core API components and classes you'll need.

Display hurricane activity with a basemap

Now that you've created a simple project and added a reference to ArcGIS Runtime, you're ready to add a map to your app. ArcGIS Runtime allows you to work with geographic data from a variety of sources, including those local to your app as well as data provided remotely as an Internet service. In your initial map, you'll display an ArcGIS Online streets map as your basemap to provide context for a dynamic layer showing hurricane activity in the Atlantic Ocean.

    To use the library in the XAML designer, you must first make a reference to the XML namespace for ArcGIS Runtime.
  1. Open the MainWindow.xaml file in the Visual Studio designer.
  2. Go to the XAML view of the designer, and add the following XML namespace reference to the Window XAML element. Visual Studio offers IntelliSense to help complete the URL portion of the statement.

    XML namespace reference to ArcGIS Runtime

  3. Next, you'll add a MapView control to the window and define a layer to display.
  4. Add the following XAML inside the <Grid> element to define a new MapView control on the page:
    <esri:MapView x:Name="MyMapView">
       <esri:Map x:Name="MyMap">
  5. Add the following XAML inside the <Map> element to define the basemap layer (World street map) to display in the map:
    <esri:ArcGISTiledMapServiceLayer ID="BaseMap" 

    The ArcGISTiledMapServiceLayer represents a map layer based on a cached map service hosted by ArcGIS for Server. The ID property provides a unique identifier for the layer that can be used to refer to the layer programmatically, which is something you'll do later in the tutorial. ServiceUri defines the source for the layer. The layer in your map will come from a tiled map service hosted on ArcGIS Online.


    In addition to the World imagery map, ArcGIS Online provides basemaps of streets, topographic data, historical maps, and many others. Visit Living Atlas of the World to browse some of the available basemaps. If you find a basemap you'd like to use in your app, you can copy the service URI from its description page.

  6. Add the following XAML to define the hurricane layer (ArcGISDynamicMapServiceLayer). By adding this XAML below the line that defines the basemap, you are ensuring that it will draw on top of the tiled basemap (world streets) layer.

    <esri:ArcGISDynamicMapServiceLayer ID="Hurricanes" 

  7. You are now ready to test your app.
  8. Click the Start button on the Standard toolbar (or DEBUG > Start Debugging) to start your app. You'll see a map similar to the following:

    Running app showing hurricane activity with a world street map base layer

    The map displays a layer of hurricane activity over the World Street Map basemap from ArcGIS Online. When the app is complete, your user will be able to change the basemap layer while the app is running.

Add a basemap selection control

You will now use standard controls to create a user interface that allows the user to choose which basemap to display in the map.

  1. Drag a ComboBox control from the Visual Studio Toolbox onto the design surface for MainWindow.xaml. Make sure the new ComboBox displays on top of the MapView control.


    To change the draw order for a control, simply change its position in the XAML. Elements that appear below the Map definition in the XAML document, for example, will appear on top of the MapView control.

  2. Edit the XAML for the new ComboBox to contain three new items, as shown in the following code sample. Each item defines a basemap that the user can choose to display in the map.
    <ComboBox HorizontalAlignment="Left" VerticalAlignment="Top" 
              Margin="10,10,0,0" Width="120">
        <ComboBoxItem Content="Streets" IsSelected="True" 
        <ComboBoxItem Content="Topo" 
        <ComboBoxItem Content="Imagery" 
  3. Define a new event handler forthe SelectionChanged event, as shown in the following code sample. As you type, Visual Studio provides IntelliSense to create the event handler for you.
         HorizontalAlignment="Left" VerticalAlignment="Top" 
         Margin="10,10,0,0" Width="120" 
  4. Right-click the name of the handler (ComboBox_SelectionChanged) in the designer, and choose Go To Definition from the context menu.
  5. Add the following code to the ComboBox_SelectionChanged event handler:
    var combo = sender as ComboBox;
    var sel = combo.SelectedItem as ComboBoxItem;
    if (sel.Tag == null) { return;  }
    // Find and remove the current basemap layer from the map
    if (MyMap == null) { return; }
    var oldBasemap = MyMap.Layers["BaseMap"];
    // Create a new basemap layer
    var newBasemap = new Esri.ArcGISRuntime.Layers.ArcGISTiledMapServiceLayer();
    // Set the ServiceUri with the url defined for the ComboBoxItem's Tag
    newBasemap.ServiceUri = sel.Tag.ToString();
    // Give the layer the same ID so it can still be found with the code above
    newBasemap.ID = "BaseMap";
    // Insert the new basemap layer as the first (bottom) layer in the map
    MyMap.Layers.Insert(0, newBasemap);

    The current basemap layer is referenced in the code using the ID value that you assigned in the XAML (BaseMap). A new layer is created, and the Tag property of the selected item is used to set the ServiceUri property. Your XAML defines a Tag for each ComboBoxItem with a URL that points to a basemap service hosted on ArcGIS Online. The same ID is then given to the new layer so the next time the code runs, the current basemap layer can again be found.

    Finally, the new basemap is added to the map's layer collection using the Insert method. This method allows you to specify where in the collection you want the new layer to appear. The Add method can also be used to add a new layer but will always add the layer to the end of the collection (which will appear as the top layer in the map).

Test the basemap selection functionality

You are now ready to test the app.

  1. Click the Start button on the Standard toolbar (or DEBUG > Start Debugging) to start your app.
  2. Choose a different basemap layer from the UI (that is, something other than Streets).

    The map updates to display the new basemap. Notice that the new basemap layer is added to the bottom of the layer display, ensuring that the dynamic layer (hurricanes) is not obscured.

    Hurricane layer over a world image basemap


    You can also use your own basemaps, hosted on ArcGIS Online or with ArcGIS for Server, in your ArcGIS Runtime SDK for .NET apps.

Your app is now complete. By providing a unique ID for each layer in your map, you can reference them later when you need to make a change. You may also find this technique useful when you need to change layer visibility, add a graphic to an existing graphics layer, alter a feature layer's renderer, and so on.

As a next step, consider exploring the functionality provided by ArcGIS Runtime SDK for .NET by stepping through more tutorials or by examining the many samples provided with the SDK.

Related topics