Sparcpoint.Extensions.Json 1.0.2

Sparcpoint.Extensions.Json

A Fluent API for customizing JSON serialization in .NET using System.Text.Json.

This library provides a fluent, code-based alternative to using attributes (like [JsonPropertyName], [JsonIgnore], etc.). It allows you to configure how types are serialized externally—without modifying the source code of those types.

Ideal for:

• Sharing the same model across multiple serialization contexts.
• Avoiding attribute clutter.
• Dynamically applying serialization rules at runtime.

📦 Installation

Install via NuGet:

dotnet add package Sparcpoint.Extensions.Json

🚀 Getting Started

You configure serialization rules using the fluent JsonEntityBuilder<T> API. These configurations can be applied to JsonSerializerOptions directly.

using System.Text.Json;

var options = new JsonSerializerOptions()
    .Configure<Person>(entity => entity
        .Property(p => p.FirstName).Name("first_name")
        .Property(p => p.LastName).Ignore()
        .Property(p => p.Age).Required()
    );

var json = JsonSerializer.Serialize(new Person
{
    FirstName = "John",
    LastName = "Doe",
    Age = 42
}, options);

Console.WriteLine(json);
// Output: {"first_name":"John","Age":42}

🧱 Fluent API Overview

JsonEntityBuilder<TEntity>

Represents configuration for a single entity type. Used internally by the .Configure<T>().

You typically won’t instantiate this directly—instead, you pass a lambda to configure it:

options.Configure<User>(entity => {
    entity.Property(u => u.Email).Ignore();
});

Property()

Selects a property on the entity to configure.

entity.Property(u => u.Email)

This returns a JsonMemberBuilder<TEntity, TProperty> for chaining member-level configuration.

Member Configuration Methods

Example:

entity.Property(u => u.Id)
      .Order(1)
      .Required()
      .Name("user_id");

⚙️ Applying Configuration to JsonSerializerOptions

The extension method is provided for integrating your configurations:

.Configure<T>()

Adds the configuration at the front of the TypeInfoResolverChain. This means it takes precedence over existing resolvers.

NOTE: It will always ensure that at least one DefaultJsonTypeInfoResolver is at the end of the chain.

options.Configure<MyModel>(builder => {
    builder.Property(m => m.Secret).Ignore();
});

Both methods support an optional parameter to control inheritance:

.Configure<MyModel>(builder => { ... }, includeInheritedTypes: true)

🧩 Example: Combining Multiple Rules

You can chain multiple configuration calls for clarity:

options
    .Configure<Order>(entity => entity
        .Property(o => o.OrderId).Name("id")
        .Property(o => o.CustomerName).Name("customer")
        .Property(o => o.InternalNotes).Ignore()
    )
    .Configure<Customer>(entity => entity
        .Property(c => c.Email).Required()
    );

🧠 Why Fluent Configuration?

This API helps you:

• Keep DTOs free of serialization attributes.
• Apply serialization behavior conditionally (e.g., per environment or feature flag).
• Centralize serialization configuration in one place.
• Modify serialization for third-party or auto-generated classes without source changes.

🧩 Notes and Constraints

• Only classes and structs can be configured (no primitives, enums, arrays, or collections).
• System types (in System.* namespaces) are excluded by default.
• Configurations are applied via IJsonTypeInfoResolver modifiers.

🧪 Example: Dynamic Behavior

if (Environment.GetEnvironmentVariable("APP_ENV") == "Production")
{
    options.Configure<User>(b =>
        b.Property(u => u.Password).Ignore()
    );
}

🧾 License

MIT License © Sparcpoint