Skip to content

map-control.md

Latest commit

 

History

History
135 lines (100 loc) · 5.13 KB

map-control.md

File metadata and controls

135 lines (100 loc) · 5.13 KB
description Displays a symbolic map of the Earth using Azure Maps, with support for pins, layers, and interactive controls.
title MapControl
template detail.hbs
ms.date 02/20/2026
ms.topic article

MapControl

The MapControl displays a symbolic, interactive map of the Earth powered by Azure Maps. You can show locations, add pins and custom layers, and let users interact with the map using pan, zoom, rotation, and pitch controls.

The MapControl requires an Azure Maps account. Follow the instructions at Manage your Azure Maps account to create an account and obtain a map service token.

Is this the right control?

Use a MapControl when you want to display geographic data in your app, such as:

  • Showing a location on a map with a pin.
  • Displaying a collection of points of interest.
  • Providing an interactive map experience with zoom and pan.

Create a MapControl

[!div class="checklist"]

[!div class="nextstepaction"] Open the WinUI 3 Gallery app and see the MapControl in action

[!INCLUDE winui-3-gallery]

Add a MapControl to your page and set the MapServiceToken to your Azure Maps key.

<MapControl x:Name="myMap"
            MapServiceToken="YOUR_AZURE_MAPS_TOKEN"
            Height="400" />

Set the map location

Set the Center and ZoomLevel properties to control what the map displays.

using Windows.Devices.Geolocation;

var position = new BasicGeoposition { Latitude = 47.6062, Longitude = -122.3321 };
myMap.Center = new Geopoint(position);
myMap.ZoomLevel = 12;
<!-- Set initial center and zoom in XAML is not supported; set in code-behind -->
<MapControl x:Name="myMap"
            MapServiceToken="YOUR_AZURE_MAPS_TOKEN"
            Height="400" />

Add pins to the map

Use MapIcon to display pushpins on the map. Add icons to a MapElementsLayer, then add the layer to the map's Layers collection.

using Windows.Devices.Geolocation;
using Microsoft.UI.Xaml.Controls;
using System.Collections.Generic;

var position = new BasicGeoposition
{
    Latitude = 47.6062,
    Longitude = -122.3321
};

var icon = new MapIcon
{
    Location = new Geopoint(position),
};

var layer = new MapElementsLayer
{
    MapElements = new List<MapElement> { icon }
};

myMap.Layers.Add(layer);

Show or hide interactive controls

The InteractiveControlsVisible property controls whether the map displays built-in overlay controls for zoom, rotation, pitch, and map style.

<MapControl x:Name="myMap"
            MapServiceToken="YOUR_AZURE_MAPS_TOKEN"
            InteractiveControlsVisible="True"
            Height="400" />

Handle map element clicks

Subscribe to the MapElementClick event to respond when the user clicks a map element such as a pin.

myMap.MapElementClick += (sender, args) =>
{
    foreach (var element in args.MapElements)
    {
        if (element is MapIcon clickedIcon)
        {
            // Handle the clicked icon
        }
    }
};

Handle map service errors

Subscribe to the MapServiceErrorOccurred event to detect issues communicating with the map service, such as an invalid or missing MapServiceToken.

myMap.MapServiceErrorOccurred += (sender, args) =>
{
    // Log or display the error
    System.Diagnostics.Debug.WriteLine("Map service error occurred.");
};

Related articles