jjm.one.ExceptionFormatter 0.0.1-alpha.2

jjm.one.ExceptionFormatter

A lightweight .NET library to simplify and standardize exception creation with templated messages and structured data.

Table of Contents

• jjm.one.ExceptionFormatter
  • Table of Contents
  • Overview
  • Features
  • Installation
  • Usage
  • API Reference
  • Examples
    • Basic Formatting
    • Unknown Placeholder Preservation
    • Unused Args Still Added
    • Formatting Without Data Attachment
  • License

Overview

jjm.one.ExceptionFormatter is a lightweight .NET library that lets you:

• Define exception messages with named placeholders (e.g. "User {UserId} failed on {Operation}").
• Provide an array of (string Key, object? Value) pairs to fill in every {Key}—leaving unknown placeholders intact.
• Instantiate any exception type TException via its best‐matching public constructor, preserving inner exceptions when supported.
• Populate the exception’s Data dictionary with all provided args, even those not present in the template.
• New: format messages and create exceptions without populating Data, using the Format<T> method.
• Handle null or empty templates/args gracefully and survive internal formatting or construction errors without blowing up.

Features

• Single‑pass, span‑based templating via ValueStringBuilder ‒ O(n) time, minimal allocations.
• Delegate‑cached constructors ‒ reflection only on first use, then direct invocation.
• Unknown placeholders preserved ‒ {Missing} remains literal.
• All provided args end up in Exception.Data, even unused ones (when using FormatWithData).
• Optional no‑data mode: call Format<T> to skip Data population entirely.
• Graceful fallbacks on formatting or constructor failures.
• Null‑tolerant: template or args may be null.
• No external dependencies beyond the .NET BCL.

Installation

Install the package from NuGet:

dotnet add package jjm.one.ExceptionFormatter --version <VERSION>

Usage

using jjm.one.ExceptionFormatter;

// --- With Data attachment ---
throw ExceptionFormatter.FormatWithData<InvalidOperationException>(
    "User {UserId} failed on {Operation}",
    new[] { ("UserId", 123), ("Operation", "CreateOrder") }
);

// --- Without Data attachment ---
throw ExceptionFormatter.Format<InvalidOperationException>(
    "User {UserId} failed on {Operation}",
    new[] { ("UserId", 123), ("Operation", "CreateOrder") }
);

Preserving an inner exception:

try
{
    // some code that throws…
}
catch (Exception ex)
{
    // with Data
    throw ExceptionFormatter.FormatWithData<ConfigurationException>(
        "Failed to load config from {Path}",
        new[] { ("Path", configPath) },
        innerException: ex
    );
    
    // or without Data
    // throw ExceptionFormatter.Format<ConfigurationException>(
    //     "Failed to load config from {Path}",
    //     new[] { ("Path", configPath) },
    //     innerException: ex
    // );
}

API Reference

namespace jjm.one.ExceptionFormatter
{
    public static class ExceptionFormatter
    {
        /// <summary>
        /// Formats a message template, creates a TException, and populates its Data dictionary.
        /// </summary>
        public static TException FormatWithData<TException>(
            string? template,
            (string Key, object? Value)[]? args = null,
            Exception? innerException = null
        ) where TException : Exception;

        /// <summary>
        /// Formats a message template, creates a TException, but does NOT populate its Data dictionary.
        /// </summary>
        public static TException Format<TException>(
            string? template,
            (string Key, object? Value)[]? args = null,
            Exception? innerException = null
        ) where TException : Exception;
    }
}

Examples

Basic Formatting

var ex = ExceptionFormatter.FormatWithData<Exception>(
    "Coordinates: {X}, {Y}",
    new[] { ("X", 42), ("Y", -7) }
);
// ex.Message == "Coordinates: 42, -7"
// ex.Data["X"] == 42, ex.Data["Y"] == -7

Unknown Placeholder Preservation

var ex = ExceptionFormatter.FormatWithData<Exception>(
    "Missing: {A}, {B}",
    new[] { ("A", "apple") }
);
// ex.Message == "Missing: apple, {B}"
// ex.Data contains "A" but not "B"

Unused Args Still Added

var ex = ExceptionFormatter.FormatWithData<Exception>(
    "No placeholders here",
    new[] { ("Foo", 100) }
);
// ex.Message == "No placeholders here"
// ex.Data["Foo"] == 100

Formatting Without Data Attachment

var ex1 = ExceptionFormatter.Format<Exception>(
    "User {Id} not found",
    new[] { ("Id", 999) }
);
// ex1.Message == "User 999 not found"
// ex1.Data.Count == 0

var ex2 = ExceptionFormatter.Format<ArgumentException>(
    "Bad argument {Name}",
    new[] { ("Name", "param") },
    new InvalidOperationException("cause")
);
// ex2 is ArgumentException with InnerException == "cause"
// ex2.Data.Count == 0

License

The jjm.one.ExceptionFormatter library is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License v3.0 (LGPL‑3.0) as published by the Free Software Foundation.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the LICENSE or https://www.gnu.org/licenses/lgpl-3.0.html for more details.

© 2025 jjm.one. Licensed under the GNU Lesser General Public License v3.0.