Quickstart Guides¶

• WebAPI Quickstart
• Blazor Quickstart

Quick Start: Display a Simple Map on WebAPI¶

We will begin by creating an ASP.NET Core Web API project on .NET 10 as the service and a simple HTML-based sample with Leaflet to consume the service. Next, we will walk you through adding the required packages and getting a Restful map service. Then, we will add some code to show a nice looking background map, and finally, add some custom data to the map and style it. After reading this, you will be in a good position to look over the How Do I Sample and explore our other features.

Step 1: Setup a New Project¶

In Visual Studio 2026, create a new project from the ASP.NET Core Web API template and name it WebApiSample. On the Additional information page, choose .NET 10.0 as the framework and check Use controllers; leave the other options as they are. Microsoft's Create a controller-based web API tutorial walks through these screens.

From the dotnet CLI, this creates the same project:

dotnet new webapi --use-controllers -o WebApiSample

Step 2: Add NuGet Packages¶

You will need to install the ThinkGeo.UI.WebApi NuGet package in your ASP.NET Core Web API project. We highly suggest you use your editor's built in NuGet package manager if possible. If you're not using an IDE you can install it via the dotnet CLI from inside your project folder where your project file exists.

dotnet add package ThinkGeo.UI.WebApi

Step 3: Prepare spatial data required¶

Download capital.zip and extract its five files into a new folder named Data in your project folder, next to WebApiSample.csproj.

The service reads the files from the folder it runs in, so let the build copy them there: open WebApiSample.csproj and add this ItemGroup before </Project>.

  <!-- The sample data is copied next to the app on build and publish, where the code reads it. -->
  <ItemGroup>
    <None Update="Data\**" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
  </ItemGroup>

Step 4: Create the Map API Controller¶

In Visual Studio, right-click the Controllers folder, choose Add > Controller..., pick the API Controller - Empty template and name it MapServiceController.cs. From the dotnet CLI, run this in your project folder:

dotnet new apicontroller -n MapServiceController -o Controllers -p:n WebApiSample.Controllers

Replace the content of MapServiceController.cs with the code below. The GetTile action serves map tiles drawn with the map data "capital.shp", following the Mercator projection:

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using ThinkGeo.Core;
using ThinkGeo.UI.WebApi;

namespace WebApiSample.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class MapServiceController : ControllerBase
    {
        [Route("{z}/{x}/{y}")]
        [HttpGet]
        public async Task<IActionResult> GetTile(int z, int x, int y)
        {
            // Create the LayerOverlay for displaying the map.
            LayerOverlay capitalOverlay = new LayerOverlay();

            // Create the point layer for capitals.
            ShapeFileFeatureLayer capitalFeatureLayer = new ShapeFileFeatureLayer(Path.Combine(AppContext.BaseDirectory, "Data", "capital.shp"));
            // Create the "Mercator projection" and apply it to the layer to match the background map.
            capitalFeatureLayer.FeatureSource.ProjectionConverter = new ProjectionConverter(Projection.GetWgs84ProjString(), Projection.GetSphericalMercatorProjString());

            // Create the point style for positions.
            capitalFeatureLayer.ZoomLevelSet.ZoomLevel01.DefaultPointStyle = new PointStyle(PointSymbolType.Circle, 4, new GeoSolidBrush(GeoColor.FromHtml("#21FF00")), new GeoPen(GeoColor.FromHtml("#ffffff"), 1));
            // Create the labeling style for capitals.
            capitalFeatureLayer.ZoomLevelSet.ZoomLevel01.DefaultTextStyle = new TextStyle("CITY_NAME", new GeoFont("Arial", 14), new GeoSolidBrush(GeoColor.FromHtml("#21FF00")));
            capitalFeatureLayer.ZoomLevelSet.ZoomLevel01.DefaultTextStyle.YOffsetInPixel = 5;
            capitalFeatureLayer.ZoomLevelSet.ZoomLevel01.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level20;
            // Set DrawingMarginPercentage to a proper value to avoid some labels are cut-off
            capitalFeatureLayer.DrawingMarginInPixel = 300;
            capitalOverlay.Layers.Add("street", capitalFeatureLayer);

            // Draw the overlay into a 256 x 256 PNG for the tile's extent.
            RectangleShape boundingBox = WebApiExtentHelper.GetBoundingBoxForXyz(x, y, z, GeographyUnit.Meter);
            byte[] imageBytes = await capitalOverlay.GetImageAsync(256, 256, boundingBox, HttpContext.RequestAborted);

            return File(imageBytes, "image/png");
        }
    }
}

Now run the project. The console window shows the address it listens on, for example Now listening on: http://localhost:5291; the same addresses are in Properties/launchSettings.json. Open http://localhost:{PortNumber}/api/mapservice/3/2/3 in your browser to see one tile of capitals.

Step 5: Create HTML page "default.html" as client to consume the service¶

Save the page below as default.html in a folder outside your project, and open it in your browser from there; double-clicking the file is enough.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>ThinkGeo Web API Quick Start</title>
    <link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" />
    <style>
        #map { width: 800px; height: 600px; }
    </style>
</head>
<body>
    <div id="map"></div>

    <script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>
    <script>
        // Create the map.
        var map = L.map('map').setView([33.1010, -96.8134], 4);

        // Add ThinkGeo Cloud Maps aerial imagery as the background map.
        var cloudApiKey = 'YOUR THINKGEO CLOUD MAPS API KEY';
        L.tileLayer('https://cloud.thinkgeo.com/api/v2/maps/raster/aerial/x1/3857/512/{z}/{x}/{y}.jpeg?apikey=' + cloudApiKey).addTo(map);

        // Add the capitals, drawn by the MapService controller of your Web API project.
        L.tileLayer('http://localhost:{PortNumber}/api/mapservice/{z}/{x}/{y}').addTo(map);
    </script>
</body>
</html>

Set cloudApiKey to your ThinkGeo Cloud API key, and change {PortNumber} to the port of the http://localhost address your project listens on. That's it! You have a working Leaflet map now.

NOTE: It requires an APIKey of ThinkGeo Cloud, and you can get the API Key from the registration email. If you don't have an account of ThinkGeo Cloud yet, please refer to ThinkGeo Cloud Maps client keys guide to get your ThinkGeo Cloud account.

Now run the ASP.NET Core Web API project. You don't need to register or install anything first: ThinkGeo 15 checks its license when your project builds, not when it runs.

• Without a license key, the first build on your machine starts a free 30-day trial. The build succeeds with warning TG0001, which tells you how many days of the trial are left, and the map shows a Not Licensed for Runtime watermark. After 30 days the build stops with error TG0002 until a key is in place.
• With a license key, the watermark goes away. Sign in at helpdesk.thinkgeo.com, download your Web key (web.thinkgeokey) and save it, with its name unchanged, in %LOCALAPPDATA%\ThinkGeo\ on Windows, or in ~/.thinkgeo/ on macOS and Linux. Then build again. There is nothing to activate, and nothing to install on the server you deploy to.

The License Guide for ThinkGeo 15 explains how to get your key, what each TG build message means and how to build on a build server. If you used ThinkGeo 14 before: Product Center and runtime license files are no longer used, see What Changed from ThinkGeo 14.

You should now see your map with our Cloud Maps layer!

Step 6: Deploy the Services in Docker¶

Deploying services in Docker offers a convenient deployment solution. ThinkGeo draws maps with SkiaSharp, which needs the fontconfig library that the .NET images do not include, so the Dockerfile installs it first.

Save the file below as Dockerfile in your project folder, next to WebApiSample.csproj. If Visual Studio already created a Dockerfile for the project, replace its content.

# The .NET 10 images are based on Ubuntu 24.04.
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base

# Use the 'root' account to install fontconfig, which SkiaSharp needs; it brings FreeType and the DejaVu fonts too.
USER root
RUN apt-get update
RUN apt-get install -y --no-install-recommends libfontconfig1

# Switch back to the 'app' account to run the service.
USER app
WORKDIR /app
EXPOSE 8080
EXPOSE 8081

FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
ARG BUILD_CONFIGURATION=Release
WORKDIR /src
COPY ["WebApiSample/WebApiSample.csproj", "WebApiSample/"]
RUN dotnet restore "./WebApiSample/WebApiSample.csproj"
COPY . .
WORKDIR "/src/WebApiSample"
RUN dotnet build "./WebApiSample.csproj" -c $BUILD_CONFIGURATION -o /app/build

FROM build AS publish
ARG BUILD_CONFIGURATION=Release
RUN dotnet publish "./WebApiSample.csproj" -c $BUILD_CONFIGURATION -o /app/publish /p:UseAppHost=false

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "WebApiSample.dll"]

Build the image and start a container from the folder that holds your WebApiSample project folder (in Visual Studio, the solution folder):

docker build -f WebApiSample/Dockerfile -t webapisample .
docker run -p 8080:8080 webapisample

In default.html, change the capitals layer to http://localhost:8080/api/mapservice/{z}/{x}/{y} and reload the page.

NOTE: This Dockerfile builds the project inside the container, where your license key file is not available, so that build runs on the 30-day trial: it succeeds with warning TG0001 and the map shows a Not Licensed for Runtime watermark. To build with your key, pass it to the build as a secret, as shown in Build Servers, CI and Containers.

You should now see your map consuming the service from Docker with our Cloud Maps layer! You are now in a great position to review the other available samples and explore additional features.

Quick Start: Display a Simple Map on Blazor¶

We will begin by creating a Blazor Web App on .NET 10 in your favorite editor. Next, we will walk you through adding the required packages and getting a map on the default page. Then, we will add some code to show a nice looking background map, and finally, add some custom data to the map and style it. After reading this, you will be in a good position to look over the How Do I Sample and explore our other features.

Step 1: Setup a New Project¶

In Visual Studio 2026, create a new project from the Blazor Web App template. On the Additional information page, choose .NET 10.0 as the framework, Server as the Interactive render mode and Per page/component as the Interactivity location. Microsoft's Tooling for ASP.NET Core Blazor walks through these screens.

From the dotnet CLI, this creates the same project:

dotnet new blazor -o BlazorApp

Step 2: Add NuGet Packages¶

You will need to install ThinkGeo.UI.Blazor in Blazor Web App project. We highly suggest you use your editor's built in NuGet package manager if possible. If you're not using an IDE you can install it via the dotnet CLI from inside your project folder where your project file exists.

dotnet add package ThinkGeo.UI.Blazor

Step 3: Create a world map¶

• Add using Reference - Open Components/_Imports.razor and add 2 using directives to reference the Map components.

  @using ThinkGeo.Core
  @using ThinkGeo.UI.Blazor
  

• No stylesheet or JavaScript references - ThinkGeo.UI.Blazor loads its own stylesheet and scripts from _content/ThinkGeo.UI.Blazor/. If your project still references https://cdn.thinkgeo.com/blazor/1.0.0/ from an earlier version, remove those references.

• Add ThinkGeo.UI.Blazor map component - Open Components/Pages/Home.razor file and replace its content with a MapView component as following. The map needs an interactive render mode: without @rendermode InteractiveServer the page shows an empty map.

  @page "/"
  @rendermode InteractiveServer
  
  <!--You can control the width and height in CSS too, if you like. -->
  <MapView Id="demomap" MapUnit="@ThinkGeo.Core.GeographyUnit.Meter" Zoom="3" Width="800" Height="600">
      <OverlaysSetting>
          <ThinkGeoCloudRasterMapsOverlay Id="RasterOverlay" MapType="ThinkGeo.Core.ThinkGeoCloudRasterMapsMapType.Aerial_V2_X1" ApiKey="YOUR CLOUD API KEY"></ThinkGeoCloudRasterMapsOverlay>
      </OverlaysSetting>
  </MapView>
  

NOTE: It requires an APIKey of ThinkGeo Cloud, and you can get the API Key from the registration email. If you don't have an account of ThinkGeo Cloud yet, please refer to ThinkGeo Cloud Maps client keys guide to get your ThinkGeo Cloud account.

Now run the Blazor Web App project. You don't need to register or install anything first: ThinkGeo 15 checks its license when your project builds, not when it runs.

• Without a license key, the first build on your machine starts a free 30-day trial. The build succeeds with warning TG0001, which tells you how many days of the trial are left, and the map shows a Not Licensed for Runtime watermark. After 30 days the build stops with error TG0002 until a key is in place.
• With a license key, the watermark goes away. Sign in at helpdesk.thinkgeo.com, download your Web key (web.thinkgeokey) and save it, with its name unchanged, in %LOCALAPPDATA%\ThinkGeo\ on Windows, or in ~/.thinkgeo/ on macOS and Linux. Then build again. There is nothing to activate, and nothing to install on the server you deploy to.

The License Guide for ThinkGeo 15 explains how to get your key, what each TG build message means and how to build on a build server. If you used ThinkGeo 14 before: Product Center and runtime license files are no longer used, see What Changed from ThinkGeo 14.

You should now see your map with our Cloud Maps layer!

Step 4: Prepare spatial data required¶

Download capital.zip and extract its five files into a new folder named Data in your project folder, next to BlazorApp.csproj.

The app reads the files from the folder it runs in, so let the build copy them there, also when you publish it: open BlazorApp.csproj and add this ItemGroup before </Project>.

  <!-- The sample data is copied next to the app on build and publish, where the code reads it. -->
  <ItemGroup>
    <None Update="Data\**" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
  </ItemGroup>

Step 5: Add a Point Data Layer¶

Replace the content of Components/Pages/Home.razor with the page below. It adds one more LayerOverlay to MapView's OverlaysSetting, and creates the FeatureLayer with the data "capital.shp" saved in the Data folder:

@page "/"
@rendermode InteractiveServer

<!--You can control the width and height in CSS too, if you like. -->
<MapView Id="demomap" MapUnit="@ThinkGeo.Core.GeographyUnit.Meter" Zoom="3" Width="800" Height="600">
    <OverlaysSetting>
        <ThinkGeoCloudRasterMapsOverlay Id="RasterOverlay" MapType="ThinkGeo.Core.ThinkGeoCloudRasterMapsMapType.Aerial_V2_X1" ApiKey="YOUR CLOUD API KEY"></ThinkGeoCloudRasterMapsOverlay>
        <!--Add one more Overlay for hosting capital FeatureLayer. -->
        <LayerOverlay Id="capitalOverlay" Layers="@layers"></LayerOverlay>
    </OverlaysSetting>
</MapView>

@code {
    GeoCollection<LayerBase> layers = new GeoCollection<LayerBase>();

    protected override void OnInitialized()
    {
        // Create the point layer for capitals.
        ShapeFileFeatureLayer capitalFeatureLayer = new ShapeFileFeatureLayer(Path.Combine(AppContext.BaseDirectory, "Data", "capital.shp"));
        // Create the "Mercator projection" and apply it to the layer to match the background map.
        capitalFeatureLayer.FeatureSource.ProjectionConverter = new ProjectionConverter(Projection.GetWgs84ProjString(), Projection.GetSphericalMercatorProjString());

        // Create the point style for positions.
        capitalFeatureLayer.ZoomLevelSet.ZoomLevel01.DefaultPointStyle = new PointStyle(PointSymbolType.Circle, 4, new GeoSolidBrush(GeoColor.FromHtml("#21FF00")), new GeoPen(GeoColor.FromHtml("#ffffff"), 1));
        // Create the labeling style for capitals.
        capitalFeatureLayer.ZoomLevelSet.ZoomLevel01.DefaultTextStyle = new TextStyle("CITY_NAME", new GeoFont("Arial", 14), new GeoSolidBrush(GeoColor.FromHtml("#21FF00")));
        capitalFeatureLayer.ZoomLevelSet.ZoomLevel01.DefaultTextStyle.YOffsetInPixel = 5;
        capitalFeatureLayer.ZoomLevelSet.ZoomLevel01.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level20;
        // Set DrawingMarginPercentage to a proper value to avoid some labels are cut-off
        capitalFeatureLayer.DrawingMarginInPixel = 300;

        layers.Add(capitalFeatureLayer);
    }
}

Step 6: Build and launch the blazor app¶

After build and run the blazor app in browser, you should now see your map with our Cloud Maps layer and capital labels.

Need Help?¶

If you run into any issues with running the samples, please let us know in the Community Forums.

If you have any questions about the product or sales, please contact us at sales@thinkgeo.com.