OutWit.Common.Json 1.1.3

OutWit.Common.Json

This library enhances System.Text.Json by providing a set of intuitive extension methods and a powerful, performance-oriented architecture.

Key Features

• Fluent Extension Methods: Simplifies serialization and deserialization to and from strings and byte arrays.
• Source Generation Ready: Boost performance and reduce memory allocation by using System.Text.Json source generation. The library provides a mechanism to register your own JsonSerializerContext.
• Merged Context Resolver: Combines multiple JsonSerializerContext instances, falling back to reflection if a type is not found in any registered context. This gives you the performance of source generation with the flexibility of reflection.
• Built-in Default Context: Comes with a pre-configured context for a wide range of primitive types, arrays, and lists, so it works great out of the box.
• Custom Converters Included:
  • Type: Serializes System.Type objects to their assembly-qualified names.
  • RSAParameters: Serializes System.Security.Cryptography.RSAParameters structures.
• File I/O Helpers: Easily export collections to JSON files or load them back, with both synchronous and asynchronous methods available.
• Graceful Error Handling: Methods safely handle exceptions during serialization/deserialization, returning null or default and optionally logging errors via Microsoft.Extensions.Logging.
• Deep Cloning: A simple JsonClone() extension method to create a deep copy of an object.

Installation

Install the package from NuGet:

Install-Package OutWit.Common.Json

Or via the .NET CLI:

dotnet add package OutWit.Common.Json

Basic Usage

The library provides easy-to-use extension methods for any object.

using OutWit.Common.Json;

public class User
{
    public int Id { get; set; }
    public string Name { get; set; }
}

var user = new User { Id = 1, Name = "John Doe" };

// Serialize to a JSON string
string json = user.ToJsonString(); // {"Id":1,"Name":"John Doe"}

// Serialize to an indented JSON string
string indentedJson = user.ToJsonString(indented: true);
/*
{
  "Id": 1,
  "Name": "John Doe"
}
*/

// Deserialize from a JSON string
var deserializedUser = json.FromJsonString<User>();

// Create a deep clone of the object
var clonedUser = user.JsonClone();

Advanced Usage: Using Source Generation

For optimal performance, especially in AOT (Ahead-of-Time) compiled scenarios, you can use your own source-generated JsonSerializerContext.

1. Define your data models and a JsonSerializerContext:

using System.Text.Json.Serialization;

namespace MyApp.Models
{
    public class Product
    {
        public string Sku { get; set; }
        public decimal Price { get; set; }
    }

    // Define a context for your types
    [JsonSerializable(typeof(Product))]
    [JsonSerializable(typeof(Product[]))]
    internal partial class AppJsonContext : JsonSerializerContext
    {
    }
}

2. Register your context at application startup:

using OutWit.Common.Json;
using MyApp.Models;

public static class Program
{
    public static void Main(string[] args)
    {
        // Register your context with OutWit.Common.Json
        JsonUtils.Register(new AppJsonContext());

        // Now, all serialization calls will use your generated context
        // for the Product type, falling back for other types.
        var product = new Product { Sku = "ABC-123", Price = 99.99m };
        string json = product.ToJsonString();

        System.Console.WriteLine(json);
    }
}

You can also use the optionsBuilder to register multiple contexts.

JsonUtils.Register(options => 
{
    options.Contexts.Add(new AppJsonContext());
    options.Contexts.Add(new AnotherContext());
});

License

Licensed under the Apache License, Version 2.0. See LICENSE.

Attribution (optional)

If you use OutWit.Common.Json in a product, a mention is appreciated (but not required), for example: "Powered by OutWit.Common.Json (https://ratner.io/)".

Trademark / Project name

"OutWit" and the OutWit logo are used to identify the official project by Dmitry Ratner.

You may:

• refer to the project name in a factual way (e.g., "built with OutWit.Common.Json");
• use the name to indicate compatibility (e.g., "OutWit.Common.Json-compatible").

You may not:

• use "OutWit.Common.Json" as the name of a fork or a derived product in a way that implies it is the official project;
• use the OutWit.Common.Json logo to promote forks or derived products without permission.