FractalDataWorks.Configuration.Abstractions 0.1.0-preview.15

FractalDataWorks.Configuration.Abstractions

Abstractions for configuration options loading patterns and configuration metadata.

Overview

This package provides interfaces and base classes for:

• Unified access to Microsoft.Extensions.Options interfaces (IOptions, IOptionsSnapshot, IOptionsMonitor)
• TypeCollection pattern for options loader type discovery
• Attributes for UI-driven configuration metadata

Key Types

Options Loading

From IConfigurationOptionsLoader.cs:33-70:

public interface IConfigurationOptionsLoader<out TOptions>
    where TOptions : class
{
    /// <summary>
    /// Gets the current configuration value.
    /// </summary>
    TOptions CurrentValue { get; }

    /// <summary>
    /// Gets a value indicating whether this loader supports change notifications.
    /// </summary>
    bool SupportsChangeNotification { get; }

    /// <summary>
    /// Registers a listener to be called when the configuration changes.
    /// </summary>
    IDisposable? OnChange(Action<TOptions, string?> listener);
}

From IOptionsLoader.cs:24-63:

public interface IOptionsLoader : ITypeOption<int, OptionsLoaderBase>
{
    string OptionsInterfaceName { get; }
    bool SupportsHotReload { get; }
    string CurrentValueAccessor { get; }
    bool RequiresDisposable { get; }
    IConfigurationOptionsLoader<TOptions> CreateLoader<TOptions>(IServiceProvider serviceProvider)
        where TOptions : class;
}

From OptionsLoaderBase.cs:19-78:

public abstract class OptionsLoaderBase : TypeOptionBase<int, OptionsLoaderBase>, IOptionsLoader
{
    public abstract string OptionsInterfaceName { get; }
    public abstract bool SupportsHotReload { get; }
    public abstract string CurrentValueAccessor { get; }
    public abstract bool RequiresDisposable { get; }

    public virtual IConfigurationOptionsLoader<TOptions> CreateLoader<TOptions>(IServiceProvider serviceProvider)
        where TOptions : class
    {
        throw new InvalidOperationException(
            $"Cannot create loader from Empty options loader type. Use a concrete implementation: Singleton, Scoped, or Reloadable.");
    }

    protected OptionsLoaderBase(int id, string name) : base(id, name)
    {
    }
}

Configuration Attributes

From Attributes/ConfigurationPropertyAttribute.cs:40-118:

[AttributeUsage(AttributeTargets.Property, AllowMultiple = false, Inherited = true)]
public sealed class ConfigurationPropertyAttribute : Attribute
{
    public string? Label { get; set; }
    public string? HelpText { get; set; }
    public string? Placeholder { get; set; }
    public int Order { get; set; } = int.MaxValue;
    public bool IsHidden { get; set; }
    public bool IsReadOnly { get; set; }
    public int MaxLength { get; set; } = 255;
    public string? ColumnName { get; set; }
    public string Section { get; set; } = "General";
    public int Width { get; set; } = 6;
}

From Attributes/ConfigurationSectionAttribute.cs:37-92:

[AttributeUsage(AttributeTargets.Class, AllowMultiple = true, Inherited = true)]
public sealed class ConfigurationSectionAttribute : Attribute
{
    public ConfigurationSectionAttribute(string name)
    {
        Name = name ?? throw new ArgumentNullException(nameof(name));
    }

    public string Name { get; }
    public string? Title { get; set; }
    public string? Description { get; set; }
    public int Order { get; set; } = int.MaxValue;
    public bool IsCollapsible { get; set; }
    public bool IsExpanded { get; set; } = true;
}

Usage

Options loaders are accessed via the OptionsLoaderTypes TypeCollection in the FractalDataWorks.Configuration package.

From OptionsLoaderIntegrationTests.cs:17-26:

// Arrange & Act
var loader = OptionsLoaderTypes.Singleton;

// Assert
loader.OptionsInterfaceName.ShouldBe("IOptions");
loader.CurrentValueAccessor.ShouldBe(".Value");
loader.RequiresDisposable.ShouldBeFalse();

From OptionsLoaderIntegrationTests.cs:40-50:

// Arrange & Act
var loader = OptionsLoaderTypes.Reloadable;

// Assert
loader.OptionsInterfaceName.ShouldBe("IOptionsMonitor");
loader.CurrentValueAccessor.ShouldBe(".CurrentValue");
loader.RequiresDisposable.ShouldBeTrue();

Loader Types

Installation

<PackageReference Include="FractalDataWorks.Configuration.Abstractions" />

Dependencies

• FractalDataWorks.Collections - TypeCollection base classes

Best Practices

1. Use Singleton loader for static configuration that never changes at runtime
2. Use Scoped loader for multi-tenant scenarios where configuration varies per request
3. Use Reloadable loader for database-backed configuration that supports hot reload
4. Implement IDisposable when using Reloadable loader to clean up change notification subscriptions
5. Use ConfigurationPropertyAttribute to customize UI rendering of configuration properties
6. Group related properties using ConfigurationSectionAttribute on the configuration class

Related Packages

• FractalDataWorks.Configuration - Concrete implementations (OptionsLoaderTypes, ConfigurationBase)
• FractalDataWorks.Collections - TypeCollection framework