Skip To Content ArcGIS for Developers Sign In Dashboard

Build a new map

A map gives you a structure for organizing your geographical data so your users can view, explore, and interact with it. This page describes how to design and build a map with code and then save it for later use by another app or by a different user.


You can also create a map for use in your ArcGIS Runtime app using ArcGIS Online's map viewer (how-to steps are in ArcGIS Online Help's Get started with maps page).

To build a map with code for your ArcGIS Runtime app, you use this API to create a map. In this API, the map is represented by the Map class that gives you all the methods and properties you need to set the background layer, add the operational layers, set the spatial reference, add bookmarks, and save the map. If you wish to display the map and allow users to interact with it then you pass the map to the MapView class.

Map design considerations

When designing a map you must:

  • Choose a background for your map so that your users can orient themselves. Esri provides a number of standard basemaps that you can use as a background or you can use other providers, such as your organization's basemaps. Alternatively, you can construct a basemap in code.
  • Ensure that you specify a spatial reference for your map that allows the layers to be aligned and displayed together. It will be more efficient if all of your operational layers have the same spatial reference as the map and basemap because the operational layers will not need to be reprojected.
  • Start the map display in a specific and recognizable geographical area.
  • Only show the data that your users need.
    • Set the minimum and maximum scale thresholds for layers so only useful information is displayed at each scale.
    • You may wish to set a map reference scale. The reference scale of the map is the scale at which a user should view the map for the feature symbols and text to appear at their authored size. By setting a reference scale, layers and labels will not resize based on changes of scale in the map view.

Construct the map

This API provides several types of map constructors. Your choice will depend upon whether you wish to specify the desired basemap, spatial reference or initial viewpoint when you create the map. There is the all-encompassing constructor that you can use to create a map with a standard Esri Imagery basemap that is centered on a latitude and longitude location and zoomed into a specific level of detail.

// create a map centered on Corsica
var myNewMap = new Map(
    BasemapType.Imagery, // use the Imagery basemap
    42.175131,           // latitude
    9.192313,            // longitude
    8                    // level of detail (lower number = smaller scale)

In this example BasemapType.Imagery refers to the ArcGIS Online service available at the REST end point This basemap, like all the standard Esri basemaps, uses the Web Mercator spatial reference and this, in turn, determines the spatial reference of the map. The latitude and longitude values center the map at a particular location and the levelOfDetail determines the scale of data that is displayed. So, this constructor will display a map at a specified location and scale no matter what size of map is displayed to the user.

Other map constructors

There are a number of other map constructors that you can use if you want to set the spatial reference, the basemap or the initial viewpoint at a later point in time. Your choice depends on the workflow in your app. Use this constructor if you:

  • Know the basemap but not the starting location
    // create a map that uses the National Geographic base map
    var myNewMap = new Map(Basemap.CreateNationalGeographic());
  • Know the spatial reference but not the basemap
    // create a map that uses the Everest Bangladesh spatial reference
    var myNewMap = new Map(SpatialReference.Create(37202));
  • Want an empty map
    // create a map without a basemap, layers, or spatial reference
    var myNewMap = new Map();

Create a basemap

A basemap is composed of a collection of base layers and reference layers. The base layer can give your map a recognizable background so that your operational layers are displayed in context. The reference layer can display useful text labels such as the city, street, river or mountain names.

Base layers are displayed at the bottom of a map, and reference layers are displayed at the top, with the map’s operational layers sandwiched between them. The content of a basemap is typically static and does not change frequently so tiled layers make good basemap layers as they provide faster access to relatively static maps. (For more information see Layer types.) As discussed previously, ArcGIS Online provides a number of ready-to-use standard basemaps such as the World imagery, topographic, oceans, streets, and so on. Or, you can add basemaps from your organization or another public service. Also, you can create your own basemap by combining (mashing up) layers.

Standard ArcGIS Online basemaps

To use, instantiate a basemap, such as the ArcGIS Online World Streets basemap.

// create a new (empty) map
var myMap = new Map();
// create a streets basemap
var streetsBasemap = Basemap.CreateStreets();
// add the basemap to the map
myMap.Basemap = streetsBasemap;

A single layer

You can also instantiate a basemap with a single layer. For example, you could instantiate a tiled layer, construct a basemap from that layer and then pass that basemap to the map.

// create a new tiled layer
var imageryTiledLayer = new ArcGISTiledLayer(new Uri(""));
// create a basemap from the tiled layer
var myBasemap = new Basemap(imageryTiledLayer);
// create a new map; set the basemap
var myMap = new Map();
myMap.Basemap = myBasemap;

Combining layers into one basemap

You can combine a number of layers to create a single basemap as long as the layers are capable of being displayed in the same spatial reference (that is, either a layer is already in the same spatial reference as the other layers or it can be re-projected to the spatial reference of the other layers). In the following code example, the first layer added to the set of basemap layers establishes the spatial reference of the basemap, making it 3857 (you can see this number if you enter the URI in the code sample into your browser's address box and look for "spatial reference" in the resulting page). The second basemap layer, being a map image layer, is requested from the map server in spatial reference set by the first layer, 3857.

// create two layers
var imageTiledLayer = new ArcGISTiledLayer(new Uri(""));
var censusLayer = new ArcGISMapImageLayer(new Uri(""));
  // create a new basemap; add the layers (BaseLayers property)
var myBasemap = new Basemap();
  // create a new Map to display the basemap
var myMap = new Map(myBasemap);


In terms of the map's spatial reference, it's important to understand the following:

  • If a map does not have a spatial reference, it will automatically be set by the map's first basemap.
  • If you add a basemap to a map that already has a spatial reference, it must have the same spatial reference as the map; otherwise it will fail to draw. The same is true if you exchange one basemap for another.
  • If the map does not have a basemap, then the map will adopt the spatial reference of the first operational layer that is added to the map.

Just like the map, the basemap loads asynchronously. This is described in more detail in the loadable pattern topic.

A group layer cannot be included in a basemap.

Add operational layers

Operational layers are a category of layers that provide geographic content that is of specific interest to the app. Your choice of layer type will determine whether you can edit, query, identify or overwrite the layer rendering. For more information about the types of operational layers please refer to the topic Layer types. Typically, operational layers contain data that changes more frequently than that of a basemap.

To add an operational layer to the map, add the layer to the map's operational layers list.

// create a service feature table of wildfire response areas
var wildfireResponseUri = new Uri("");
var wildfireAreasFeatureTable = new ServiceFeatureTable(wildfireResponseUri);

// create a new feature layer from the table
var wildfireAreasLayer = new FeatureLayer(wildfireAreasFeatureTable);

// add the layer to the OperationalLayers collection in the map
A layer that is added first is placed directly above the basemap and is in the 0th position in the map's operational layers list. If you add additional layers they are placed above the last layer and their position will be incremented by one. So the next layer will be in the first, then the next in the second position, and so on.


If your code adds operational layers to an existing map, the map’s original list of operational layers is overridden to contain only the added layers. To keep the map’s original operational layers and add new ones, wait until the map is loaded before adding operational layers. You can declare new operational layers outside the map’s declaration, and use a signal handler to wait for the map to finish loading before adding the new layers. See the next section of this topic for details about loading a map and its layers.

If you wish to, you can insert a layer into the list of operational layers at a specific position.

// insert a layer into a specified position of the OperationalLayers collection
//myMap.OperationalLayers.Insert(3, wildfireAreasLayer);

All operational layers are added to the map in the same way and also conform to the asynchronous loading pattern as detailed in the Loadable pattern topic.

Operational layer properties

Each operational layer has a set of default properties. You can modify these properties so that they are more appropriate for your map. For example, you can:

  • Set the maximum and minimum scale at which the layer is visible.
  • Change the opacity of the layer.
  • Change the visibility of the layer.
  • Override the rendering.
  • Specify a definition expression.
  • Change the order in which the layers are displayed in the map.

By adding operational layers to a group layer, you can control some of these properties on a group of layers simultaneously.

For more information please explore the specific layer and sublayer classes.

Load the map and its layers

The map has been designed to load as quickly as possible. You will be able to access the map and set its properties and iterate through its layers even if a layer has failed or a layer's service response is slow. One broken layer should not prevent the entire map from being used. A map should not load layers that are not needed. The advantage of this design is that the map can be used without having to wait for all of the layer's to be available.

When you construct the map, its load status will be NotLoaded. You can load the map (initiate the map's load cycle) either by:

  • Calling LoadAsync on the map
    // load the map
    // check the load status and display an error message if necessary
    if (myNewMap.LoadStatus == LoadStatus.FailedToLoad)
        StatusTextBlock.Text = "Unable to load map.";
  • Or, by setting the map on the mapview.
    MyMapView.Map = myNewMap;

Upon completion of the map's load cycle, the map's load status will be Loaded, indicating that:

  • The map's spatial reference has been defined by the basemap's spatial reference. The Esri basemaps defined in the API all use Web Mercator.
  • The map's initial viewpoint has been specified, for example, by setting the map's latitude, longitude and level of detail. (The levelOfDetail value sets the scale or resolution at which the map is displayed.)
  • The map's list of layers has been created.

The map can be in a loaded state and ready for user interaction even if the individual layers have not finished loading. The map's layers could be in a Loaded, NotLoaded, or FailedToLoad state. Please explore the Loadable pattern for more information on loading maps and layers.

Save the map to a portal

You have designed and built a map. Now you can save the map so you, or other users, can view at a later time. To save the map to the ArcGIS Enterprise portal or your organization's portal the following conditions must be met:

  • The map must be in a loaded state.
  • Any layers that you wish to save must be in a loaded state.
  • You must be authenticated to a portal.

Have the map and layers been loaded?

Before attempting to save the map it is prudent to confirm that the map is loaded and that the layers are loaded. If a layer has failed to load you may decide to save the map without the layer or investigate why you cannot access the layer. This will depend on your workflow.


If a layer has an invalid URL then the layer will have a layer type of Unknown Layer. This layer will not be saved to the map.

// check the map load status and display an error message if necessary
if (myNewMap.LoadStatus == LoadStatus.NotLoaded)
    StatusTextBlock.Text = "Map is not loaded.";

// see if the map layers loaded successfully
foreach(var lyr in myNewMap.AllLayers)
    // report errors for layers that didn't load
    if(lyr.LoadStatus == LoadStatus.FailedToLoad)
        StatusTextBlock.Text = "Error loading layer " + lyr.Name + 
            ": " + lyr.LoadError.Message;

Has the user authenticated with the portal?

When your user authenticates to a portal (including ArcGIS Online) they have access to the maps that they own. When they log into ArcGIS Online or ArcGIS Enterprise portal, these maps are visible in a set of folders under the My Content tab. In ArcGIS Enterprise portal, the My Content filter is selected by default. When a user saves a map with this API, the map is saved into a folder under My Content and is accessible from there.

To authenticate a user to a portal you must create a portal object, provide the essential credentials and then asynchronously load the portal. Just like map and layer classes, the ArcGISPortal class conforms to the Loadable pattern.

// get the user credentials (username and password); add it to the authentication manager
var cred = await AuthenticationManager.Current.GenerateCredentialAsync(
    new Uri(PortalUriTextBox.Text),

// pass the credentials (token) and create the portal instance
var myPortal = await ArcGISPortal.CreateAsync(new Uri(PortalUriTextBox.Text), cred, CancellationToken.None);

For more information on authenticating with a portal, see Access the ArcGIS Platform.

Save the map

Saving a map to the portal creates a new web map portal item. The map is placed in a folder of your choice in the My Content area of the authenticated user. For full details on how to save the map to a portal, see Save a map.

Share the map

By default, the map that the user adds to the portal is only accessible to that user. The map is not available to others. For example, the map does not appear in search results and is not part of any group. There are several options for sharing a map. The options are described in the Share a portal item topic.

Related topics