Add a map to your app

At the heart of most ArcGIS Runtime SDK for .NET apps are the MapView and Map controls. These controls allow you to easily add a map to your app with a few lines of XAML or .NET code. See the Use the MapView to display a map topic for details about using these controls.

This tutorial guides you through the process of creating a Hello, World Map app using Microsoft Visual Studio and the ArcGIS Runtime API. It introduces you to the basics of working with ArcGIS Runtime SDK for .NET and describes fundamental principles to help your future app development. Your completed app will contain a simple map that displays at a specified initial extent when opened.


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 is recommended but not required.

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 HelloWorldMap.

    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 HelloWorldMap project listing in the Visual Studio Solution Explorer window, and click Add Reference in the context menu.

    Visual Studio Add Reference menu choice

  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.

Hello, World!

Now that you've created a blank project and referenced ArcGIS Runtime SDK for .NET, 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 this tutorial, you'll display street data from a public map service provided by ArcGIS Online.

    To use the library in the XAML designer, you must first make a reference to the XML namespace for ArcGIS Runtime.
  1. Double click the MainWindow.xaml file in the Visual Studio Solution Explorer to open it in the 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.

    XAML namespace declaration

  3. Next, you'll add a MapView control and define a layer to display.
  4. Add the following XAML inside the <Grid> element to define a new MapView control and Map on the page:
    <esri:MapView x:Name="MyMapView">
       <esri:Map x:Name="MyMap">
  5. Add the following XAML inside the <Map> element to define a new layer 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 (although you won't need to in this 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. You are now ready to test your app.
  7. 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:

    App showing the world streets map at full extent

    By default, the map displays at the full extent of the first (bottom) layer it contains. To show the initial view of the map at a particular location, you can add logic to the map's XAML or programmatically adjust the extent when the app starts. To practice setting the initial extent, proceed to the next section.

Hello, Cleveland!

As a finishing touch to your app, you will add a ViewpointExtent element to the map's XAML to define the extent at which the map should initially be displayed.

  1. Add the following XAML inside your Map element. It can go either before or after the existing ArcGISTiledMapServiceLayer element.

        <esri:ViewpointExtent XMin="-9113800"

    The previous XAML sets the map's InitialViewpoint property with an ViewpointExtent element that defines the desired extent (centered on Cleveland, Ohio USA). The dimensions of the envelope are specified with Web Mercator coordinate values to match the coordinate system of the map.

  2. Run the app again. The map displays with an initial extent centered on Cleveland Ohio, as shown in the following screen capture:

    Street map of Cleveland

Here is the complete XAML for the app:

<Window x:Class="HelloWorldMap.MainWindow"
        Title="MainWindow" Height="350" Width="525">

            <esri:Map x:Name="MyMap">
                     <esri:ViewpointExtent XMin="-9113800"
                <esri:ArcGISTiledMapServiceLayer ID="BaseLayer" 

That's it. You created a simple map app with only a few lines of XAML. As a next step, consider exploring the functionality provided by ArcGIS Runtime SDK for .NET by stepping through more advanced tutorials or by examining the many samples provided with the SDK.

Related topics