Quick Start

This guide gets an interactive map on screen and a marker placed in just a few lines.

Tip

Pick your UI framework with the switcher in the header: WPF, WinForms, Blazor or .NET MAUI. Every code sample on the site then shows that framework, and your choice is remembered as you move between pages.

Prerequisites

.NET 10 SDK
A free beta license key. Request one on the TMS.NET Maps page.
A provider API key (e.g. a Google Maps key). Map providers such as Leaflet / OpenStreetMap work without a key; see Providers.

1. Install

The open beta is published on nuget.org as one self-contained .Trial package per UI framework. It contains the map control and all services. Install exactly one per project: the Trial packages are mutually exclusive with each other and with the individual TMS.Maps.* packages.

They are prerelease packages, so pass --prerelease to the .NET CLI, or tick Include prerelease in Visual Studio's Manage NuGet Packages dialog.

dotnet add package TMS.Maps.Wpf.Trial --prerelease

dotnet add package TMS.Maps.WinForms.Trial --prerelease

dotnet add package TMS.Maps.Blazor.Trial --prerelease

dotnet add package TMS.Maps.Maui.Trial --prerelease

The MAUI package supports every MAUI target: Android, iOS, Mac Catalyst and Windows.

2. Register your license key

Call RegisterLicense(string) once at startup, before any map control or service is created. The key is checked offline.

In App.xaml.cs:

using TMS.Maps.Core.Licensing;

public partial class App : Application
{
    protected override void OnStartup(StartupEventArgs e)
    {
        TMSLicensing.RegisterLicense("YOUR-BETA-LICENSE-KEY");
        base.OnStartup(e);
    }
}

In Program.cs:

using TMS.Maps.Core.Licensing;

[STAThread]
static void Main()
{
    TMSLicensing.RegisterLicense("YOUR-BETA-LICENSE-KEY");

    ApplicationConfiguration.Initialize();
    Application.Run(new MainForm());
}

In Program.cs (for Blazor WebAssembly, the client project's Program.cs):

using TMS.Maps.Core.Licensing;

TMSLicensing.RegisterLicense("YOUR-BETA-LICENSE-KEY");

var builder = WebApplication.CreateBuilder(args);
// ...

In MauiProgram.cs:

using TMS.Maps.Core.Licensing;

public static MauiApp CreateMauiApp()
{
    TMSLicensing.RegisterLicense("YOUR-BETA-LICENSE-KEY");

    var builder = MauiApp.CreateBuilder();
    builder.UseMauiApp<App>();
    return builder.Build();
}

With a valid key the map shows a "TMS .NET Maps BETA — expires date" strip across its bottom edge, with links to this documentation and to the support forum, and on WPF, WinForms and MAUI the first map in each app run shows a native beta welcome dialog. Without a key (or once it expires) the map shows a "Map unavailable" panel instead, with a link to request a license key (also offered in a native dialog at startup on WPF, WinForms and MAUI), and every service call throws TMSLicensingException. A key that is not a valid license token makes RegisterLicense itself throw TMSLicensingException; an expired key does not throw but is reported by Status.

3. Add the map control

In XAML, reference the control from the Trial package's single assembly: TMS.Maps.Wpf for WPF and TMS.Maps.Maui for MAUI.

<Window x:Class="MyApp.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:maps="clr-namespace:TMS.Maps.Wpf;assembly=TMS.Maps.Wpf">
    <maps:MapControl x:Name="Map"
                     Provider="Google"
                     ApiKey="YOUR_API_KEY"
                     CenterLatitude="37.7749"
                     CenterLongitude="-122.4194"
                     ZoomLevel="12" />
</Window>

using TMS.Maps.Core.Models;
using TMS.Maps.WinForms;

public partial class MainForm : Form
{
    private readonly MapControl _map;

    public MainForm()
    {
        InitializeComponent();

        _map = new MapControl
        {
            Dock = DockStyle.Fill,
            Provider = Providers.Google,
            ApiKey = "YOUR_API_KEY",
            CenterLatitude = 37.7749,
            CenterLongitude = -122.4194,
            ZoomLevel = 12
        };
        Controls.Add(_map);
    }
}

@using TMS.Maps.Core.Models
@using TMS.Maps.UI.Web

<MapControl @ref="_map"
            Provider="Providers.Google"
            ApiKey="YOUR_API_KEY"
            CenterLatitude="37.7749"
            CenterLongitude="-122.4194"
            ZoomLevel="12"
            Width="100%"
            Height="600px" />

@code {
    private MapControl? _map;
}

<ContentPage x:Class="MyApp.MainPage"
             xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:maps="clr-namespace:TMS.Maps.Maui;assembly=TMS.Maps.Maui">
    <maps:MapControl x:Name="Map"
                     Provider="Google"
                     ApiKey="YOUR_API_KEY"
                     CenterLatitude="37.7749"
                     CenterLongitude="-122.4194"
                     ZoomLevel="12" />
</ContentPage>

4. Drop a marker once the map is ready

Wait for the map's ready event before calling its methods, then add a marker.

public MainWindow()
{
    InitializeComponent();

    Map.MapReady += async (_, _) =>
        await Map.AddMarkerAsync(37.7749, -122.4194, "San Francisco");
}

_map.MapReady += async (_, _) =>
    await _map.AddMarkerAsync(37.7749, -122.4194, "San Francisco");

<MapControl @ref="_map"
            Provider="Providers.Google"
            ApiKey="YOUR_API_KEY"
            CenterLatitude="37.7749"
            CenterLongitude="-122.4194"
            OnMapReady="OnMapReady"
            Width="100%"
            Height="600px" />

@code {
    private MapControl? _map;

    private async Task OnMapReady()
    {
        if (_map is not null)
            await _map.AddMarkerAsync(37.7749, -122.4194, "San Francisco");
    }
}

public MainPage()
{
    InitializeComponent();

    Map.MapReady += async (_, _) =>
        await Map.AddMarkerAsync(37.7749, -122.4194, "San Francisco");
}

Next steps

Working with the map — markers, shapes, clustering, heatmaps and events.
Calling the services — geocoding, directions, elevation, places, static maps and location.
Privacy & network access — which hosts the controls contact, and the limits of the free map styles.
Browse the full API reference.

Note

This is an open beta evaluation release. APIs may change before general availability.