Spatial Mapping with NetTopologySuite

Note

It's recommended that you start by reading the general Entity Framework Core docs on spatial support.

PostgreSQL supports spatial data and operations via the PostGIS extension, which is a mature and feature-rich database spatial implementation. .NET doesn't provide a standard spatial library, but NetTopologySuite is a leading spatial library. The Npgsql EF Core provider has a plugin which allows you to map the NTS types to PostGIS columns, allowing seamless reading and writing. This is the recommended way to interact with spatial types in Npgsql.

Note that the EF Core NetTopologySuite plugin depends on the Npgsql ADO.NET NetTopology plugin, which provides NetTopologySuite support at the lower level.

Setup

To use the NetTopologySuite plugin, add the Npgsql.EntityFrameworkCore.PostgreSQL.NetTopologySuite nuget to your project. Then, configure the NetTopologySuite plugin as follows:

If you're passing a connection string to UseNpgsql, simply add the UseNetTopologySuite call as follows:

builder.Services.AddDbContext<MyContext>(options => options.UseNpgsql(
    "<connection string>",
    o => o.UseNetTopologySuite()));

This configures all aspects of Npgsql to use the NetTopologySuite plugin - both at the EF and the lower-level Npgsql layer.

If you're creating an external NpgsqlDataSource and passing it to UseNpgsql, you must call UseNetTopologySuite on your NpgsqlDataSourceBuilder independently of the EF-level setup:

var dataSourceBuilder = new NpgsqlDataSourceBuilder("<connection string>");
dataSourceBuilder.UseNetTopologySuite();
var dataSource = dataSourceBuilder.Build();

builder.Services.AddDbContext<MyContext>(options => options.UseNpgsql(
    dataSource,
    o => o.UseNetTopologySuite()));

// Configure NetTopologySuite at the ADO.NET level.
// This code must be placed at the beginning of your application, before any other Npgsql API is called; an appropriate place for this is in the static constructor on your DbContext class:
static MyDbContext()
    => NpgsqlConnection.GlobalTypeMapper.UseNetTopologySuite();

// Then, when configuring EF Core with UseNpgsql(), call UseNetTopologySuite():
builder.Services.AddDbContext<MyContext>(options =>
    options.UseNpgsql("<connection string>", o => o.UseNetTopologySuite()));

The above sets up all the necessary EF mappings and operation translators. If you're using EF 6.0, you also need to make sure that the PostGIS extension is installed in your database (later versions do this automatically). Add the following to your DbContext:

protected override void OnModelCreating(ModelBuilder builder)
{
    builder.HasPostgresExtension("postgis");
}

At this point spatial support is set up. You can now use NetTopologySuite types as regular properties in your entities, and even perform some operations:

public class City
{
    public int Id { get; set; }
    public string Name { get; set; }
    public Point Location { get; set; }
}

var nearbyCities = context.Cities.Where(c => c.Location.Distance(somePoint) < 100);

Constraining your type names

With the code above, the provider will create a database column of type geometry. This is perfectly fine, but be aware that this type accepts any geometry type (point, polygon...), with any coordinate system (XY, XYZ...). It's good practice to constrain the column to the exact type of data you will be storing, but unfortunately the provider isn't aware of your required coordinate system and therefore can't do that for you. Consider explicitly specifying your column types on your properties as follows:

[Column(TypeName="geometry (point)")]
public Point Location { get; set; }

This will constrain your column to XY points only. The same can be done via the fluent API with HasColumnType().

Geography (geodetic) support

PostGIS has two types: geometry (for Cartesian coordinates) and geography (for geodetic or spherical coordinates). You can read about the geometry/geography distinction in the PostGIS docs or in this blog post. In a nutshell, geography is much more accurate when doing calculations over long distances, but is more expensive computationally and supports only a small subset of the spatial operations supported by geometry.

The Npgsql provider will be default map all NetTopologySuite types to PostGIS geometry. However, you can instruct it to map certain properties to geography instead:

protected override void OnModelCreating(ModelBuilder builder)
{
    builder.Entity<City>().Property(b => b.Location).HasColumnType("geography (point)");
}

or via an attribute:

public class City
{
    public int Id { get; set; }
    public string Name { get; set; }
    [Column(TypeName="geography")]
    public Point Location { get; set; }
}

Once you do this, your column will be created as geography, and spatial operations will behave as expected.

Operation translation

The following table lists NetTopologySuite operations which are translated to PostGIS SQL operations. This allows you to use these NetTopologySuite methods and members efficiently - evaluation will happen on the server side. Since evaluation happens at the server, table data doesn't need to be transferred to the client (saving bandwidth), and in some cases indexes can be used to speed things up.

Note that the plugin is far from covering all spatial operations. If an operation you need is missing, please open an issue to request for it.