Vue d’ensemble des cartes et des localisations

SDK d'application Windows et WinUI 3 fournissent des API et des contrôles pour afficher des cartes, détecter l'emplacement de l'utilisateur et configurer des limites géographiques. Utilisez ces fonctionnalités pour créer des applications qui affichent des cartes interactives avec des broches, effectuent le suivi de la position de l’utilisateur et déclenchent des actions lorsque l’utilisateur entre ou quitte une zone géographique.

Cet article présente chaque fonctionnalité et inclut un exemple complet qui combine MapControl, Geolocatoret GeofenceMonitor dans une application de travail unique.

Afficher des cartes avec MapControl

MapControl affiche une carte interactive alimentée par Azure Maps. Vous pouvez ajouter des repères, des couches et réagir aux interactions de l’utilisateur, telles que le déplacement, le zoom et le clic.

MapControl nécessite un compte Azure Maps. Consultez Gérer votre compte Azure Maps pour créer un compte et obtenir un jeton de service.

Pour obtenir des instructions d’utilisation détaillées, consultez MapControl.

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

Note

Les API UWP MapControl et Windows.Services.Maps sont déconseillées et pourraient ne plus être disponibles dans les futures versions de Windows. Les applications WinUI 3 doivent utiliser le nouveau MapControl décrit ci-dessus. Pour plus d’informations, consultez Ressources pour les fonctionnalités déconseillées.

Détecter l’emplacement de l’utilisateur

Les API Windows.Devices.Geolocation vous permettent d'obtenir la position géographique de l'appareil. Ces API fonctionnent à la fois dans les applications UWP et SDK d'application Windows (WinUI 3). Vous pouvez:

Obtenez une position unique à l’aide de Geolocator.GetGeopositionAsync.
Suivez les modifications de position au fil du temps à l’aide de l’événement Geolocator.PositionChanged .
Surveillez les changements d’état des visites à l’aide de GeovisitMonitor pour une géolocalisation économe en batterie.

Pour obtenir un guide pas à pas, consultez Obtenir l’emplacement de l’utilisateur.

Configurer des limites géographiques

Une limite géographique définit une limite géographique. Votre application reçoit des notifications lorsque l’utilisateur entre ou quitte la limite. Les limites géographiques sont utiles pour les rappels, alertes ou remise de contenu basés sur l’emplacement.

Pour obtenir des instructions sur la création et la surveillance des limites géographiques, consultez Configurer une limite géographique.

Localisation et confidentialité

Toutes les API d’emplacement nécessitent la fonctionnalité Emplacement déclarée dans le manifeste de package de votre application. Vous devez également appeler Geolocator.RequestAccessAsync au moment de l’exécution avant d’accéder aux données d’emplacement.

Windows permet aux utilisateurs de contrôler les applications qui peuvent accéder à leur position via Paramètres > Confidentialité et sécurité > Localisation. Votre application doit gérer le cas où l’utilisateur refuse ou révoque l’accès à l’emplacement.

Exemple complet

L’exemple suivant rassemble MapControl, Geolocatoret GeofenceMonitor dans une seule fenêtre WinUI 3. Si aucune clé Azure Maps n’est configurée, la carte se dégrade correctement pendant que la géolocalisation et les limites géographiques continuent de fonctionner.

Prerequisites

SDK d'application Windows 2.2 ou version ultérieure
Clé Azure Maps nécessaire pour afficher les vignettes de carte. Sans clé valide, MapControl s’affiche, mais affiche une carte vide.
La fonctionnalité Localisation de l’appareil déclarée dans Package.appxmanifest :

<DeviceCapability Name="location" />

Définissez votre clé Azure Maps en tant que variable d’environnement avant d’exécuter l’application :

$env:AZURE_MAPS_KEY = "your-key-here"

MainWindow.xaml

Panneau de configuration de 300 pixels à gauche avec des boutons et du texte d’état, ainsi qu’un MapControl sur la droite. Une superposition s’affiche lorsque la clé Azure Maps est manquante.

<?xml version="1.0" encoding="utf-8" ?>
<Window
    x:Class="MapLocationDemo.MainWindow"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    Title="Map Location Demo">
    <Window.SystemBackdrop>
        <MicaBackdrop />
    </Window.SystemBackdrop>

    <Grid>
        <Grid.RowDefinitions>
            <RowDefinition Height="Auto" />
            <RowDefinition Height="*" />
        </Grid.RowDefinitions>

        <TitleBar Title="Map Location Demo" />

        <Grid Grid.Row="1">
            <Grid.ColumnDefinitions>
                <ColumnDefinition Width="300" />
                <ColumnDefinition Width="*" />
            </Grid.ColumnDefinitions>

            <Grid Grid.Column="0" Margin="16" RowSpacing="12">
                <Grid.RowDefinitions>
                    <RowDefinition Height="Auto"/>
                    <RowDefinition Height="Auto"/>
                    <RowDefinition Height="Auto"/>
                    <RowDefinition Height="*"/>
                </Grid.RowDefinitions>

                <TextBlock Text="Location Demo" FontSize="20" FontWeight="Bold"/>
                <StackPanel Grid.Row="1" Spacing="8">
                    <Button x:Name="FindMeButton" Content="Find My Location"
                            Click="FindMeButton_Click" HorizontalAlignment="Stretch"/>
                    <Button x:Name="AddGeofenceButton" Content="Add Geofence Here"
                            Click="AddGeofenceButton_Click" HorizontalAlignment="Stretch"/>
                </StackPanel>
                <TextBlock x:Name="StatusText" Grid.Row="2"
                           Text="Click 'Find My Location' to begin." TextWrapping="Wrap"/>
                <ListView x:Name="EventLog" Grid.Row="3" Header="Event Log"/>
            </Grid>

            <Grid Grid.Column="1">
                <MapControl x:Name="MyMap" />
                <StackPanel x:Name="MapKeyMissing" Visibility="Collapsed"
                            HorizontalAlignment="Center" VerticalAlignment="Center"
                            Spacing="8">
                    <FontIcon Glyph="&#xE783;" FontSize="48"
                              HorizontalAlignment="Center"
                              Foreground="{ThemeResource SystemFillColorCautionBrush}" />
                    <TextBlock Text="Azure Maps key not configured"
                               FontSize="18" FontWeight="SemiBold"
                               HorizontalAlignment="Center" />
                    <TextBlock x:Name="MapKeyHint" TextWrapping="Wrap" MaxWidth="400"
                               HorizontalAlignment="Center" TextAlignment="Center"
                               Foreground="{ThemeResource TextFillColorSecondaryBrush}" />
                </StackPanel>
            </Grid>
        </Grid>
    </Grid>
</Window>

MainWindow.xaml.cs

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

namespace MapLocationDemo;

public sealed partial class MainWindow : Window
{
    private Geolocator? _geolocator;
    private BasicGeoposition _lastPosition;
    private bool _mapAvailable;

    public MainWindow()
    {
        InitializeComponent();
        _mapAvailable = TryConfigureMap();
        GeofenceMonitor.Current.GeofenceStateChanged += OnGeofenceStateChanged;
    }

    // Read the Azure Maps key from an environment variable.
    // If missing, collapse the map and show an informational overlay.
    private bool TryConfigureMap()
    {
        var key = Environment.GetEnvironmentVariable("AZURE_MAPS_KEY");
        if (string.IsNullOrWhiteSpace(key))
        {
            MyMap.Visibility = Visibility.Collapsed;
            MapKeyMissing.Visibility = Visibility.Visible;
            MapKeyHint.Text = "Set the AZURE_MAPS_KEY environment variable "
                + "and restart.\nGeolocation and geofencing still work "
                + "without the map.";
            Log("Azure Maps key not found — map disabled");
            return false;
        }
        MyMap.MapServiceToken = key;
        return true;
    }

    private async void FindMeButton_Click(object sender, RoutedEventArgs e)
    {
        FindMeButton.IsEnabled = false;
        StatusText.Text = "Requesting location access...";

        var access = await Geolocator.RequestAccessAsync();
        if (access != GeolocationAccessStatus.Allowed)
        {
            StatusText.Text =
                "Location access denied. Check Settings > Privacy > Location.";
            FindMeButton.IsEnabled = true;
            return;
        }

        _geolocator = new Geolocator { DesiredAccuracyInMeters = 100 };
        try
        {
            var pos = await _geolocator.GetGeopositionAsync();
            var lat = pos.Coordinate.Point.Position.Latitude;
            var lon = pos.Coordinate.Point.Position.Longitude;
            _lastPosition = new BasicGeoposition
            {
                Latitude = lat, Longitude = lon
            };

            StatusText.Text =
                $"Location: {lat:F5}, {lon:F5}  ({pos.Coordinate.Accuracy:F0} m)";
            Log($"Position: {lat:F5}, {lon:F5}");

            if (_mapAvailable)
            {
                var pt = new Geopoint(_lastPosition);
                MyMap.Center = pt;
                MyMap.ZoomLevel = 15;

                var layer = new MapElementsLayer();
                layer.MapElements = new List<MapElement>
                {
                    new MapIcon { Location = pt }
                };
                MyMap.Layers.Clear();
                MyMap.Layers.Add(layer);
            }
        }
        catch (Exception ex) { StatusText.Text = $"Error: {ex.Message}"; }
        finally { FindMeButton.IsEnabled = true; }
    }

    private void AddGeofenceButton_Click(object sender, RoutedEventArgs e)
    {
        if (_lastPosition.Latitude == 0 && _lastPosition.Longitude == 0)
        {
            StatusText.Text = "Get your location first.";
            return;
        }

        var fence = new Geofence("MyGeofence",
            new Geocircle(_lastPosition, 200),
            MonitoredGeofenceStates.Entered | MonitoredGeofenceStates.Exited,
            false, TimeSpan.FromSeconds(5));
        GeofenceMonitor.Current.Geofences.Add(fence);

        StatusText.Text = $"Geofence added at "
            + $"{_lastPosition.Latitude:F5}, {_lastPosition.Longitude:F5}";
        Log("Geofence registered");
    }

    private void OnGeofenceStateChanged(
        GeofenceMonitor sender, object args)
    {
        var reports = sender.ReadReports();
        DispatcherQueue.TryEnqueue(() =>
        {
            foreach (var r in reports)
            {
                var msg = r.NewState switch
                {
                    GeofenceState.Entered => $"Entered: {r.Geofence.Id}",
                    GeofenceState.Exited  => $"Exited: {r.Geofence.Id}",
                    GeofenceState.Removed => $"Removed: {r.Geofence.Id}",
                    _ => null
                };
                if (msg != null) { StatusText.Text = msg; Log(msg); }
            }
        });
    }

    private void Log(string msg) =>
        EventLog.Items.Insert(0, $"[{DateTime.Now:HH:mm:ss}] {msg}");
}

Modèles clés

MapControlest intégré à SDK d'application Windows 1.6 et versions ultérieures. Définissez MapServiceToken sur votre clé Azure Maps.
TryConfigureMap vérifie la variable d’environnement AZURE_MAPS_KEY au démarrage. Si la variable est vide, la carte se replie et un message superposé explique comment résoudre le problème — sans plantage, pas de carte vide.
DeviceCapability Name="location" in Package.appxmanifest est obligatoire ou Geolocator.RequestAccessAsync renvoie Denied.
GeofenceMonitor.GeofenceStateChanged s’exécute sur un thread d’arrière-plan, utilisez donc DispatcherQueue.TryEnqueue pour mettre à jour l’interface utilisateur.

MapControl
Obtenir la localisation de l’utilisateur
Configurer une limite géographique
Documentation d'Azure Maps

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-07-07