Oakrey.Applications.Json.Abstractions 3.0.4

Oakrey.Applications.Json.Abstractions

A .NET 10 library that defines the IJsonService abstraction for JSON serialization and deserialization operations. It contains no implementation code, no logging, and no telemetry dependencies, making it the correct reference for libraries and application layers that need JSON access without coupling to a concrete implementation.

Main features

SaveJsonFiles requires TNamed to implement IName from Oakrey.Collections, which provides a Name property used as the file name.

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~TNamed~(jsons, folder, extension)
    }

    class JsonService {
        <<Oakrey.Applications.Json>>
    }

    class IFileService {
        <<Oakrey.Applications.Files.Abstractions>>
    }

    IJsonService <|.. JsonService
    JsonService --> IFileService

The concrete implementation lives in the separate Oakrey.Applications.Json package. Consuming projects should reference only this abstractions package and register the implementation via the extension provided by Oakrey.Applications.Json.

Requirements

• .NET 10 or later
• Oakrey.Collections � provides the IName interface required by SaveJsonFiles

Installation

dotnet add package Oakrey.Applications.Json.Abstractions

To also include the concrete implementation:

dotnet add package Oakrey.Applications.Json

Example usage

Registering the service

// In your composition root, reference Oakrey.Applications.Json for the extension method.
services.AddJsonService();

Deserializing a single file

public sealed class ConfigLoader
{
    private readonly IJsonService _jsonService;

    public ConfigLoader(IJsonService jsonService)
    {
        _jsonService = jsonService;
    }

    public async Task<AppConfig> LoadAsync(string path, CancellationToken cancellationToken)
    {
        return await _jsonService.LoadJsonAsync<AppConfig>(path, cancellationToken);
    }
}

Loading all files from a directory

List<Profile> profiles = await _jsonService.LoadObjectsFromJsonFilesAsync<Profile>(
    folder: @"C:\Data\Profiles",
    extension: "json",
    cancellationToken: cancellationToken);

Saving a batch of named objects

// Profile implements IName, so each item is saved as "{profile.Name}.json".
_jsonService.SaveJsonFiles(profiles, folder: @"C:\Data\Profiles", extension: "json");

Development notes

• This package contains only the IJsonService interface. No serializer, logger, or tracer code is included.
• The concrete implementation (JsonService) is in Oakrey.Applications.Json. It uses System.Text.Json with stream-based I/O via IFileService, structured logging via Oakrey.Log, and OpenTelemetry activity spans via Oakrey.Telemetry.
• Both packages share the Oakrey.Applications.Json root namespace.
• The Oakrey.Collections dependency is required here because IName appears in the SaveJsonFiles contract on the interface itself.

License

MIT � Copyright � Oakrey 2016-present