GIS Walkthrough

This page shows how to add GIS (geospatial feature) endpoints to a Domain Services Web API project. GIS services expose FeatureCollection entities — named groups of geographic features (points, lines, polygons) backed by providers such as ShapeFiles, MCLite (SQLite), or PostGIS.

---

Choosing a Service Class

GIS follows the same hierarchy as other DS modules. Pick based on what operations your repository supports:

Service class	Connection class	Use when…
GisService	GisServiceConnection	Read-only access to a discrete set of feature collections
GroupedGisService	GroupedGisServiceConnection	Read-only, collections organised in groups/projects
UpdatableGisService	UpdatableGisServiceConnection	Full CRUD on feature collections (no grouping)
GroupedUpdatableGisService	GroupedUpdatableGisServiceConnection	Group-aware full CRUD — most capable

Default TId is string. The non-generic variants (GisService, GroupedGisService, GroupedUpdatableGisService) default to TId = string.

Note: Unlike TimeSeries, GIS has no built-in file provider in the base package. You need at least one provider NuGet package (see table below).

---

Step 1 — Install the Packages

dotnet add package DHI.Services.GIS.WebApi
# Plus one provider (choose based on your data source)
dotnet add package DHI.Services.Provider.ShapeFile   # ShapeFile folders

Other common GIS providers:

Provider	NuGet package	Data source
ShapeFile	DHI.Services.Provider.ShapeFile	ESRI .shp file folders
MCLite	DHI.Services.Provider.MCLite	SQLite / MIKE Operations database
PostGIS	DHI.Services.Provider.PostgreSQL	PostgreSQL with PostGIS extension
MIKE Res1D	DHI.Services.Provider.MIKE	MIKE result files

---

Step 2 — Register the Converters

In Program.cs, inside .AddJsonOptions(...):

options.JsonSerializerOptions.AddConverters(
    DHI.Services.GIS.WebApi.SerializerOptionsDefault.Options.Converters
);

GIS uses a custom converter set for FeatureCollection, IGeometry, IFeature, IAttribute, and map-style types.

---

Step 3 — Register an IMapStyleRepository

GIS Web API controllers require IMapStyleRepository in DI for map style lookups. Register it in Program.cs:

builder.Services.AddScoped<IMapStyleRepository>(_ =>
    new MapStyleRepository(
        "[AppData]styles.json".Resolve(),
        DHI.Services.GIS.WebApi.SerializerOptionsDefault.Options
    )
);

Create an empty App_Data/styles.json to start:

{}

---

Step 4 — Register the GIS Service

Option A — Imperative (code)

ShapeFile provider — reads all .shp files from a folder:

ServiceLocator.Register(
    new GisService(
        new DHI.Services.Provider.ShapeFile.FeatureRepository(
            "[AppData]shapefiles".Resolve()
        )
    ),
    "gis-shape"
);

Each .shp file in the folder becomes one FeatureCollection (keyed by the file name without extension).

Option B — Declarative (connections.json)

{
  "$type": "System.Collections.Generic.Dictionary`2[[System.String, mscorlib],[DHI.Services.IConnection, DHI.Services]], mscorlib",
  "gis-shape": {
    "$type": "DHI.Services.GIS.WebApi.GisServiceConnection, DHI.Services.GIS.WebApi",
    "ConnectionString": "[AppData]shapefiles",
    "RepositoryType": "DHI.Services.Provider.ShapeFile.FeatureRepository, DHI.Services.Provider.ShapeFile",
    "Name": "GIS (ShapeFile)",
    "Id": "gis-shape"
  }
}

---

Step 5 — Add Sample Data

Create App_Data/shapefiles/ and copy any .shp file (with its companion .dbf, .shx files) into it. The folder name becomes the group; the file name becomes the collection ID.

---

Step 6 — Verify in Swagger

Start the API and open Swagger. You should see /api/featurecollections/... and /api/maps/... endpoint groups.

List all feature collection IDs:

GET /api/featurecollections/gis-shape

Get a specific feature collection by ID:

GET /api/featurecollections/gis-shape/{featureCollectionId}

Stream a collection as a file (GeoJSON / ShapeFile):

GET /api/featurecollections/gis-shape/{featureCollectionId}/stream

Tip: IDs that contain slashes (group/name) must be encoded using | as the separator in URLs. See Web API Core for details.

---

Map Services (Optional)

In addition to feature collections, GIS includes Map services that render raster map images (WMS-style). Map services use a different service class hierarchy:

Service	Use when…
MapService	Single data source (e.g., one .dfs2 file), returns bitmap tiles
GroupedMapService	Multiple layers organised in groups
CachedMapService	Like MapService but with in-memory tile caching
FileCachedMapService	Like MapService but with disk-based tile caching

Example registration (DFS2 file):

ServiceLocator.Register(
    new MapService(
        new Dfs2MapSource("[AppData]dfs2/myfile.dfs2".Resolve()),
        new MapStyleService(
            new MapStyleRepository("[AppData]styles.json".Resolve(),
                DHI.Services.GIS.WebApi.SerializerOptionsDefault.Options)
        )
    ),
    "dfs2-map"
);

Map endpoints follow WMS conventions:

GET /api/maps?request=GetMap&service=wms&version=1.3.0&LAYERS=dfs2-map&...

---

Key Data Types

Type	Description
FeatureCollection<TId>	The main entity — a named, optionally grouped collection of features
IFeature	A single geographic feature with geometry and attributes
IGeometry	A geometry shape (point, line, polygon, etc.)
IAttribute	A key/value metadata attribute on a feature or collection
MapStyle	A color palette definition used to style raster map images

---

Summary

• Install DHI.Services.GIS.WebApi plus at least one provider package (e.g. DHI.Services.Provider.ShapeFile).
• Register DHI.Services.GIS.WebApi.SerializerOptionsDefault.Options.Converters in Program.cs.
• GIS controllers also require IMapStyleRepository in DI — register it with a MapStyleRepository pointing to a styles.json file.
• Use GisService for simple read-only access; use GroupedUpdatableGisService for full CRUD with project grouping.
• Map services (MapService, GroupedMapService) expose WMS-compatible image rendering endpoints.

Next: Building a Custom Domain