StarThrower.Gis.EsriLibrary 2.0.0

StarThrower.Gis.EsriLibrary

Read and write ESRI shapefile format (.shp/.dbf) including support for points, polylines, polygons, and multipart shapes.

StarThrower.Gis.EsriLibrary provides ShapeFile, a high-level wrapper that pairs a .shp geometry file with its companion .dbf attribute table (via StarThrower.XBase) and exposes them as a single set of records — each combining an attribute Record with a StarThrower.Gis.GeoUtilities.Shapes.Shape geometry.

Installation

dotnet add package StarThrower.Gis.EsriLibrary

Core Types

Field Types (Types namespace)

Types.FieldType is an abstract base deriving from StarThrower.XBase.FieldType; each concrete type delegates MinLength/MaxLength, MinDecimalCount/MaxDecimalCount, IsValidLength/IsValidDecimalCount/IsValidData, and Translate to the corresponding StarThrower.XBase field type, so validation and on-disk representation match the underlying .dbf exactly.

Usage

using StarThrower.Gis.EsriLibrary;
using StarThrower.Gis.EsriLibrary.Types;
using StarThrower.Gis.GeoUtilities.Shapes;

// Create a new point shapefile and define its attribute schema
using ShapeFile shapeFile = new ShapeFile();
shapeFile.ShapeType = ShapeType.Point;

shapeFile.AddField(new Field { Name = "NAME", Type = new StringField(), Length = 30 });
shapeFile.AddField(new Field { Name = "POP", Type = new NumericField(), Length = 9 });

// Add a record
Record record = shapeFile.CreateNewRecord();
record.SetShape(new PointShape(-77.0365, 38.8977));
record.SetData("NAME", "Washington, DC");
record.SetData("POP", 689545L);
shapeFile.AddRecord(record);

shapeFile.SaveAs(@"cities.shp"); // writes cities.shp and cities.dbf

// Read records back
shapeFile.Open(@"cities.shp", FileMode.Open, FileAccess.Read);
for (int i = 0; i < shapeFile.RecordCount; i++)
{
    Record r = shapeFile.GetRecord(i);
    PointShape point = (PointShape)r.GetShape();
    string name = (string)r.GetData("NAME")!;
}

Exporting to XML

using StarThrower.Gis.GeoUtilities.Formatting;

string fileWiseXml = shapeFile.ToXml(XmlFormat.FileWise);  // separate geography/data sections
string layerWiseXml = shapeFile.ToXml(XmlFormat.LayerWise); // combined geography+data per record

LoadXml(XmlDocument, XmlFormat) reads the LayerWise format back (schema, extent, and field definitions). See Known Limitations below for Gml, ToJson/LoadJson, and other unimplemented paths.

Usage Notes

• Opening a shapefile. Open/SaveAs take the .shp path; the companion .dbf is derived by replacing the extension and opened/saved alongside it. Open throws InvalidDataException if the .shp and .dbf record counts don't match.
• AddRecord validates ShapeType. A Record's shape must match the ShapeFile's ShapeType, or AddRecord throws ArgumentException.
• Field type round-tripping. Field/Types.FieldType mirror StarThrower.XBase's XBaseField/FieldType exactly — internal conversion helpers translate between the two so the .dbf written alongside the .shp is a standard dBASE III file.
• Geometry types. ShapeType values map one-to-one to StarThrower.Gis.GeoUtilities.Shapes.ShapeType values; CreateNewRecord() returns a Record pre-populated with the matching Shapes.Shape subtype (e.g. PointShape, PolygonShape, PolylineZShape) for the shapefile's ShapeType.

Known Limitations

• Only four shape types fully read and write geometry. NullShape, Point, PolyLine, and Polygon are fully implemented. The other ten ShapeType values — MultiPoint, PointZ, PolyLineZ, PolygonZ, MultiPointZ, PointM, PolyLineM, PolygonM, MultiPointM, and MultiPatch — throw NotImplementedException as soon as a record of that shape type is added via ShapeFile.AddRecord. See issues #17–#26.
• .prj projection files can be read but not written. Reading resolves the British National Grid and all WGS72/WGS84 UTM zones from a .prj file's PROJCS name, but ShapeFile.Save/SaveAs never write projection data back out — the underlying write path is unimplemented. See #16.
• AlterRecord, ToJson, and LoadJson are unimplemented stubs that throw NotImplementedException. ToXml(XmlFormat.Gml) and LoadXml with XmlFormat.Gml or XmlFormat.FileWise silently produce no output rather than throwing. See #34 and #35.

Dependencies

• StarThrower.ByteUtilities — endian-aware byte conversions used internally for .shp/.shx binary record headers and geometry data.
• StarThrower.Gis.GeoUtilities — Shapes geometry types, GeoRectangle, and XML formatting (XmlFormat).
• StarThrower.StringUtilities — XML encoding and string padding helpers.
• StarThrower.XBase — the .dbf attribute table read/write implementation underlying ShapeFile's field and record support.

License

Copyright © 2026 Stephen Elmer. Licensed under the MIT License.