In my most recent project we needed to do a bit of geo-spatial referencing. While spatial features have been in SQL Server for a while using those features inside of .NET applications hasn't been as straight forward as could be, because .NET natively doesn't support spatial types. There are workarounds for this with a few custom project like SharpMap or a hack using
the Sql Server specific Geo types found in
the Microsoft.SqlTypes assembly that ships with SQL server. While these approaches work for manipulating spatial data from .NET code, they didn't work with database access if you're using Entity Framework. Other ORM vendors have been rolling their own versions of spatial integration. In Entity Framework 5.0 running on .NET 4.5
the Microsoft ORM finally adds support for spatial types as well. In this post I'll describe basic geography features that deal with single location and distance calculations which is probably
the most common usage scenario. SQL Server Transact-SQL Syntax for Spatial Data Before we look at how things work with Entity framework, lets take a look at how SQL Server allows you to use spatial data to get an understanding of
the underlying semantics.
The following SQL examples should work with SQL 2008 and forward. Let's start by creating a test table that includes a Geography field and also a pair of Long/Lat fields that demonstrate how you can work with
the geography functions even if you don't have geography/geometry fields in
the database. Here's
the CREATE command:CREATE TABLE [dbo].[Geo](
[id] [int] IDENTITY(1,1) NOT NULL,
[Location] [geography] NULL,
[Long] [float] NOT NULL,
[Lat] [float] NOT NULL
)
Now using plain SQL you can insert data into
the table using geography::STGeoFromText SQL CLR function:insert into Geo( Location , long, lat ) values
( geography::STGeomFromText ('POINT(-121.527200 45.712113)', 4326), -121.527200, 45.712113 )
insert into Geo( Location , long, lat ) values
( geography::STGeomFromText ('POINT(-121.517265 45.714240)', 4326), -121.517265, 45.714240 )
insert into Geo( Location , long, lat ) values
( geography::STGeomFromText ('POINT(-121.511536 45.714825)', 4326), -121.511536, 45.714825)
The STGeomFromText function accepts a string that points to a geometric item (a point here but can also be a line or path or polygon and many others). You also need to provide an SRID (Spatial Reference System Identifier) which is an integer value that determines
the rules for how geography/geometry values are calculated and returned. For mapping/distance functionality you typically want to use 4326 as this is
the format used by most mapping software and geo-location libraries like Google and Bing.
The spatial data in
the Location field is stored in binary format which looks something like this:
Once
the location data is in
the database you can query
the data and do simple distance computations very easily. For example to calculate
the distance of each of
the values in
the database to another spatial point is very easy to calculate.
Distance calculations compare two points in space using a direct line calculation. For our example I'll compare a new point to all
the points in
the database.
Using
the Location field
the SQL looks like this:-- create a source point
DECLARE @s geography
SET @s = geography:: STGeomFromText('POINT(-121.527200 45.712113)' , 4326);
--- return
the ids
select ID, Location as Geo ,
Location .ToString() as Point ,
@s.STDistance( Location) as distance
from Geo
order by distance
The code defines a new point which is
the base point to compare each of
the values to. You can also compare values from
the database directly, but typically you'll want to match a location to another location and determine
the difference for which you can use
the geography::STDistance function.
This query produces
the following output:
The STDistance function returns
the straight line distance between
the passed in point and
the point in
the database field.
The result for SRID 4326 is always in meters. Notice that
the first value passed was
the same point so
the difference is 0.
The other two points are two points here in town in Hood River a little ways away - 808 and 1256 meters respectively.
Notice also that you can order
the result by
the resulting distance, which effectively gives you results that are ordered radially out from closer to further away. This is great for searches of points of interest near a central location (YOU typically!).
These geolocation functions are also available to you if you don't use
the Geography/Geometry types, but plain float values. It's a little more work, as each point has to be created in
the query using
the string syntax, but
the following code doesn't use a geography field but produces
the same result as
the previous query.--- using float fields
select ID,
geography::STGeomFromText ('POINT(' + STR (long, 15,7 ) + ' ' + Str(lat ,15, 7) + ')' , 4326),
geography::STGeomFromText ('POINT(' + STR (long, 15,7 ) + ' ' + Str(lat ,15, 7) + ')' , 4326). ToString(),
@s.STDistance( geography::STGeomFromText ('POINT(' + STR(long ,15, 7) + ' ' + Str(lat ,15, 7) + ')' , 4326)) as distance
from geo
order by distance
Spatial Data in
the Entity Framework
Prior to Entity Framework 5.0 on .NET 4.5 consuming of
the data above required using stored procedures or raw SQL commands to access
the spatial data. In Entity Framework 5 however, Microsoft introduced
the new DbGeometry and DbGeography types. These immutable location types provide a bunch of functionality for manipulating spatial points using geometry functions which in turn can be used to do common spatial queries like I described in
the SQL syntax above.
The DbGeography/DbGeometry types are immutable, meaning that you can't write to them once they've been created. They are a bit odd in that you need to use factory methods in order to instantiate them - they have no constructor() and you can't assign to properties like Latitude and Longitude.
Creating a Model with Spatial Data
Let's start by creating a simple Entity Framework model that includes a Location property of type DbGeography: public class GeoLocationContext : DbContext
{
public DbSet<GeoLocation> Locations { get; set; }
}
public class GeoLocation
{
public int Id { get; set; }
public DbGeography Location { get; set; }
public string Address { get; set; }
}
That's all there's to it. When you run this now against SQL Server, you get a Geography field for
the Location property, which looks
the same as
the Location field in
the SQL examples earlier.
Adding Spatial Data to
the Database
Next let's add some data to
the table that includes some latitude and longitude data. An easy way to find lat/long locations is to use Google Maps to pinpoint your location, then right click and click on What's Here. Click on
the green marker to get
the GPS coordinates.
To add
the actual geolocation data create an instance of
the GeoLocation type and use
the DbGeography.PointFromText() factory method to create a new point to assign to
the Location property:[TestMethod]
public void AddLocationsToDataBase()
{
var context = new GeoLocationContext();
// remove all
context.Locations.ToList().ForEach( loc => context.Locations.Remove(loc));
context.SaveChanges();
var location = new GeoLocation()
{
// Create a point using native DbGeography Factory method
Location = DbGeography.PointFromText(
string.Format("POINT({0} {1})", -121.527200,45.712113)
,4326),
Address = "301 15th Street, Hood River"
};
context.Locations.Add(location);
location = new GeoLocation()
{
Location = CreatePoint(45.714240, -121.517265),
Address = "
The Hatchery, Bingen"
};
context.Locations.Add(location);
location = new GeoLocation()
{
// Create a point using a helper function (lat/long)
Location = CreatePoint(45.708457, -121.514432),
Address = "Kaze Sushi, Hood River"
};
context.Locations.Add(location);
location = new GeoLocation()
{
Location = CreatePoint(45.722780, -120.209227),
Address = "Arlington, OR"
};
context.Locations.Add(location);
context.SaveChanges();
}
As promised, a DbGeography object has to be created with one of
the static factory methods provided on
the type as
the Location.Longitude and Location.Latitude properties are read only. Here I'm using PointFromText() which uses a "Well Known Text" format to specify spatial data. In
the first example I'm specifying to create a Point from a longitude and latitude value, using an SRID of 4326 (just like earlier in
the SQL examples).
You'll probably want to create a helper method to make
the creation of Points easier to avoid that string format and instead just pass in a couple of double values. Here's my helper called CreatePoint that's used for all but
the first point creation in
the sample above:public static DbGeography CreatePoint(double latitude, double longitude)
{
var text = string.Format(CultureInfo.InvariantCulture.NumberFormat,
"POINT({0} {1})", longitude, latitude);
// 4326 is most common coordinate system used by GPS/Maps
return DbGeography.PointFromText(text, 4326);
}
Using
the helper
the syntax becomes a bit cleaner, requiring only a latitude and longitude respectively. Note that my method intentionally swaps
the parameters around because Latitude and Longitude is
the common format I've seen with mapping libraries (especially Google Mapping/Geolocation APIs with their LatLng type).
When
the context is changed
the data is written into
the database using
the SQL Geography type which looks
the same as in
the earlier SQL examples shown.
Querying
Once you have some location data in
the database it's now super easy to query
the data and find out
the distance between locations. A common query is to ask for a number of locations that are near a fixed point - typically your current location and order it by distance.
Using LINQ to Entities a query like this is easy to construct:[TestMethod]
public void QueryLocationsTest()
{
var sourcePoint = CreatePoint(45.712113, -121.527200);
var context = new GeoLocationContext();
// find any locations
within 5 kilometers ordered by distance
var matches =
context.Locations
.Where(loc => loc.Location.Distance(sourcePoint) < 5000)
.OrderBy( loc=> loc.Location.Distance(sourcePoint) )
.Select( loc=> new { Address = loc.Address, Distance = loc.Location.Distance(sourcePoint) });
Assert.IsTrue(matches.Count() > 0);
foreach (var location in matches)
{
Console.WriteLine("{0} ({1:n0} meters)", location.Address, location.Distance);
}
}
This example produces:
301 15th Street, Hood River (0 meters)The Hatchery, Bingen (809 meters)Kaze Sushi, Hood River (1,074 meters)
The first point in
the database is
the same as my source point I'm comparing against so
the distance is 0.
The other two are
within the 5 mile radius, while
the Arlington location which is 65 miles or so out is not returned.
The result is ordered by distance from closest to furthest away.
In
the code, I first create a source point that is
the basis for comparison.
The LINQ query then selects all locations that are
within 5km of
the source point using
the Location.Distance() function, which takes a source point as a parameter. You can either use a pre-defined value as I'm doing here, or compare against another database DbGeography property (say when you have to points in
the same database for things like routes).
What's nice about this query syntax is that it's very clean and easy to read and understand. You can calculate
the distance and also easily order by
the distance to provide a result that shows locations from closest to furthest away which is a common scenario for any application that places a user in
the context of several locations. It's now super easy to accomplish this.
Meters vs. Miles
As with
the SQL Server functions,
the Distance() method returns data in meters, so if you need to work with miles or feet you need to do some conversion. Here are a couple of helpers that might be useful (can be found in GeoUtils.cs of
the sample project):/// <summary>
/// Convert meters to miles
/// </summary>
/// <param name="meters"></param>
/// <returns></returns>
public static double MetersToMiles(double? meters)
{
if (meters == null)
return 0F;
return meters.Value * 0.000621371192;
}
/// <summary>
/// Convert miles to meters
/// </summary>
/// <param name="miles"></param>
/// <returns></returns>
public static double MilesToMeters(double? miles)
{
if (miles == null)
return 0;
return miles.Value * 1609.344;
}
Using these two helpers you can query on miles like this:[TestMethod]
public void QueryLocationsMilesTest()
{
var sourcePoint = CreatePoint(45.712113, -121.527200);
var context = new GeoLocationContext();
// find any locations
within 5 miles ordered by distance
var fiveMiles = GeoUtils.MilesToMeters(5);
var matches =
context.Locations
.Where(loc => loc.Location.Distance(sourcePoint) <= fiveMiles)
.OrderBy(loc => loc.Location.Distance(sourcePoint))
.Select(loc => new { Address = loc.Address, Distance = loc.Location.Distance(sourcePoint) });
Assert.IsTrue(matches.Count() > 0);
foreach (var location in matches)
{
Console.WriteLine("{0} ({1:n1} miles)", location.Address, GeoUtils.MetersToMiles(location.Distance));
}
}
which produces:
301 15th Street, Hood River (0.0 miles)The Hatchery, Bingen (0.5 miles)Kaze Sushi, Hood River (0.7 miles)
Nice 'n simple.
.NET 4.5 Only
Note that DbGeography and DbGeometry are exclusive to Entity Framework 5.0 (not 4.4 which ships in
the same NuGet package or installer) and requires .NET 4.5. That's because
the new DbGeometry and DbGeography (and related) types are defined in
the 4.5 version of System.Data.Entity which is a CLR assembly and is only updated by major versions of .NET. Why this decision was made to add these types to System.Data.Entity rather than to
the frequently updated EntityFramework assembly that would have possibly made this work in .NET 4.0 is beyond me, especially given that there are no native .NET framework spatial types to begin with.
I find it also odd that there is no native CLR spatial type.
The DbGeography and DbGeometry types are specific to Entity Framework and live on those assemblies. They will also work for general purpose, non-database spatial data manipulation, but then you are forced into having a dependency on System.Data.Entity, which seems a bit silly. There's also a System.Spatial assembly that's apparently part of WCF Data Services which in turn don't work with Entity framework. Another example of multiple teams at Microsoft not communicating and implementing
the same functionality (differently) in several different places. Perplexed as a I may be, for EF specific code
the Entity framework specific types are easy to use and work well.
Working with pre-.NET 4.5 Entity Framework and Spatial Data
If you can't go to .NET 4.5 just yet you can also still use spatial features in Entity Framework, but it's a lot more work as you can't use
the DbContext directly to manipulate
the location data. You can still run raw SQL statements to write data into
the database and retrieve results using
the same TSQL syntax I showed earlier using Context.Database.ExecuteSqlCommand().
Here's code that you can use to add location data into
the database:[TestMethod]
public void RawSqlEfAddTest()
{
string sqlFormat =
@"insert into GeoLocations( Location, Address) values
( geography::STGeomFromText('POINT({0} {1})', 4326),@p0 )";
var sql = string.Format(sqlFormat,-121.527200, 45.712113);
Console.WriteLine(sql);
var context = new GeoLocationContext();
Assert.IsTrue(context.Database.ExecuteSqlCommand(sql,"301 N. 15th Street") > 0);
}
Here I'm using
the STGeomFromText() function to add
the location data.
Note that I'm using string.Format here, which usually would be a bad practice but is required here. I was unable to use ExecuteSqlCommand() and its named parameter syntax as
the longitude and latitude parameters are embedded into a string. Rest assured it's required as
the following does not work:string sqlFormat =
@"insert into GeoLocations( Location, Address) values
( geography::STGeomFromText('POINT(@p0 @p1)', 4326),@p2 )";context.Database.ExecuteSqlCommand(sql, -121.527200, 45.712113, "301 N. 15th Street")
Explicitly assigning
the point value with string.format works however.
There are a number of ways to query location data. You can't get
the location data directly, but you can retrieve
the point string (which can then be parsed to get Latitude and Longitude) and you can return calculated values like distance.
Here's an example of how to retrieve some geo data into a resultset using EF's and SqlQuery method:[TestMethod]
public void RawSqlEfQueryTest()
{
var sqlFormat =
@"
DECLARE @s geography
SET @s = geography:: STGeomFromText('POINT({0} {1})' , 4326);
SELECT
Address,
Location.ToString() as GeoString,
@s.STDistance( Location) as Distance
FROM GeoLocations
ORDER BY Distance";
var sql = string.Format(sqlFormat, -121.527200, 45.712113);
var context = new GeoLocationContext();
var locations = context.Database.SqlQuery<ResultData>(sql);
Assert.IsTrue(locations.Count() > 0);
foreach (var location in locations)
{
Console.WriteLine(location.Address + " " + location.GeoString + " " + location.Distance);
}
}
public class ResultData
{
public string GeoString { get; set; }
public double Distance { get; set; }
public string Address { get; set; }
}
Hopefully you don't have to resort to this approach as it's fairly limited. Using
the new DbGeography/DbGeometry types makes this sort of thing so much easier. When I had to use code like this before I typically ended up retrieving data pks only and then running another query with just
the PKs to retrieve
the actual underlying DbContext entities. This was very inefficient and tedious but it did work.
Summary
For
the current project I'm working on we actually made
the switch to .NET 4.5 purely for
the spatial features in EF 5.0. This app heavily relies on spatial queries and it was worth taking a chance with pre-release code to get this ease of integration as opposed to manually falling back to stored procedures or raw SQL string queries to return spatial specific queries. Using native Entity Framework code makes life a lot easier than
the alternatives. It might be a late addition to Entity Framework, but it sure makes location calculations and storage easy. Where do you want to go today? ;-)
Resources
Download Sample Project© Rick Strahl, West Wind Technologies, 2005-2012Posted in ADO.NET Sql Server .NET
Tweet
!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src="//platform.twitter.com/widgets.js";fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");
(function() {
var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
po.src = 'https://apis.google.com/js/plusone.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
})();
