👁 Image
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.