ESENT Serialization Class Library
This article only answers the questions "What?" and "How?". For the "Why?" information, see the corresponding page in "Articles" section.
Features
- Serializes and deserializes objects. To mark the object to be your database record type, apply [EseTable] attribute to your record class, and column attributes to the class members.
- 27 column types, ranging from something as simple as a byte or int32, to enums, multi-valued strings, or arbitrary objects serialized with either XmlSerializer or DataContractSerializer.
- The library is multithreading-aware. Concurrent database access by several threads is OK.
- Suitable for building both Windows desktop software, and servers including ASP.NET web applications. This web site stores registered users, their avatar images, and the commens they've posted in the ESENT database: no SQL or file storage is required.
- The complete absense of database query language improves the web application security: unless you've explicitly written the code to modify a specific column in your table, you can be sure your data is safe. Using this library completely eliminates possibility of SQL injection-class attacks.
- Table-granular change notification mechanism (practically untested, to be honest).
- The recordsets support filtering and sorting by the ESE indexes, which is much more efficient then using LINQ with its O(n)+ complexity.
- The recordset returns records as the IEnumerable<tRow> (where tRow is your record class that has the [EseTable] attribute applied) suitable for lazy evaluation, making it possible to sequentially process a huge dataset that does not even fit in your RAM.
- Provides data binding mechanisms for windows forms controls: see the documentation on EditableObjectList generic class. For example, you can build a form with DataGridView displaying the whole ESENT table with just a dozen lines of code.
- Import/export of the tables to an Excel-friendly format (UCS2-encoded tab-separated values, to be precise).
- Although no remote database access API is provided, records can be easily serialized into arrays of bytes for replicating across the LAN. The DB is suitable for building redundant distributed systems. Some optimizations were made specially for inexpensive Amazon EC2 small instances running Windows Server 2003 R2.
- Just like the Managed ESENT, the DLL is architecture-neutral ("Any CPU").
- Good documentation.
ESENT features
- Reliable, high-performance, low-overhead storage of structured or semi-structured data.
- Wide range of columns values, ranging in size from 1 byte to (2 GB - 1).
- Auto increment columns.
- Sophisticated indexing: multi-column, sparse, and tuple indexes.
- Data consistency is maintained even in the event of a system crash.
- ESE caches data intelligently to ensure high performance access to data.
- Snapshot isolation.
Shortcomings
- I never tested the library itself. Some parts of the library are untested (binary format import / export), other parts are tested poorly (VirtualMode).
- Only tested on Vista, Windows 7, Windows Server 2003 and 2008.
- Only tested with C# language, Visual Studio 2008 and 2010, .NET framework 3.5 SP1 and 4.0.
- No DB schema upgrade mechanism is currently implemented.
- My design goal was to simplify the developing of ESENT-based software. I did not want to create an additional level of abstraction, see the law of leaky abstractions for the reason why. To efficiently use the library, you'll have to understand (to some extent) the underlying ESENT technology.
License
Free for both commercial and non-commercial use.
You can freely redistribute the DLL along with your software.
You may not decompile the DLL and/or claim you're the author of the library.
Downloads
The latest version is 1.7.0. Here's the change log (will open in a new window).
The class library binaries, including the latest version of managed Esent.
A console demo project demonstrates recordsets operations.
A WinForms demo project demonstrates data binding to a DataGridView control.
Both demo projects use the same database. You may use a WinForms demo to put some data,
then use the console application to test filtering.
Note on demo projects
If you're going to modify the DB schema (by modifying the Ese* attributes applied to the Person class and its fields), don't forget to delete old database, which is located in %APPDATA%\EsentDemoApp folder. Since there's no DB schema upgrade mechanism, you'll just get an exception if the schema of the existing database is not the same as the schema derived from your records classes.
File System Demo
The file system demo project (advanced) demonstrates how to implement a file system on the top of ESENT database.
Don't be scared with many source files in the project: most of them implement various GUI features, windows shell integration, or related utilities. See "FileSystem/EfsEntry.cs" for the file system entry record class, and "FileSystem/EFS.cs" for the static class implementing some file system operations.
The storage overhead is about 10% (more while adding files because of the transaction logs). The throughput is adequate: write rate might be better (about 7-8 megabytes / second on my old Core 2 Duo PC), the read rate is pretty good ( 60 megabytes / second on my old PC ).