Corvus.Extensions.System.Text.Json

This provides opinionated configuration and DI support for System.Text.Json serialization.

It is built for netstandard2.0.

Features

IJsonSerializationOptionsProvider

It is common to need to configure and manage a consistent set of JsonSerializationOptions across multiple components, to ensure succesful interop between services, both within and between hosts.

In order to support this, we have an IJsonSerializationOptionsProvider service which has a single Instance property which (as the naming implies) gives you an instance of System.Text's JsonSerializationOptions, in a known configuration.

We also supply a standard implementation of this service called JsonSerializationSettingsProvider.

This is configured for enum serialization as strings, camelCase property names, no dictionary key mapping, and ignored null values.

You can see the current defaults here.

One feature of this implementation is that it takes an enumerable of JsonConverter objects in its constructor. If you register it in the Microsoft.Extensions.DependencyInjection container using the IServiceCollection extension method called AddJsonSerializationOptions(), then you get the powerful feature that it will then have its converters configured from the container too. Components that wish to add their converters to the standard settings need only add them to the container.

The default implementation adds the following converters

services.AddSingleton<JsonConverter, CultureInfoConverter>();
services.AddSingleton<JsonConverter, DateTimeOffsetConverter>();
services.AddSingleton<JsonConverter, PropertyBagConverter>();
services.AddSingleton<JsonConverter>(new JsonStringEnumConverter(JsonNamingPolicy.CamelCase));

Standard JsonConverter

DateTimeOffsetConverter

(Nullable) DateTimeOffset (which converts to/from json of the form {"dateTimeOffset":"<Roundtrippable string format>", "unixTime": <long of unix milliseconds>}, and from standard JSON date strings.

CultureInfoConverter

which converts to/from the culture name string e.g. en-GB, fr-FR

PropertyBag

A handy serializable property bag which converts to/from strongly typed key value pairs, internally stored in a JSON representation.

You can construct an empty PropertyBag

var propertyBag = new PropertyBag();

Or from a string

string someJsonString;
var propertyBag = new PropertyBag(someJsonString);

Or from an IDictionary<string,object>

IDictionary<string,object> someDictionary;
var propertyBag = new PropertyBag(someDictionary);

You can then set or retrieve strongly typed values from the property bag.

int myValue = 3;
var myObject = new SomeType("Hello world", 134.6);

propertyBag.Set("property1", myValue);
propertyBag.Set("property2", myObject);

propertyBag.TryGet("property1", out int myRetrievedValue); // returns true
propertyBag.TryGet("property2", out SomeType myRetrievedObject); // returns true
propertyBag.TryGet("property3", out double wontWork); // returns false 

Internally, it stores the values using a JSON representation. This means that you can happily set as one type, and retrieve as another, as long as your serializer supports that conversion.

public class SomeType
{
  public SomeType()
  {
  }
  
  public SomeType(string property1, int property2)
  {
    this.Property1 = property1;
    this.Property2 = property2;
  }
  
  public string Property1 { get; set; }
  public int Property2 { get; set; }
}

public class SomeSemanticallySimilarType
{
  public SomeSemanticallySimilarType()
  {
  }
  
  public SomeSemanticallySimilarType(string property1, int property2)
  {
    this.Property1 = property1;
    this.Property2 = property2;
  }
  
  public string Property1 { get; set; }
  public int Property2 { get; set; }
  public bool? Property3 { get; set; }
}

propertyBag.Set("key1", new SomeType("Hello", 3));
propertyBag.TryGet("key1", out SomeSemanticallySimilarType myRetrievedObject); // returns true

Conversions

You can implicitly convert the PropertyBag to and from a string , and there is an AsDictionary() method which returns a Dictionary<string,object>. This can also be used to enumerate the underlying JToken values.

JsonSerializationOptions

Internally, all the property values are stored in a JSON string. There are overloads for each constructor that allow you to set the JsonSerializationOptions to be used for serialization and deserialization conversions. It also has a constructor which takes the IJsonSerializationOptionsProvider described above.

Microsoft.Extensions.DependencyInjection

While you can create instances of this type by hand, it is recommended that you use the container to obtain instances instead. If you use the AddJsonSerializationOptions() extension method, then PropertyBag is registered as a transient and will typically retrieve its serializer settings from the IJsonSerializationOptionsProvider.

Licenses

Corvus.Extensions.System.Text.Json is available under the Apache 2.0 open source license.

For any licensing questions, please email licensing@endjin.com

Project Sponsor

This project is sponsored by endjin, a UK based Microsoft Gold Partner for Cloud Platform, Data Platform, Data Analytics, DevOps, and a Power BI Partner.

For more information about our products and services, or for commercial support of this project, please contact us.

We produce two free weekly newsletters; Azure Weekly for all things about the Microsoft Azure Platform, and Power BI Weekly.

Keep up with everything that's going on at endjin via our blog, follow us on Twitter, or LinkedIn.

Our other Open Source projects can be found on GitHub

Code of conduct

This project has adopted a code of conduct adapted from the Contributor Covenant to clarify expected behavior in our community. This code of conduct has been adopted by many other projects. For more information see the Code of Conduct FAQ or contact hello@endjin.com with any additional questions or comments.

IP Maturity Matrix (IMM)

The IMM is endjin's IP quality framework.