Cuemon.Extensions.Core

Overview

Cuemon.Extensions.Core extends Cuemon.Core with fluent APIs for configuring options objects, converting values, wrapping instances with extra data, and turning ordinary object graphs into searchable hierarchies. It is the package where the base Cuemon abstractions gain day-to-day extension methods over System types and common collection workflows.

The package also adds a small runtime model around IWrapper<T>, IHierarchy<T>, and HierarchySerializer, alongside factory helpers such as MutableTupleFactory and ActionFactory for carrying strongly typed argument lists. That mix makes it useful when a codebase wants Cuemon-style configuration, traversal, and lightweight metadata without introducing a heavier framework.

Key APIs

ActionExtensions.Configure<TOptions>() turns an Action<TOptions> into a fully initialized options object, with the same IParameterObject and parameterless-constructor constraints enforced by the source. CreateInstance<T>() sits beside it for default-constructable classes that need a short initialization path without a separate builder.

ObjectExtensions.UseWrapper<T>() wraps an existing instance in IWrapper<T> and optionally attaches arbitrary metadata through the wrapper Data dictionary. The overload that accepts MemberInfo also records where a wrapped value came from, which matters when wrappers participate in hierarchy traversal.

ObjectExtensions.As<T>() and As(this object, Type, ...) centralize conversion through Cuemon's formatting pipeline instead of scattered Convert.ChangeType calls. The overloads support enums, generics, format-provider configuration, and explicit fallback values when a caller wants a default instead of a thrown conversion failure.

MutableTupleFactory produces MutableTuple instances from zero to twenty arguments. Those tuples are used directly in the package's delegate factories and provide a strongly typed alternative to passing raw object[] argument bags around.

AsyncDisposable is the package's async extension point for disposal. Consumers override OnDisposeManagedResourcesAsync() and let DisposeAsync() run the asynchronous cleanup before finishing the normal disposal flow and suppressing finalization.

Hierarchy.GetObjectHierarchy() walks a source object through its readable properties and projects the result into IHierarchy<object> nodes. HierarchyOptions controls depth limits, property filtering, circular-reference handling, reflection rules, and value resolution during that traversal.

HierarchyDecoratorExtensions.DescendantsAndSelf<T>() is the core traversal helper once a hierarchy exists. The same type also exposes AncestorsAndSelf<T>(), SiblingsAndSelfAt<T>(), Find<T>(), NodeAt<T>(), FlattenAll<T>(), and formatter helpers that turn DataPair hierarchies back into concrete values.

HierarchySerializer packages hierarchy generation behind a small object with a Nodes property and a readable ToString() output. It is the quickest way to inspect how Cuemon sees an object graph before you start searching or rewriting nodes.

Basic usage

Use this pattern when you need to turn a nested settings object into something you can both query and log without hand-writing reflection or duplicate tree walkers. It matters because the package lets the same hierarchy model drive targeted assertions and a readable serialized view of the object graph.

using System.Linq;
using Codebelt.Extensions.Xunit;
using Cuemon.Extensions.Runtime;
using Cuemon.Extensions.Runtime.Serialization;
using Xunit;

namespace MyProject.Tests;

public class DeploymentPlanHierarchyTest : Test
{
    public DeploymentPlanHierarchyTest(ITestOutputHelper output) : base(output) { }

    [Fact]
    public void ShouldLocateNestedRetrySettings_WhenInspectingObjectHierarchy()
    {
        var plan = new DeploymentPlan("sync-workers", new RetrySettings(3, 15));
        var hierarchy = Hierarchy.GetObjectHierarchy(plan);
        var retryNode = Hierarchy.Find(hierarchy, node => node.InstanceType == typeof(RetrySettings)).Single();
        var text = new HierarchySerializer(plan).ToString().TrimEnd();

        TestOutput.WriteLine(text);

        Assert.Equal(1, retryNode.Depth);
        Assert.Equal(3, Assert.IsType<RetrySettings>(retryNode.Instance).Count);
        Assert.Contains("DeploymentPlan.RetrySettings", text);
    }

    private sealed record DeploymentPlan(string Name, RetrySettings Retry);
    private sealed record RetrySettings(int Count, int DelaySeconds);
}

Installation

dotnet add package Cuemon.Extensions.Core

Usage guidance

Adopt Cuemon.Extensions.Core when you want Cuemon.Core abstractions to feel natural in application code through extension methods, wrappers, typed delegate argument containers, and object-graph traversal helpers. If you only need isolated BCL conversions or a narrow feature such as text, IO, or threading helpers, a plain framework API or a smaller sibling package is usually the better fit.