Sudzekai.AspNetCore.Toolkit.Core.Abstractions 1.0.0

sudzekai's Toolkit for ASP.NET — Core Abstractions

The Core Abstractions package provides the fundamental contracts and base types used by Sudzekai.AspNetCore.Toolkit.

It defines the abstractions required to represent Toolkit modules, manage their state, and integrate them into the ASP.NET Core application lifecycle.

The package contains no concrete application functionality. It provides only the APIs required by the Toolkit and its modules.

Overview

The Core Abstractions include:

• IToolkitModule — the base contract for Toolkit modules;
• ToolkitModule — the base implementation of IToolkitModule;
• IToolkitPreBuilderModule — abstraction for pre-builder lifecycle operations;
• IToolkitHostBuilderModule — abstraction for host-builder lifecycle operations;
• IToolkitHostModule — abstraction for post-build lifecycle operations.

These abstractions allow modules to remain independent of the Toolkit's concrete implementation while using standard ASP.NET Core infrastructure.

Abstractions

IToolkitModule

IToolkitModule is the base abstraction for all Toolkit modules.

public interface IToolkitModule
{
    string Name { get; }

    bool IsConfigured { get; }

    bool IsEnabled { get; }

    void Configure(IConfiguration configuration);

    void Disable();

    void Enable();
}

Name

Gets the name of the module.

The property can be used by the Toolkit and module implementations to identify a module.

IsConfigured

Gets a value indicating whether the module has been configured.

A module must be configured before it can be enabled.

IsEnabled

Gets a value indicating whether the module is currently enabled.

The Toolkit uses this state to determine whether the module should be applied.

Configure(IConfiguration configuration)

Configures the module using the application's IConfiguration.

The configuration implementation is responsible for reading and validating its own configuration.

module.Configure(configuration);

Enable()

Enables the module.

Implementations must ensure that a module cannot be enabled before it has been configured.

module.Configure(configuration);
module.Enable();

Disable()

Disables the module.

module.Disable();

Disabling a module does not remove it from the Toolkit. It only changes its enabled state.

ToolkitModule

ToolkitModule provides a base implementation of IToolkitModule.

public abstract class ToolkitModule : IToolkitModule
{
    public string Name => GetType().Name;

    public bool IsConfigured { get; private set; }

    public bool IsEnabled { get; private set; }

    public abstract void Configure(IConfiguration configuration);

    public virtual void Disable()
    {
        IsEnabled = false;
    }

    public virtual void Enable()
    {
        if (!IsConfigured)
            throw new InvalidOperationException(
                $"Module '{Name}' couldn't be enabled because it is not configured.");

        IsEnabled = true;
    }

    protected void SetConfigured()
        => IsConfigured = true;
}

The base class provides the common module state management so implementations only need to provide their configuration logic and, when required, lifecycle behavior.

Name

The default implementation derives the module name from its runtime type:

public string Name => GetType().Name;

For example:

public sealed class DatabaseModule : ToolkitModule
{
    // ...
}

will have:

Name = "DatabaseModule"

SetConfigured()

SetConfigured() marks the module as configured.

It is protected so that only derived module implementations can change the configuration state.

public override void Configure(IConfiguration configuration)
{
    // Configure the module.

    SetConfigured();
}

Enable State

ToolkitModule prevents a module from being enabled before configuration:

module.Enable();

results in an InvalidOperationException when IsConfigured is false.

Lifecycle Abstractions

The Core Abstractions define three optional lifecycle contracts.

A module can implement one or multiple lifecycle interfaces depending on when it needs to execute.

IToolkitModule
     │
     ├── IToolkitPreBuilderModule
     │
     ├── IToolkitHostBuilderModule
     │
     └── IToolkitHostModule

IToolkitPreBuilderModule

public interface IToolkitPreBuilderModule : IToolkitModule
{
    void Apply();
}

Defines a lifecycle operation that does not require an IHostApplicationBuilder.

The Toolkit invokes Apply() during the pre-builder stage.

public sealed class ExampleModule :
    ToolkitModule,
    IToolkitPreBuilderModule
{
    public override void Configure(IConfiguration configuration)
    {
        SetConfigured();
    }

    public void Apply()
    {
        // Pre-builder logic.
    }
}

IToolkitHostBuilderModule

public interface IToolkitHostBuilderModule : IToolkitModule
{
    void Apply(IHostApplicationBuilder builder);
}

Defines a lifecycle operation that receives the ASP.NET Core IHostApplicationBuilder.

This allows implementations to work with standard host-builder infrastructure such as:

• dependency injection;
• logging;
• configuration;
• host configuration;
• application services.

Example:

public sealed class ExampleModule :
    ToolkitModule,
    IToolkitHostBuilderModule
{
    public override void Configure(IConfiguration configuration)
    {
        SetConfigured();
    }

    public void Apply(IHostApplicationBuilder builder)
    {
        builder.Services.AddSingleton<ExampleService>();
    }
}

IToolkitHostModule

public interface IToolkitHostModule : IToolkitModule
{
    void Apply(IServiceProvider provider);
}

Defines a lifecycle operation that is executed after the application has been built.

The module receives the application's IServiceProvider.

Example:

public sealed class ExampleModule :
    ToolkitModule,
    IToolkitHostModule
{
    public override void Configure(IConfiguration configuration)
    {
        SetConfigured();
    }

    public void Apply(IServiceProvider provider)
    {
        var service = provider.GetRequiredService<ExampleService>();

        service.Initialize();
    }
}

This abstraction is intended for operations that require services from the already-built application's dependency injection container.

Multiple Lifecycle Abstractions

A single implementation can implement multiple lifecycle interfaces.

public sealed class ExampleModule :
    ToolkitModule,
    IToolkitPreBuilderModule,
    IToolkitHostBuilderModule,
    IToolkitHostModule
{
    public override void Configure(IConfiguration configuration)
    {
        SetConfigured();
    }

    public void Apply()
    {
        // Pre-builder stage.
    }

    public void Apply(IHostApplicationBuilder builder)
    {
        // Host-builder stage.
    }

    public void Apply(IServiceProvider provider)
    {
        // Post-build stage.
    }
}

All lifecycle interfaces inherit from IToolkitModule, allowing the same module abstraction and state to be used across different application lifecycle stages.

State Model

The Core Abstractions distinguish between configuration and activation.

                 Configure()
                      │
                      ▼
              ┌───────────────┐
              │ IsConfigured  │
              │    = true     │
              └───────┬───────┘
                      │
                   Enable()
                      │
                      ▼
              ┌───────────────┐
              │   IsEnabled   │
              │     = true    │
              └───────────────┘

The states are independent:

An unconfigured module cannot be enabled through the default ToolkitModule implementation.

ASP.NET Core Integration

The abstractions intentionally use standard ASP.NET Core types rather than defining Toolkit-specific equivalents.

The main integration points are:

IConfiguration
      │
      ▼
IToolkitModule.Configure()
      
IHostApplicationBuilder
      │
      ▼
IToolkitHostBuilderModule.Apply()

IServiceProvider
      │
      ▼
IToolkitHostModule.Apply()

This allows implementations to directly use the existing ASP.NET Core hosting, configuration, and dependency injection infrastructure.

The Core Abstractions do not introduce a custom dependency injection container or replace the ASP.NET Core hosting model.

Package Scope

The Core Abstractions package is intentionally limited to contracts and base implementations.

It does not provide:

• concrete logging implementations;
• database integrations;
• authentication implementations;
• application-specific services;
• host orchestration;
• module discovery or registration logic.

Those responsibilities belong to the Toolkit itself or to separate Toolkit modules.

The Core Abstractions package exists so that these components can share a stable set of contracts without depending on each other's implementations.

Architecture

The relationship between the core types can be represented as:

                    IToolkitModule
                           │
                           │
                    ToolkitModule
                           │
             ┌─────────────┼─────────────┐
             │             │             │
             ▼             ▼             ▼
 IToolkitPreBuilder  IToolkitHostBuilder  IToolkitHost
      Module             Module              Module

A concrete implementation normally derives from ToolkitModule and implements the lifecycle abstraction it requires.

Concrete Module
      │
      ├── ToolkitModule
      │
      ├── IToolkitPreBuilderModule       (optional)
      ├── IToolkitHostBuilderModule      (optional)
      └── IToolkitHostModule             (optional)

This keeps the core API small while allowing modules to participate in exactly the lifecycle stages they require.