Données spatialesSpatial Data

Note

Cette fonctionnalité est une nouveauté dans EF Core 2.2.This feature is new in EF Core 2.2.

Données spatiales représentent l’emplacement physique et la forme d’objets.Spatial data represents the physical location and the shape of objects. Plusieurs bases de données prennent en charge ce type de données afin de pouvoir être indexé et interrogée en même temps que d’autres données.Many databases provide support for this type of data so it can be indexed and queried alongside other data. Scénarios courants incluent l’interrogation d’objets dans un rayon donné à partir d’un emplacement, ou en sélectionnant l’objet dont la bordure contient un emplacement donné.Common scenarios include querying for objects within a given distance from a location, or selecting the object whose border contains a given location. EF Core prend en charge le mappage de types de données spatiales à l’aide de la NetTopologySuite bibliothèque spatiale.EF Core supports mapping to spatial data types using the NetTopologySuite spatial library.

Installation deInstalling

Pour utiliser les données spatiales avec EF Core, vous devez installer le package NuGet de prise en charge approprié.In order to use spatial data with EF Core, you need to install the appropriate supporting NuGet package. Le package que vous devez installer varie selon le fournisseur que vous utilisez.Which package you need to install depends on the provider you're using.

Fournisseur EF CoreEF Core Provider Package NuGet spatialSpatial NuGet Package
Microsoft.EntityFrameworkCore.SqlServerMicrosoft.EntityFrameworkCore.SqlServer Microsoft.EntityFrameworkCore.SqlServer.NetTopologySuiteMicrosoft.EntityFrameworkCore.SqlServer.NetTopologySuite
Microsoft.EntityFrameworkCore.SqliteMicrosoft.EntityFrameworkCore.Sqlite Microsoft.EntityFrameworkCore.Sqlite.NetTopologySuiteMicrosoft.EntityFrameworkCore.Sqlite.NetTopologySuite
Microsoft.EntityFrameworkCore.InMemoryMicrosoft.EntityFrameworkCore.InMemory NetTopologySuiteNetTopologySuite
Npgsql.EntityFrameworkCore.PostgreSQLNpgsql.EntityFrameworkCore.PostgreSQL Npgsql.EntityFrameworkCore.PostgreSQL.NetTopologySuiteNpgsql.EntityFrameworkCore.PostgreSQL.NetTopologySuite

Ingénierie à reboursReverse engineering

Les spatial packages NuGet également activer ingénierie à rebours modèles avec des propriétés spatiales, mais vous doivent installer le package avant en cours d’exécution Scaffold-DbContext ou dotnet ef dbcontext scaffold.The spatial NuGet packages also enable reverse engineering models with spatial properties, but you need to install the package before running Scaffold-DbContext or dotnet ef dbcontext scaffold. Si vous ne le faites, vous recevez des avertissements sur la recherche ne pas de mappages de type pour les colonnes et les colonnes sont ignorés.If you don't, you'll receive warnings about not finding type mappings for the columns and the columns will be skipped.

NetTopologySuite (NTS)NetTopologySuite (NTS)

NetTopologySuite est une bibliothèque spatiale pour .NET.NetTopologySuite is a spatial library for .NET. EF Core autorise les types de mappage des données spatiales dans la base de données à l’aide des types NTS dans votre modèle.EF Core enables mapping to spatial data types in the database by using NTS types in your model.

Pour activer le mappage de types spatiaux via NTS, appelez la méthode de UseNetTopologySuite sur Générateur d’options du fournisseur DbContext.To enable mapping to spatial types via NTS, call the UseNetTopologySuite method on the provider's DbContext options builder. Par exemple, avec SQL Server vous appelez il comme suit.For example, with SQL Server you'd call it like this.

optionsBuilder.UseSqlServer(
    @"Data Source=(localdb)\MSSQLLocalDB;Initial Catalog=WideWorldImporters",
    x => x.UseNetTopologySuite());

Il existe plusieurs types de données spatiales.There are several spatial data types. Le type que vous utilisez dépend des types de formes que vous souhaitez autoriser.Which type you use depends on the types of shapes you want to allow. Voici la hiérarchie des types NTS que vous pouvez utiliser pour les propriétés dans votre modèle.Here is the hierarchy of NTS types that you can use for properties in your model. Elles se trouvent dans le NetTopologySuite.Geometries espace de noms.They're located within the NetTopologySuite.Geometries namespace. Les interfaces correspondantes dans le package GeoAPI (GeoAPI.Geometries espace de noms) peut également être utilisé.Corresponding interfaces in the GeoAPI package (GeoAPI.Geometries namespace) can also be used.

  • géométrieGeometry
    • PointPoint
    • LineStringLineString
    • PolygonePolygon
    • GeometryCollectionGeometryCollection
      • MultiPointMultiPoint
      • MultiLineStringMultiLineString
      • MultiPolygonMultiPolygon

Avertissement

CircularString, CompoundCurve et CurePolygon ne sont pas pris en charge par NTS.CircularString, CompoundCurve, and CurePolygon aren't supported by NTS.

Le type de géométrie de base grâce à n’importe quel type de forme à être spécifié par la propriété.Using the base Geometry type allows any type of shape to be specified by the property.

Les classes d’entité suivante peut servir à mapper aux tables dans le base de données Wide World Importers exemple.The following entity classes could be used to map to tables in the Wide World Importers sample database.

[Table("Cities", Schema = "Application"))]
class City
{
    public int CityID { get; set; }

    public string CityName { get; set; }

    public IPoint Location { get; set; }
}

[Table("Countries", Schema = "Application"))]
class Country
{
    public int CountryID { get; set; }

    public string CountryName { get; set; }

    // Database includes both Polygon and MultiPolygon values
    public IGeometry Border { get; set; }
}

Création de valeursCreating values

Vous pouvez utiliser des constructeurs pour créer des objets de géométrie ; Toutefois, NTS recommande plutôt d’utiliser une fabrique de géométrie.You can use constructors to create geometry objects; however, NTS recommends using a geometry factory instead. Cela vous permet de spécifier une valeur par défaut SRID (le système de référence spatiale utilisé par les coordonnées) et vous donne un contrôle sur des éléments plus avancés tels que le modèle de précision (utilisé lors des calculs) et la séquence de coordonnées (détermine les coordonnées--dimensions et mesures sont disponibles).This lets you specify a default SRID (the spatial reference system used by the coordinates) and gives you control over more advanced things like the precision model (used during calculations) and the coordinate sequence (determines which ordinates--dimensions and measures--are available).

var geometryFactory = NtsGeometryServices.Instance.CreateGeometryFactory(srid: 4326);
var currentLocation = geometryFactory.CreatePoint(-122.121512, 47.6739882);

Note

4326 fait référence à WGS 84, une norme utilisée dans le GPS et d’autres systèmes géographiques.4326 refers to WGS 84, a standard used in GPS and other geographic systems.

Longitude et LatitudeLongitude and Latitude

Coordonnées dans NTS sont exprimées en termes de valeurs X et Y.Coordinates in NTS are in terms of X and Y values. Pour représenter la longitude et latitude, utilisez X longitude et Y de latitude.To represent longitude and latitude, use X for longitude and Y for latitude. Notez que cela est descendante à partir de la latitude, longitude format dans lequel vous voyez généralement ces valeurs.Note that this is backwards from the latitude, longitude format in which you typically see these values.

SRID ignorés pendant les opérations du clientSRID Ignored during client operations

NTS ignore les valeurs SRID lors des opérations.NTS ignores SRID values during operations. Il suppose un système de coordonnées planaire.It assumes a planar coordinate system. Cela signifie que si vous spécifiez des coordonnées en termes de longitude et latitude, certaines valeurs client évalué comme zone, la longueur et distance sera en degrés, pas de compteurs.This means that if you specify coordinates in terms of longitude and latitude, some client-evaluated values like distance, length, and area will be in degrees, not meters. Pour des valeurs plus significatives, vous devez tout d’abord projeter les coordonnées à un autre système de coordonnées à l’aide d’une bibliothèque comme ProjNet4GeoAPI avant de calculer ces valeurs.For more meaningful values, you first need to project the coordinates to another coordinate system using a library like ProjNet4GeoAPI before calculating these values.

Si une opération est évalué par EF Core par le biais de SQL server, les unités du résultat seront déterminée par la base de données.If an operation is server-evaluated by EF Core via SQL, the result's unit will be determined by the database.

Voici un exemple d’utilisation ProjNet4GeoAPI pour calculer la distance entre deux villes.Here is an example of using ProjNet4GeoAPI to calculate the distance between two cities.

static class GeometryExtensions
{
    static readonly IGeometryServices _geometryServices = NtsGeometryServices.Instance;
    static readonly ICoordinateSystemServices _coordinateSystemServices
        = new CoordinateSystemServices(
            new CoordinateSystemFactory(),
            new CoordinateTransformationFactory(),
            new Dictionary<int, string>
            {
                // Coordinate systems:

                // (3857 and 4326 included automatically)

                // This coordinate system covers the area of our data.
                // Different data requires a different coordinate system.
                [2855] =
                @"
                    PROJCS[""NAD83(HARN) / Washington North"",
                        GEOGCS[""NAD83(HARN)"",
                            DATUM[""NAD83_High_Accuracy_Regional_Network"",
                                SPHEROID[""GRS 1980"",6378137,298.257222101,
                                    AUTHORITY[""EPSG"",""7019""]],
                                AUTHORITY[""EPSG"",""6152""]],
                            PRIMEM[""Greenwich"",0,
                                AUTHORITY[""EPSG"",""8901""]],
                            UNIT[""degree"",0.01745329251994328,
                                AUTHORITY[""EPSG"",""9122""]],
                            AUTHORITY[""EPSG"",""4152""]],
                        PROJECTION[""Lambert_Conformal_Conic_2SP""],
                        PARAMETER[""standard_parallel_1"",48.73333333333333],
                        PARAMETER[""standard_parallel_2"",47.5],
                        PARAMETER[""latitude_of_origin"",47],
                        PARAMETER[""central_meridian"",-120.8333333333333],
                        PARAMETER[""false_easting"",500000],
                        PARAMETER[""false_northing"",0],
                        UNIT[""metre"",1,
                            AUTHORITY[""EPSG"",""9001""]],
                        AUTHORITY[""EPSG"",""2855""]]
                "
            });

    public static IGeometry ProjectTo(this IGeometry geometry, int srid)
    {
        var geometryFactory = _geometryServices.CreateGeometryFactory(srid);
        var transformation = _coordinateSystemServices.CreateTransformation(geometry.SRID, srid);

        return GeometryTransform.TransformGeometry(
            geometryFactory,
            geometry,
            transformation.MathTransform);
    }
}
var seattle = new Point(-122.333056, 47.609722) { SRID = 4326 };
var redmond = new Point(-122.123889, 47.669444) { SRID = 4326 };

var distance = seattle.ProjectTo(2855).Distance(redmond.ProjectTo(2855));

Interrogation des donnéesQuerying Data

Dans LINQ, les méthodes NTS et propriétés disponibles en tant que fonctions de base de données seront traduites à SQL.In LINQ, the NTS methods and properties available as database functions will be translated to SQL. Par exemple, les méthodes de Distance et Contains sont traduits dans les requêtes suivantes.For example, the Distance and Contains methods are translated in the following queries. Le tableau à la fin de cet article indique quels membres sont pris en charge par divers fournisseurs d’EF Core.The table at the end of this article shows which members are supported by various EF Core providers.

var nearestCity = db.Cities
    .OrderBy(c => c.Location.Distance(currentLocation))
    .FirstOrDefault();

var currentCountry = db.Countries
    .FirstOrDefault(c => c.Border.Contains(currentLocation));

SQL ServerSQL Server

Si vous utilisez SQL Server, il existe certaines choses supplémentaires, que vous devez connaître.If you're using SQL Server, there are some additional things you should be aware of.

Géographie ou géométrieGeography or geometry

Par défaut, les propriétés spatiales sont mappées sur geography colonnes dans SQL Server.By default, spatial properties are mapped to geography columns in SQL Server. Pour utiliser geometry, configurer le type de colonne dans votre modèle.To use geometry, configure the column type in your model.

Anneaux de polygon GeographyGeography polygon rings

Lorsque vous utilisez le geography type de colonne, SQL Server impose des exigences supplémentaires sur l’anneau extérieur (ou un interpréteur de commandes) et intérieurs anneaux (ni aucune faille).When using the geography column type, SQL Server imposes additional requirements on the exterior ring (or shell) and interior rings (or holes). L’anneau extérieur doit être orienté dans le sens anti-horaire et l’intérieur les anneaux dans le sens horaire.The exterior ring must be oriented counterclockwise and the interior rings clockwise. NTS cela valide avant d’envoyer des valeurs à la base de données.NTS validates this before sending values to the database.

FullGlobeFullGlobe

SQL Server dispose d’un type de géométrie non standard pour représenter le globe complet lorsque vous utilisez le geography type de colonne.SQL Server has a non-standard geometry type to represent the full globe when using the geography column type. Il a également un moyen pour représenter des polygones selon le globe complet (sans un anneau extérieur).It also has a way to represent polygons based on the full globe (without an exterior ring). Aucune de ces sont pris en charge par NTS.Neither of these are supported by NTS.

Avertissement

Polygones basés sur celui-ci et FullGlobe ne sont pas pris en charge par NTS.FullGlobe and polygons based on it aren't supported by NTS.

SQLiteSQLite

Voici quelques informations supplémentaires pour ceux qui utilisent SQLite.Here is some additional information for those using SQLite.

L’installation SpatiaLiteInstalling SpatiaLite

La bibliothèque native mod_spatialite est distribuée sur Windows, comme une dépendance de package NuGet.On Windows, the native mod_spatialite library is distributed as a NuGet package dependency. Autres plateformes doivent l’installer séparément.Other platforms need to install it separately. Cela s’effectue généralement à l’aide d’un gestionnaire de package de logiciel.This is typically done using a software package manager. Par exemple, vous pouvez utiliser APT sur Ubuntu et Homebrew sur MacOS.For example, you can use APT on Ubuntu and Homebrew on MacOS.

# Ubuntu
apt-get install libsqlite3-mod-spatialite

# macOS
brew install libspatialite

Configuration des SRIDConfiguring SRID

Dans SpatiaLite, les colonnes doivent spécifier un SRID par colonne.In SpatiaLite, columns need to specify an SRID per column. La valeur par défaut est de SRID 0.The default SRID is 0. Spécifiez un SRID différent à l’aide de la méthode ForSqliteHasSrid.Specify a different SRID using the ForSqliteHasSrid method.

modelBuilder.Entity<City>().Property(c => c.Location)
    .ForSqliteHasSrid(4326);

DimensionDimension

Comme pour les SRID, dimension d’une colonne (ou les coordonnées) sont également spécifiées dans le cadre de la colonne.Similar to SRID, a column's dimension (or ordinates) is also specified as part of the column. Les coordonnées de la valeur par défaut sont X et Y. activer les coordonnées supplémentaires (Z et M) à l’aide de la méthode ForSqliteHasDimension.The default ordinates are X and Y. Enable additional ordinates (Z and M) using the ForSqliteHasDimension method.

modelBuilder.Entity<City>().Property(c => c.Location)
    .ForSqliteHasDimension(Ordinates.XYZ);

Opérations traduitesTranslated Operations

Ce tableau indique quels membres NTS sont traduites en SQL par chaque fournisseur EF Core.This table shows which NTS members are translated into SQL by each EF Core provider.

NetTopologySuiteNetTopologySuite SQL Server (geometry)SQL Server (geometry) SQL Server (geography)SQL Server (geography) SQLiteSQLite NpgsqlNpgsql
Geometry.AreaGeometry.Area
Geometry.AsBinary()Geometry.AsBinary()
Geometry.AsText()Geometry.AsText()
Geometry.BoundaryGeometry.Boundary
Geometry.Buffer(double)Geometry.Buffer(double)
Geometry.Buffer (double, int)Geometry.Buffer(double, int)
Geometry.CentroidGeometry.Centroid
Geometry.Contains(Geometry)Geometry.Contains(Geometry)
Geometry.ConvexHull()Geometry.ConvexHull()
Geometry.CoveredBy(Geometry)Geometry.CoveredBy(Geometry)
Geometry.Covers(Geometry)Geometry.Covers(Geometry)
Geometry.Crosses(Geometry)Geometry.Crosses(Geometry)
Geometry.Difference(Geometry)Geometry.Difference(Geometry)
Geometry.DimensionGeometry.Dimension
Geometry.Disjoint(Geometry)Geometry.Disjoint(Geometry)
Geometry.Distance(Geometry)Geometry.Distance(Geometry)
Geometry.EnvelopeGeometry.Envelope
Geometry.EqualsExact(Geometry)Geometry.EqualsExact(Geometry)
Geometry.EqualsTopologically(Geometry)Geometry.EqualsTopologically(Geometry)
Geometry.GeometryTypeGeometry.GeometryType
Geometry.GetGeometryN(int)Geometry.GetGeometryN(int)
Geometry.InteriorPointGeometry.InteriorPoint
Geometry.Intersection(Geometry)Geometry.Intersection(Geometry)
Geometry.Intersects(Geometry)Geometry.Intersects(Geometry)
Geometry.IsEmptyGeometry.IsEmpty
Geometry.IsSimpleGeometry.IsSimple
Geometry.IsValidGeometry.IsValid
Geometry.IsWithinDistance (Geometry, double)Geometry.IsWithinDistance(Geometry, double)
Geometry.LengthGeometry.Length
Geometry.NumGeometriesGeometry.NumGeometries
Geometry.NumPointsGeometry.NumPoints
Geometry.OgcGeometryTypeGeometry.OgcGeometryType
Geometry.Overlaps(Geometry)Geometry.Overlaps(Geometry)
Geometry.PointOnSurfaceGeometry.PointOnSurface
Geometry.Relate (Geometry, chaîne)Geometry.Relate(Geometry, string)
Geometry.Reverse()Geometry.Reverse()
Geometry.SRIDGeometry.SRID
Geometry.SymmetricDifference(Geometry)Geometry.SymmetricDifference(Geometry)
Geometry.ToBinary()Geometry.ToBinary()
Geometry.ToText()Geometry.ToText()
Geometry.Touches(Geometry)Geometry.Touches(Geometry)
Geometry.Union()Geometry.Union()
Geometry.Union(Geometry)Geometry.Union(Geometry)
Geometry.Within(Geometry)Geometry.Within(Geometry)
GeometryCollection.CountGeometryCollection.Count
GeometryCollection [int]GeometryCollection[int]
LineString.CountLineString.Count
LineString.EndPointLineString.EndPoint
LineString.GetPointN(int)LineString.GetPointN(int)
LineString.IsClosedLineString.IsClosed
LineString.IsRingLineString.IsRing
LineString.StartPointLineString.StartPoint
MultiLineString.IsClosedMultiLineString.IsClosed
Point.MPoint.M
Point.XPoint.X
Point.YPoint.Y
Point.ZPoint.Z
Polygon.ExteriorRingPolygon.ExteriorRing
Polygon.GetInteriorRingN(int)Polygon.GetInteriorRingN(int)
Polygon.NumInteriorRingsPolygon.NumInteriorRings

Ressources supplémentairesAdditional resources