Skip To Content

Use ArcGIS basemaps

In this topic

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 Windows Phone app

You'll use Visual Studio to create a Windows Phone 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 Store Apps > Windows Phone Apps > Blank App (Windows Phone) 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 Phone projects under Windows 8 > Windows Phone


    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 page called MainPage.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 ArcGIS Runtime for Windows Phone assembly under Windows Phone 8.1 > Extensions.

    Visual Studio Reference Manager dialog box

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

    Visual Studio project references

  10. Note:

    In order for your app to build, you need to specify a build target for the project. The default value of Any CPU will not work and is why the new references are shown with a yellow warning icon.

    You will now specify a build platform for the app.

  11. Choose BUILD > Configuration Manager.
  12. Choose x86 in the Active solution platform drop-down menu. This will target a 32-bit platform for the app.

    Visual Studio Configuration Manager dialog box

  13. Click Close in the Configuration Manager dialog box.

    The warning icons no longer appear in the Solution Explorer window for these references.

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 MainPage.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 Page XAML element. Visual Studio offers IntelliSense to help complete the URL portion of the statement.
  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:
    <layers: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.

    <layers: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 basemap

    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. In MainPage.xaml, add a new StackPanel control below your MapView, and give it a name of BasemapChoices.


    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.

        <esri:MapView x:Name="MyMapView">
            <esri:Map x:Name="MyMap">
                <layers:ArcGISTiledMapServiceLayer ID="BaseMap" 
                <layers:ArcGISDynamicMapServiceLayer ID="Hurricanes" 
        <StackPanel x:Name="BasemapChoices">

  2. Add three new RadioButton controls in the BasemapChoicesStackPanel. Set the control properties as shown in the following code sample to provide a URL for new basemaps the user can display in the map.
    <RadioButton Content="Streets" IsChecked="true" 
     <RadioButton Content="Imagery" 
     <RadioButton Content="Topo"
    Visual Studio design view of UI
  3. Define a new event handler foreach control's Checked event, as shown in the following code sample. As you type, Visual Studio provides IntelliSense to create the event handler for you.
    <RadioButton Content="Streets" IsChecked="true" Checked="RadioButton_Checked"
     <RadioButton Content="Imagery" Checked="RadioButton_Checked"
     <RadioButton Content="Topo" Checked="RadioButton_Checked"
  4. Right-click the name of the handler (RadioButton_Checked) in the designer, and choose Go To Definition from the context menu.
  5. Add the following code to the RadioButton_Checked event handler:
    var radioButton = sender as RadioButton;
    if (radioButton.Tag == null) { return; }
    var url = radioButton.Tag.ToString();
    // Find and remove the current basemap layer from the map
    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 = url;
    // 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 RadioButton 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 imagery 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