Linger.Json 2.0.0-preview.1

Linger.Json

Migration notes for 2.0 are documented in the Linger.Json migration guide; see the Linger migration guide for other packages.

Linger.Json contains the optional JSON support that was previously part of Linger.Utils. It provides System.Text.Json converters, DataTable conversion extensions, and reusable JsonSerializerOptions factories.

Installation

dotnet add package Linger.Json

For the 2.0 package split, add a reference to Linger.Json wherever the following APIs are used: JsonDefaults, DateTimeConverter, DateTimeNullConverter, DataTableJsonConverter, DataSetConverter, JsonStringConverter, string.ToDataTable(), DataTable.ToJsonString(), or JsonElement.JsonElementToDataTable().

DataTable JSON Extensions

using Linger.Extensions;
using Linger.Extensions.Core;
using Linger.Extensions.Data;
using System.Text.Json;

DataTable? table = "[{\"Name\":\"Ada\",\"Age\":37}]".ToDataTable();
string json = table.ToJsonString();

using var document = JsonDocument.Parse(json);
DataTable inferredTable = document.RootElement.JsonElementToDataTable();

JSON Serialization Configuration

JsonDefaults provides unified JSON serialization configuration for HTTP clients and ASP.NET Core WebAPI applications.

Overview

JsonDefaults provides centralized JSON serialization options that follow the "Be conservative in what you send, be liberal in what you accept" principle:

• Response/Input Options (CreateResponseOptions): Liberal configuration for deserializing API responses
• Request/Output Options (CreateRequestOptions): Conservative configuration for serializing API requests
• WebAPI Configuration (ApplyDefaultConfiguration): Applies optimized configuration to existing options, balancing input tolerance and output optimization

Usage in ASP.NET Core WebAPI

For Controllers (MVC/WebAPI)

Add this to your Program.cs or Startup.cs:

using Linger.Json;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers()
    .AddJsonOptions(options => 
        JsonDefaults.ApplyDefaultConfiguration(options.JsonSerializerOptions));

var app = builder.Build();

For Minimal API

using Linger.Json;

var builder = WebApplication.CreateBuilder(args);

builder.Services.Configure<Microsoft.AspNetCore.Http.Json.JsonOptions>(options =>
    JsonDefaults.ApplyDefaultConfiguration(options.SerializerOptions));

var app = builder.Build();

Manual Configuration

If you need to customize further:

using Linger.Json;

builder.Services.AddControllers()
    .AddJsonOptions(options =>
    {
        JsonDefaults.ApplyDefaultConfiguration(options.JsonSerializerOptions);
        options.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower;
    });

Configure JsonSerializerOptions Directly

using Linger.Json;

var jsonOptions = new JsonSerializerOptions();
JsonDefaults.ApplyDefaultConfiguration(jsonOptions);

var responseOptions = JsonDefaults.CreateResponseOptions();
var requestOptions = JsonDefaults.CreateRequestOptions();

Features

Response Options - CreateResponseOptions() (Liberal, for receiving)

• Accepts number strings ("123" as 123)
• Handles reference cycles
• Preserves null values
• Custom date/time converters
• DataTable support
• Camel case properties (Web defaults)

Request Options - CreateRequestOptions() (Conservative, for sending)

• Standard JSON format (numbers without quotes)
• Omits null values (reduces payload size)
• Custom date/time converters
• Camel case properties (Web defaults)
• Only includes necessary converters (more lightweight)

WebAPI Configuration - ApplyDefaultConfiguration() (Balanced, for WebAPI)

• Accepts number strings (input tolerance)
• Handles reference cycles
• Omits null values (output optimization)
• Custom date/time converters
• DataTable support
• Camel case properties (Web defaults)

Benefits

1. Consistency: Same JSON behavior across HTTP clients and WebAPI
2. Maintainability: Single source of truth for JSON configuration
3. Best Practices: Follows "strict output, lenient input" principle
4. Interoperability: Handles common API variations (number strings, etc.)

Built-in Converters

The following custom converters are included in the configuration:

• DateTimeConverter: Handles DateTime serialization/deserialization
• DateTimeNullConverter: Handles nullable DateTime
• DataTableJsonConverter: Converts between DataTable and JSON

Related Types

• JsonDefaults - JSON default configuration utility class
• DateTimeConverter - DateTime serialization converter
• DateTimeNullConverter - Nullable DateTime converter
• DataTableJsonConverter - DataTable serialization converter
• StandardHttpClient - standard HTTP client implementation that uses these options