Oakrey.Applications.Json 3.0.4

Oakrey.Applications.Json

A .NET 10 class library that provides stream-based JSON serialization and deserialization through a single injectable service interface. It uses System.Text.Json internally, delegates all file I/O to IFileService, and instruments every operation with OpenTelemetry tracing and structured logging.

Main features

• Deserialize a JSON file to a typed object, synchronously or asynchronously with CancellationToken support
• Serialize a typed object to a JSON file, synchronously or asynchronously
• Batch-load all JSON files from a directory into a List<T> asynchronously
• Batch-save a collection of IName objects to individual files named after each object
• Stream-based I/O � no intermediate string allocation during serialization or deserialization
• All key methods are virtual on JsonService, allowing subclass overrides
• Every operation emits an OpenTelemetry activity span and structured log entries

Architecture

classDiagram
    class IJsonService {
        +LoadJson~T~(fileName) T
        +LoadJsonAsync~T~(fileName, ct) Task~T~
        +LoadObjectsFromJsonFilesAsync~T~(folder, extension, ct) Task~List~T~~
        +SaveJson~T~(value, fileName)
        +SaveJsonAsync~T~(value, fileName)
        +SaveJsonFiles~T~(jsons, folder, extension)
    }

    class JsonService {
        #IFileService fileService
        #ILogger logger
        #ITracing tracer
        +JsonService()
        +JsonService(IFileService)
    }

    class IFileService {
        +LoadFileStream(fileName) FileStream
        +CreateSaveStream(fileName) FileStream
        +GetFilesPaths(folder, extension) string[]
    }

    IJsonService <|.. JsonService
    JsonService --> IFileService

Requirements

• .NET 10 or higher
• Oakrey.Applications.Files (transitively provides IFileService)
• Oakrey.Collections 2.0.0 or higher (provides IName used by SaveJsonFiles)

Installation

NuGet Package Manager

1. In Visual Studio open Tools > NuGet Package Manager > Manage NuGet Packages for Solution.
2. Search for Oakrey.Applications.Json and click Install.

.NET CLI

dotnet add package Oakrey.Applications.Json

Package Manager Console

Install-Package Oakrey.Applications.Json

Configuration

JsonService can be constructed with or without a custom IFileService. Register with the DI container of your choice:

// Uses the default FileService internally
services.AddSingleton<IJsonService, JsonService>();

// Bring your own IFileService
services.AddSingleton<IFileService, FileService>();
services.AddSingleton<IJsonService, JsonService>();

Oakrey.Log and Oakrey.Telemetry must be configured separately before JsonService is resolved.

Example usage

public class ConfigRepository(IJsonService jsonService)
{
    private const string ConfigFolder = "config";
    private const string Extension = "json";

    // Load a single config file
    public AppConfig Load(string fileName)
    {
        return jsonService.LoadJson<AppConfig>(fileName);
    }

    // Load a single config file asynchronously
    public async Task<AppConfig> LoadAsync(string fileName, CancellationToken ct)
    {
        return await jsonService.LoadJsonAsync<AppConfig>(fileName, ct);
    }

    // Load all config files from a directory
    public async Task<List<AppConfig>> LoadAllAsync(CancellationToken ct)
    {
        return await jsonService.LoadObjectsFromJsonFilesAsync<AppConfig>(ConfigFolder, Extension, ct);
    }

    // Save a single config
    public void Save(AppConfig config, string fileName)
    {
        jsonService.SaveJson(config, fileName);
    }

    // Batch-save named configs � each file is named after config.Name
    public void SaveAll(IEnumerable<AppConfig> configs)
    {
        jsonService.SaveJsonFiles(configs, ConfigFolder, Extension);
    }
}

AppConfig must implement Oakrey.Collections.IName (exposes a Name property) to be usable with SaveJsonFiles.

Development notes

• LoadJson, LoadJsonAsync, and SaveJson are declared virtual on JsonService, making the class suitable as a base for domain-specific JSON services that need to apply custom JsonSerializerOptions or pre/post-processing.
• SaveJsonFiles calls SaveJsonAsync internally, which is async void. Exceptions thrown inside async void propagate to the synchronization context and cannot be awaited. Prefer SaveJson or a custom override when reliable error propagation is required.
• LoadObjectsFromJsonFilesAsync enumerates files sequentially rather than in parallel to keep memory pressure predictable for large directories.
• Serialization and deserialization operate directly on FileStream instances obtained from IFileService, avoiding intermediate string or byte-array buffers.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Author: Oakrey
Repository: https://dev.azure.com/oakrey/OpenPackages/_git/ApplicationServices
Project URL: http://www.oakrey.cz/opkg_applications