BitBadger.Documents
Advanced Usage: Custom Serialization
Documentation pages for BitBadger.Npgsql.Documents redirect here. This library replaced it as of v3; see project home if this applies to you.
JSON documents are sent to and received from both PostgreSQL and SQLite as strings; the translation to and from your domain objects (commonly called POCOs) is handled via .NET. By default, the serializer used by the library is based on System.Text.Json with converters for common F# types.
Implementing a Custom Serializer
IDocumentSerializer (found in the BitBadger.Documents namespace) specifies two methods. Serialize<T> takes a T and returns a string; Deserialize<T> takes a string and returns an instance of T. (These show as 'T in F#.) While implementing those two methods is required, the custom implementation can use whatever library you desire, and contain converters for custom types.
Once this serializer is implemented and constructed, provide it to the library:
// C# var serializer = /* constructed serializer */; Configuration.UseSerializer(serializer);
// F# let serializer = (* constructed serializer *) Configuration.useSerializer serializer
The biggest benefit to registering a serializer (apart from control) is that all JSON operations will use the same serializer. This is most important for PostgreSQL's JSON containment queries; the object you pass as the criteria will be translated properly before it is compared. However, “unstructured” data does not mean “inconsistently structured” data; if your application uses custom serialization, extending this to your documents ensures that the structure is internally consistent.
Uses for Custom Serialization
- If you use a custom serializer (or serializer options) in your application, a custom serializer implementation can utilize these existing configuration options.
- If you prefer
Newtonsoft.Json, you can wrapJsonConvertorJsonSerializercalls in a custom converter. F# users may consider incorporating Microsoft'sFSharpLu.Jsonconverter. - If your project uses
NodaTime, your custom serializer could include its converters forSystem.Text.JsonorNewtonsoft.Json. - If you use DDD to define custom types, you can implement converters to translate them to/from your preferred JSON representation.