Nabs.Launchpad.Core.Serialisation 10.0.220

Nabs Launchpad Core Serialisation Library

The Nabs Launchpad Core Serialisation library provides centralized configuration and utilities for JSON and CSV serialization across the application. This library ensures consistent serialization behavior throughout your projects by providing global settings and convenient serializer wrappers.

Key Features

• Global Configuration Management: Centralized settings for JSON and CSV serialization
• Default JSON Serialization: Consistent camelCase formatting with indented output
• CSV Configuration: Pre-configured CSV parsing with sensible defaults
• Configurable Overrides: Ability to customize both JSON and CSV settings at runtime
• Type-Safe Serialization: Strongly-typed generic methods for JSON serialization/deserialization

Core Components

GlobalSettings

The central configuration class that manages global serialization settings for both JSON and CSV formats. Provides lazy initialization with sensible defaults and allows runtime configuration overrides.

DefaultJsonSerializer

A static utility class that provides convenient methods for JSON serialization and deserialization using the configured global settings.

Usage Examples

Basic JSON Serialization

// Serialize an object to JSON
var user = new User { Name = "John Doe", Email = "john@example.com" };
var json = DefaultJsonSerializer.Serialize(user);
// Output: {
//   "name": "John Doe",
//   "email": "john@example.com"
// }

// Deserialize JSON to an object
var jsonString = """
{
  "name": "Jane Doe",
  "email": "jane@example.com"
}
""";
var user = DefaultJsonSerializer.Deserialize<User>(jsonString);

Accessing Global Settings

// Access JSON serializer options
var jsonOptions = GlobalSettings.JsonSerializerOptions;
// Default: camelCase naming policy, indented formatting

// Access CSV configuration
var csvConfig = GlobalSettings.CsvConfiguration;
// Default: InvariantCulture, headers enabled, comma delimiter

Customizing JSON Settings

// Register custom JSON serializer options
var customOptions = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower,
    WriteIndented = false,
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
};
GlobalSettings.RegisterJsonSerializerOptions(customOptions);

// All subsequent serialization will use these settings
var json = DefaultJsonSerializer.Serialize(myObject);

Customizing CSV Settings

// Register custom CSV configuration
var customCsvConfig = new CsvConfiguration(CultureInfo.InvariantCulture)
{
    HasHeaderRecord = true,
    Delimiter = "|",  // Use pipe delimiter instead of comma
    TrimOptions = TrimOptions.Trim,
    IgnoreBlankLines = true,
    MissingFieldFound = null,
    HeaderValidated = null
};
GlobalSettings.RegisterCsvConfiguration(customCsvConfig);

// Use the configuration with CsvHelper
using var reader = new StreamReader("data.csv");
using var csv = new CsvReader(reader, GlobalSettings.CsvConfiguration);
var records = csv.GetRecords<MyDataType>();

API Reference

GlobalSettings

Properties

JsonSerializerOptions

public static JsonSerializerOptions JsonSerializerOptions { get; }

Gets the configured JSON serializer options. Returns default settings if none have been registered.

Default Settings:

• PropertyNamingPolicy: JsonNamingPolicy.CamelCase
• WriteIndented: true

CsvConfiguration

public static CsvConfiguration CsvConfiguration { get; }

Gets the configured CSV configuration. Returns default settings if none have been registered.

Default Settings:

• Culture: CultureInfo.InvariantCulture
• HasHeaderRecord: true
• HeaderValidated: null
• MissingFieldFound: null
• IgnoreBlankLines: true
• Delimiter: ","
• TrimOptions: TrimOptions.Trim

Methods

RegisterJsonSerializerOptions

public static void RegisterJsonSerializerOptions(JsonSerializerOptions jsonSerializerOptions)

Registers custom JSON serializer options to be used globally throughout the application.

RegisterCsvConfiguration

public static void RegisterCsvConfiguration(CsvConfiguration csvConfiguration)

Registers custom CSV configuration to be used globally throughout the application.

DefaultJsonSerializer

Methods

Serialize

public static string Serialize<T>(T value)

Serializes an object to a JSON string using the global JSON serializer options.

Parameters:

• value: The object to serialize

Returns: A JSON string representation of the object

Deserialize

public static T Deserialize<T>(string json)

Deserializes a JSON string to an object of the specified type using the global JSON serializer options.

Parameters:

• json: The JSON string to deserialize

Returns: An object of type T

Configuration Best Practices

1. Early Registration: Register custom settings at application startup before any serialization occurs
2. Consistency: Use the global settings throughout your application to ensure consistent behavior
3. Thread Safety: Note that settings are stored in static fields; register settings before multi-threaded access
4. Testing: Reset global settings between tests to avoid test interdependencies (see testing section below)

Testing

When writing unit tests that use global settings, you should reset the static configuration between tests to ensure test isolation. The library includes a base test class pattern:

public abstract class BaseSerialisationUnitTest : IAsyncLifetime
{
    public ValueTask InitializeAsync()
    {
        // Reset static members using reflection
        ResetStaticMember(typeof(GlobalSettings), "_csvConfiguration");
        ResetStaticMember(typeof(GlobalSettings), "_jsonSerializerOptions");
        return ValueTask.CompletedTask;
    }

    public ValueTask DisposeAsync()
    {
        return ValueTask.CompletedTask;
    }

    private static void ResetStaticMember(Type type, string fieldName)
    {
        var field = type.GetField(fieldName, BindingFlags.Static | BindingFlags.NonPublic);
        field?.SetValue(null, null);
    }
}

Dependencies

• System.Text.Json: For JSON serialization functionality
• CsvHelper: For CSV parsing and configuration
• Ardalis.Result: For result pattern support (project reference)

Target Framework

• .NET 10