Skip to content

Extends the basic JSON Serialization/Deserialization functionality of System.Text.Json.

Notifications You must be signed in to change notification settings

wayfair-incubator/WaySON

Repository files navigation

WaySON

WaySON Version Contributor Covenant .NET Build & Test Lint Markdown files codecov

About this project

Extends the basic JSON Serialization/Deserialization functionality of System.Text.Json.

System.Text.Json was built as a replacement for Newtonsoft, with a focus on performance. Both its .NET Core 3.1 and .NET 5 iterations, however, lack support for some desireable types. In .NET Core 3.1 in particular, there is noticeable missing support for dictionaries with non-string keys, quoted numbers, and specification of DateFormatString settings when handling DateTime and DateTimeOffset. While .NET 5 introduced support for dictionaries with non-string keys and quoted numbers, it still lacks support for specification of DateFormatString when handling DateTime and DateTimeOffset, so using this library may still be desirable for applications running .NET 5 and above.

Notable Features

  • Serialize and deserialize Dictionary<TKey, TValue> with non-string keys.
  • Serialize and deserialize numbers represented by JSON strings (surrounded by quotes). For example, it can accept: {"DegreesCelsius":"23"} instead of {"DegreesCelsius":23}.
  • Serialize and deserialize DateTime and DateTimeOffset with support for specification of DateFormatString.
  • A JsonBinder, suitable for when you already have an existing object instance to bind JSON to.

Installation

dotnet add package WaySON

Usage

There are three ways this package can be used:

  1. Explicit calls to WaySONSerializer.Serialize and WaySONSerializer.Deserialize methods
  2. Configuration of .NET's MVC framework using .AddJsonOptions(...) in startup
  3. Calls to JsonBinder.BindToObject for scenarios when you already have an existing object instance on hand to bind values to

WaySONSerializer

Use this instead of calling the native JsonSerializer methods if you need to make an explicit call to Serialize/Deserialize:

// To Serialize object to json:
var json = WaySONSerializer.Serialize(obj);

// To Deserialize json to object of type T:
var obj = WaySONSerializer.Deserialize<T>(json);

// or if you don't know the type at compile time: 
var obj = WaySONSerializer.Deserialize(json, type);

MVC

This is for automatic serialization for when data leaves a controller in .NET's MVC. To further customize, in your startup file, in the ConfigureServices method, chain AddJsonOptions after AddMvcCore:

services
    .AddMvcCore()
    .AddJsonOptions(options =>
    {
        // You can choose which options to use. Here, we use the default ones set in WaySONSerializer.
        options.JsonSerializerOptions.PropertyNamingPolicy = WaySONSerializer.Options().PropertyNamingPolicy;
        options.JsonSerializerOptions.PropertyNameCaseInsensitive = WaySONSerializer.Options().PropertyNameCaseInsensitive;
        
        // Add custom converters. Here, we add all the custom converters in WaySONSerializer, then add another custom MyTypeConverter
        // You can add more, or filter some out by not adding them.
        foreach (var jsonConverter in WaySONSerializer.Options().Converters)
        {
            options.JsonSerializerOptions.Converters.Add(jsonConverter);
        }

        options.JsonSerializerOptions.Converters.Add(new MyTypeConverter());
    })   
    ...

JsonBinder

If you already have an object instance on hand that you would like to bind some JSON to, using JsonBinder may be preferable:

var dictionary = new Dictionary<string, string>();

const string json = @"
    {
        ""key_one"": ""value_one"",
        ""key_two"": ""value_two""
    }";

dictionary = JsonBinder.BindToObject(dictionary, json);

Roadmap

See the open issues for a list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated. For detailed contributing guidelines, please see CONTRIBUTING.md.

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Maintainers: MAINTAINERS.md

Project Link: https://github.com/wayfair-incubator/wayson

Acknowledgements

This README was adapted from https://github.com/othneildrew/Best-README-Template.

References

About

Extends the basic JSON Serialization/Deserialization functionality of System.Text.Json.

Topics

Resources

Code of conduct

Security policy

Stars

Watchers

Forks

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •  

Languages