EonaCat.Json 2.2.5

EonaCat.Json

A high-performance JSON library for .NET with support for serialization, deserialization, LINQ-to-JSON (JSONL), JSON Schema validation, BSON, and XML/JSON conversion. Built with multi-framework support targeting .NET Framework 4.8, .NET Standard 2.0/2.1, and .NET 6 through .NET 10.

Features

Multiple Serialization Engines

• Traditional JSON serialization via JsonHelper
• High-performance FastJson implementation
• Streaming JSON support

LINQ to JSON (JSONL)

• JObject, JArray, JToken for flexible JSON manipulation
• JSONPath queries with JPath
• JSON merging and diffing

Type Support

• Custom converters for dates, enums, XML, BSON, and more
• Support for generic types, collections, and dynamic objects
• Strong typing with JsonSerializer

JSON Schema Validation

• JSON Schema draft 3, 4, 6, 7, and 2019-09 support
• Schema generation from types
• Validation with detailed error reporting

BSON Support

• Full BSON serialization/deserialization
• BSON readers and writers
• MongoDB ObjectID support

XML/JSON Conversion

• Bidirectional XML ↔ JSON transformation
• XPath and structured element mapping

Enterprise Features

• Data protection with encryption (AES, DPAPI)
• Circular reference detection
• Property name strategies (CamelCase, KebabCase, SnakeCase, etc.)
• Async support for streaming operations

Multi-Framework Compatibility

• .NET Framework 4.8
• .NET Standard 2.0 / 2.1
• .NET 6, 7, 8, 9, 10

Installation

NuGet Package

dotnet add package EonaCat.Json

Or install via NuGet Package Manager:

Install-Package EonaCat.Json

Quick Start

Basic Serialization / Deserialization

using EonaCat.Json;

// Serialize object to JSON string
var person = new { Name = "John", Age = 30 };
string json = JsonHelper.ToJson(person);
// Output: {"Name":"John","Age":30}

// Deserialize JSON string to object
var obj = JsonHelper.ToObject<dynamic>(json);
Console.WriteLine(obj.Name); // Output: John

Using FastJson (High-Performance)

using EonaCat.Json.Fast;

// Serialize
var data = new { Id = 1, Title = "Hello" };
string json = Json.ToJson(data);

// Deserialize
var obj = Json.ToObject<MyClass>(json);

Working with Dynamic JSON

using EonaCat.Json;

string json = @"{ ""name"": ""Alice"", ""age"": 25 }";

// Parse to dynamic object
dynamic obj = JsonHelper.ToObject<dynamic>(json);
Console.WriteLine(obj.name); // Alice
Console.WriteLine(obj.age);  // 25

Core Serialization

JsonHelper - Full-Featured Serialization

The JsonHelper static class provides comprehensive JSON serialization with control over formatting, type handling, and custom converters.

Basic Methods

// Simple serialization
string json = JsonHelper.ToJson(myObject);

// With formatting
string prettyJson = JsonHelper.ToJson(myObject, Formatting.Indented);

// With custom converters
string json = JsonHelper.ToJson(myObject, new IsoDateTimeConverter());

// With settings
var settings = new JsonSerializerSettings
{
    NullValueHandling = NullValueHandling.Ignore,
    DateFormatHandling = DateFormatHandling.IsoDateFormat
};
string json = JsonHelper.ToJson(myObject, settings);

Deserialization

// Deserialize to specific type
MyClass obj = JsonHelper.ToObject<MyClass>(jsonString);

// Deserialize from Stream
using (FileStream fs = File.OpenRead("data.json"))
{
    MyClass obj = JsonHelper.ToObject<MyClass>(fs);
}

// With type hint
object obj = JsonHelper.ToObject(jsonString, typeof(MyClass));

Available Methods

// Serialization overloads
public static string ToJson(object? value);
public static string ToJson(object? value, Formatting formatting);
public static string ToJson(object? value, params Converter[] converters);
public static string ToJson(object? value, Formatting formatting, JsonSerializerSettings? settings);
public static string ToJson(object? value, Type? type, Formatting formatting, JsonSerializerSettings? settings);

// For very large objects
public static string ToJsonLarge<T>(T value, Formatting formatting = Formatting.None, JsonSerializerSettings? settings = null);

// Deserialization overloads
public static T ToObject<T>(string json, JsonSerializerSettings? settings = null);
public static object ToObject(string json, Type targetType, JsonSerializerSettings? settings = null);
public static T ToObject<T>(Stream s);

Fast JSON - High-Performance Serialization

The FastJson class provides optimized serialization for performance-critical scenarios.

using EonaCat.Json.Fast;

// Basic usage
string json = Json.ToJson(myObject);
MyClass obj = Json.ToObject<MyClass>(json);

// Parse to dynamic node representation
JsonNode node = Json.Parse(json);
Console.WriteLine(node["property"]); // Access properties dynamically

// With options
var options = new JsonOptions 
{ 
    /* Configure serialization options */ 
};
string json = Json.ToJson(myObject, options);

Attributes for FastJson

// Ignore properties
[JsonIgnore]
public string InternalId { get; set; }

// Custom property names
[JsonProperty("user_name")]
public string UserName { get; set; }

// Skip null values
[JsonProperty(IgnoreIfNull = true)]
public string? OptionalField { get; set; }

LINQ to JSON

The LINQ to JSON API (JToken, JObject, JArray, JProperty, JValue) enables flexible, query-like manipulation of JSON data without requiring strong typing.

JObject - JSON Object

using EonaCat.Json.Linq;

// Create from scratch
JObject obj = new JObject();
obj["name"] = "John";
obj["age"] = 30;

// Create with initialization
JObject obj = new JObject(
    new JProperty("name", "John"),
    new JProperty("age", 30)
);

// Load from JSON string
JObject obj = JObject.Parse(@"{ ""name"": ""John"", ""age"": 30 }");

// Access properties
string name = (string)obj["name"];
int age = (int)obj["age"];

// Enumerate
foreach (JProperty prop in obj.Properties())
{
    Console.WriteLine($"{prop.Name}: {prop.Value}");
}

// Convert to strongly-typed object
MyClass person = obj.ToObject<MyClass>();

// Convert to JSON string
string json = obj.ToString();

JArray - JSON Array

// Create array
JArray array = new JArray(1, 2, 3, 4, 5);

// Create with objects
JArray users = new JArray(
    new JObject(new JProperty("name", "John")),
    new JObject(new JProperty("name", "Jane"))
);

// Load from JSON
JArray array = JArray.Parse(@"[1, 2, 3, 4, 5]");

// Access elements
int first = (int)array[0];

// Add elements
array.Add("new element");

// Query with LINQ
var adults = array
    .Where(x => (int)x["age"] >= 18)
    .ToList();

// Convert to list
List<MyClass> items = array.ToObject<List<MyClass>>();

JToken - Base Token

// Parse any JSON
JToken token = JToken.Parse(jsonString);

// Check type
if (token.Type == JTokenType.Object)
{
    JObject obj = (JObject)token;
}
else if (token.Type == JTokenType.Array)
{
    JArray arr = (JArray)token;
}

// Safe conversion
if (token is JObject obj)
{
    string name = (string)obj["name"];
}

JSONPath Queries

JObject data = JObject.Parse(@"
{
    ""users"": [
        { ""name"": ""John"", ""age"": 30 },
        { ""name"": ""Jane"", ""age"": 25 }
    ]
}");

// Select with JSONPath
JToken users = data.SelectToken("$.users");
JToken firstUser = data.SelectToken("$.users[0]");
IEnumerable<JToken> adults = data.SelectTokens("$.users[?(@.age >= 30)]");

JSON Merging

JObject obj1 = JObject.Parse(@"{ ""name"": ""John"", ""age"": 30 }");
JObject obj2 = JObject.Parse(@"{ ""age"": 31, ""city"": ""NYC"" }");

// Merge objects
obj1.Merge(obj2);
// Result: { "name": "John", "age": 31, "city": "NYC" }

Custom Attributes

Attributes allow fine-grained control over serialization behavior:

JsonPropertyAttribute

public class Person
{
    [JsonProperty("full_name")]
    public string Name { get; set; }

    [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
    public string? Title { get; set; }

    public int Age { get; set; }
}

JsonIgnoreAttribute

public class Person
{
    public string Name { get; set; }

    [JsonIgnore]
    public string Password { get; set; } // Excluded from serialization
}

JsonObjectAttribute & JsonArrayAttribute

[JsonObject(ItemRequired = Required.Always)]
public class User
{
    [JsonProperty(Required = Required.Always)]
    public string Username { get; set; }

    public string? Email { get; set; }
}

[JsonArray]
public class UserList : List<User> { }

JsonConverterAttribute

public class Event
{
    [JsonConverter(typeof(IsoDateTimeConverter))]
    public DateTime Timestamp { get; set; }

    [JsonConverter(typeof(StringEnumConverter))]
    public EventType Type { get; set; }
}

JsonConstructorAttribute

public class Point
{
    public int X { get; }
    public int Y { get; }

    [JsonConstructor]
    public Point(int x, int y)
    {
        X = x;
        Y = y;
    }
}

Converters

Built-in converters for specialized type handling:

DateTime Converters

var settings = new JsonSerializerSettings
{
    Converters = new JsonConverter[] 
    { 
        new IsoDateTimeConverter(),      // ISO 8601
        new JavaScriptDateTimeConverter(),
        new UnixDateTimeConverter()       // Unix timestamp
    }
};

string json = JsonHelper.ToJson(datetime, settings);

Enum Converters

// String values instead of integers
var settings = new JsonSerializerSettings
{
    Converters = new[] { new StringEnumConverter() }
};

string json = JsonHelper.ToJson(enumValue, settings);
// Result: "EnumValue" instead of 0

Special Type Converters

// Version
var converter = new VersionConverter();

// Key-Value pairs
var keyValueConverter = new KeyValuePairConverter();

// Binary data
var binaryConverter = new BinaryConverter();

// Regex patterns
var regexConverter = new RegexConverter();

// BSON ObjectId
var objectIdConverter = new BsonObjectIdConverter();

DataTable & DataSet Converters

var settings = new JsonSerializerSettings
{
    Converters = new[] { new DataTableConverter() }
};

string json = JsonHelper.ToJson(dataTable, settings);
DataTable dt = JsonHelper.ToObject<DataTable>(json, settings);

XML Converters

// Convert XDocument to JSON
var converter = new XmlNodeConverter();
XDocument doc = XDocument.Load("data.xml");
string json = JsonConvert.SerializeXNode(doc);

// Convert JSON to XML
string xmlJson = @"{ 'root': { 'item': 'value' } }";
XDocument doc = JsonConvert.DeserializeXNode(xmlJson);

Custom Converters

public class CustomConverter : JsonConverter
{
    public override bool CanConvert(Type objectType)
    {
        return objectType == typeof(MyCustomType);
    }

    public override object ReadJson(JsonReader reader, Type objectType, 
        object existingValue, JsonSerializer serializer)
    {
        // Custom deserialization logic
        string value = reader.Value as string;
        return new MyCustomType(value);
    }

    public override void WriteJson(JsonWriter writer, object value, 
        JsonSerializer serializer)
    {
        // Custom serialization logic
        writer.WriteValue(value.ToString());
    }
}

JSON Schema

Validate JSON against schemas and generate schemas from .NET types:

Schema Validation

using EonaCat.Json.Schema;

// Load schema
JSchema schema = JSchema.Parse(@"
{
    'type': 'object',
    'properties': {
        'name': { 'type': 'string' },
        'age': { 'type': 'integer', 'minimum': 0 }
    },
    'required': ['name']
}");

// Validate JSON
JObject data = JObject.Parse(@"{ 'name': 'John', 'age': 30 }");
bool isValid = data.IsValid(schema);

// With error collection
IList<string> errors = new List<string>();
bool isValid = data.IsValid(schema, out errors);
foreach (var error in errors)
{
    Console.WriteLine(error);
}

Schema Generation

// Generate schema from type
var generator = new JSchemaGenerator();
JSchema schema = generator.Generate(typeof(MyClass));

// Get schema as JSON
string schemaJson = schema.ToString();

Multi-Draft Support

// Specify schema version
var settings = new JSchemaReaderSettings 
{ 
    SchemaVersion = SchemaVersion.Draft7 
};

JSchema schema = JSchema.Load(schemaUri, settings);

Schema Reference Resolution

// Use custom resolver for external schemas
var resolver = new JSchemaPreloadedResolver();
resolver.Add(new Uri("http://example.com/schema.json"), 
    JSchema.Parse(schemaJson));

var settings = new JSchemaReaderSettings { Resolver = resolver };
JSchema schema = JSchema.Load(uri, settings);

BSON Support

Binary JSON format support for MongoDB and similar systems:

using EonaCat.Json.Bson;

// Serialize to BSON
BsonWriter writer = new BsonWriter();
JsonSerializer.Create().Serialize(writer, myObject);
byte[] bsonData = writer.GetBuffer();

// Deserialize from BSON
BsonReader reader = new BsonReader(bsonData);
var obj = JsonSerializer.Create().Deserialize<MyClass>(reader);

// Working with BSON types
BsonObject bsonObj = new BsonObject();
bsonObj["name"] = new BsonString("John");
bsonObj["age"] = new BsonValue(30);

// MongoDB ObjectID
var objectId = new BsonObjectId(ObjectId.GenerateNewId().ToByteArray());

XML Integration

Seamless conversion between JSON and XML:

JSON to XML

using EonaCat.Json;

string jsonString = @"
{
    'root': {
        'person': {
            'name': 'John',
            'age': 30
        }
    }
}";

// Convert to XML
XDocument doc = JsonConvert.DeserializeXNode(jsonString, "root");
doc.Save("output.xml");

XML to JSON

// Convert to JSON
XDocument doc = XDocument.Load("input.xml");
string json = JsonConvert.SerializeXNode(doc, Formatting.Indented);
Console.WriteLine(json);

XPath Integration

// Load and query with XPath
XDocument doc = XDocument.Load("data.xml");
var elements = doc.XPathSelectElements("//person[age>25]");

// Convert to JSON
string json = JsonConvert.SerializeXNode(doc);

Advanced Features

Controlling Serialization Behavior

var settings = new JsonSerializerSettings
{
    // Handle null values
    NullValueHandling = NullValueHandling.Ignore,

    // Default value handling
    DefaultValueHandling = DefaultValueHandling.Ignore,

    // Reference handling
    ReferenceLoopHandling = ReferenceLoopHandling.Serialize,
    PreserveReferencesHandling = PreserveReferencesHandling.Objects,

    // Constructor behavior
    ConstructorHandling = ConstructorHandling.Default,

    // Type name handling
    TypeNameHandling = TypeNameHandling.All,
    TypeNameAssemblyFormatHandling = TypeNameAssemblyFormatHandling.Simple,

    // Date/Time handling
    DateFormatHandling = DateFormatHandling.IsoDateFormat,
    DateParseHandling = DateParseHandling.DateTime,
    DateTimeZoneHandling = DateTimeZoneHandling.RoundtripKind,

    // String escaping
    StringEscapeHandling = StringEscapeHandling.Default,

    // Float handling
    FloatFormatHandling = FloatFormatHandling.String,
    FloatParseHandling = FloatParseHandling.Double
};

Property Naming Strategies

var settings = new JsonSerializerSettings
{
    ContractResolver = new DefaultContractResolver
    {
        NamingStrategy = new CamelCaseNamingStrategy()
        // Other options: SnakeCaseNamingStrategy, KebabCaseNamingStrategy
    }
};

// Input class: FirstName, LastName
// Output JSON: firstName, lastName

Data Protection & Encryption

using EonaCat.Json.Protection;

// Encrypt sensitive data
var protectionOptions = new ProtectionOptions
{
    ProtectionType = ProtectionType.Aes,
    Key = "your-secret-key-here"
};

var dataProtection = new DataProtection(protectionOptions);
string encrypted = dataProtection.Protect(sensitiveData);
string decrypted = dataProtection.Unprotect(encrypted);

Custom Type Handling

public class CustomContractResolver : DefaultContractResolver
{
    protected override JsonProperty CreateProperty(
        MemberInfo member, MemberSerialization memberSerialization)
    {
        JsonProperty property = base.CreateProperty(member, memberSerialization);

        // Custom logic
        if (member.Name.StartsWith("_"))
        {
            property.Ignored = true;
        }

        return property;
    }
}

Streaming Large JSON

// For memory efficiency with large files
using (JsonReader reader = new JsonTextReader(new StreamReader("large.json")))
{
    reader.SupportMultipleContent = true;

    while (reader.Read())
    {
        // Process tokens one by one
        if (reader.TokenType == JsonToken.StartObject)
        {
            JObject obj = JObject.Load(reader);
            // Process object
        }
    }
}

Configuration

JsonSerializerSettings

The JsonSerializerSettings class provides a comprehensive configuration object:

var settings = new JsonSerializerSettings
{
    Formatting = Formatting.Indented,
    NullValueHandling = NullValueHandling.Ignore,
    DateFormatHandling = DateFormatHandling.IsoDateFormat,
    ReferenceLoopHandling = ReferenceLoopHandling.Serialize,
    Converters = new JsonConverter[] { new StringEnumConverter() },
    ContractResolver = new CamelCasePropertyNamesContractResolver(),
    TraceWriter = new MemoryTraceWriter(),
    DateFormatString = "yyyy-MM-dd",
};

string json = JsonHelper.ToJson(myObject, settings);

Default Settings

// Set global default settings
JsonHelper.DefaultSettings = () => new JsonSerializerSettings
{
    NullValueHandling = NullValueHandling.Ignore,
    DateFormatHandling = DateFormatHandling.IsoDateFormat
};

// All subsequent calls use these defaults
string json1 = JsonHelper.ToJson(obj1); // Uses defaults
string json2 = JsonHelper.ToJson(obj2); // Uses defaults

JsonLoadSettings

Configure loading behavior:

var loadSettings = new JsonLoadSettings
{
    DuplicatePropertyNameHandling = DuplicatePropertyNameHandling.Replace,
    CommentHandling = CommentHandling.Ignore,
    LineInfoHandling = LineInfoHandling.Load
};

JObject obj = JObject.Load(reader, loadSettings);

API Reference

Main Namespaces

• EonaCat.Json - Core serialization (JsonHelper, JsonSerializer, JsonSerializerSettings)
• EonaCat.Json.Linq - LINQ to JSON (JObject, JArray, JToken, JProperty)
• EonaCat.Json.Converters - Custom converters (StringEnumConverter, IsoDateTimeConverter, etc.)
• EonaCat.Json.Schema - JSON Schema validation and generation
• EonaCat.Json.Bson - BSON serialization (BsonReader, BsonWriter, BsonObject)
• EonaCat.Json.Fast - High-performance JSON (FastJson.Json static class)
• EonaCat.Json.Extensions - Extension methods (JsonExtensions)
• EonaCat.Json.Protection - Data encryption (DataProtection, ProtectionOptions)

Examples

Complex Object Serialization

public class Order
{
    [JsonProperty("order_id")]
    public int Id { get; set; }

    [JsonProperty(Required = Required.Always)]
    public string Customer { get; set; }

    [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
    public string? Notes { get; set; }

    [JsonConverter(typeof(IsoDateTimeConverter))]
    public DateTime OrderDate { get; set; }

    public List<OrderItem> Items { get; set; }
}

public class OrderItem
{
    [JsonProperty("item_id")]
    public int Id { get; set; }

    public string Product { get; set; }

    public decimal Price { get; set; }

    public int Quantity { get; set; }
}

// Usage
var order = new Order
{
    Id = 123,
    Customer = "Acme Corp",
    OrderDate = DateTime.Now,
    Items = new List<OrderItem>
    {
        new OrderItem { Id = 1, Product = "Widget", Price = 9.99m, Quantity = 2 }
    }
};

string json = JsonHelper.ToJson(order, Formatting.Indented);
Order restored = JsonHelper.ToObject<Order>(json);

Dynamic JSON Processing

string apiResponse = @"
{
    ""status"": ""success"",
    ""data"": {
        ""users"": [
            { ""id"": 1, ""name"": ""Alice"" },
            { ""id"": 2, ""name"": ""Bob"" }
        ]
    }
}";

dynamic response = JsonHelper.ToObject<dynamic>(apiResponse);
Console.WriteLine(response.status);           // success
Console.WriteLine(response.data.users[0].name); // Alice

Schema Validation

string schema = @"
{
    ""type"": ""object"",
    ""properties"": {
        ""name"": { ""type"": ""string"" },
        ""email"": { ""type"": ""string"", ""format"": ""email"" },
        ""age"": { ""type"": ""integer"", ""minimum"": 0 }
    },
    ""required"": [""name"", ""email""]
}";

string data = @"{ ""name"": ""John"", ""email"": ""john@example.com"", ""age"": 30 }";

JSchema jsonSchema = JSchema.Parse(schema);
JObject jsonData = JObject.Parse(data);

IList<string> validationErrors;
bool isValid = jsonData.IsValid(jsonSchema, out validationErrors);

if (!isValid)
{
    foreach (var error in validationErrors)
        Console.WriteLine(error);
}