Edit

Share via

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

Open the WinUI 3 Gallery app and see the MapControl in action

WinUI 3 Gallery icon The WinUI 3 Gallery app includes interactive examples of WinUI controls and features. Get the app from the Microsoft Store or browse the source code on GitHub.

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.");
};
  • Last updated on