Sudzekai.AspNetCore.Toolkit.Core 1.0.0

sudzekai's Toolkit for ASP.NET

Overview

sudzekai's Toolkit for ASP.NET is a modular toolkit for configuring ASP.NET applications.

The Toolkit provides a common module system that allows application configuration to be divided into independent modules while keeping the standard ASP.NET Core dependency injection and hosting infrastructure.

Modules can configure different parts of an ASP.NET application during different stages of application startup.

The Toolkit itself does not provide a replacement for the ASP.NET Core dependency injection container. It uses the standard IServiceCollection and ASP.NET Core hosting APIs.

Installation

Install the Toolkit package using the .NET CLI:

dotnet add package Sudzekai.AspNetCore.Toolkit.Core

Basic Usage

Create a Toolkit instance and register the required modules:

var toolkit = Toolkit.Create();

toolkit.Modules.AddModule<ExampleModule>();

Modules can then be configured and applied during application startup:

var builder = WebApplication.CreateBuilder(args);

toolkit.Modules.ConfigureAll(builder.Configuration);
toolkit.Modules.ApplyPreBuilderModules();
toolkit.Modules.ApplyHostBuilderModules(builder);

var app = builder.Build();

toolkit.Modules.ApplyHostModules(app.Services);

app.Run();

The Toolkit module lifecycle is divided into several stages to allow modules to configure the application at the appropriate point during startup.

Module Lifecycle

A Toolkit module can participate in one or more lifecycle stages:

• IToolkitPreBuilderModule — executed before the host builder is configured;
• IToolkitHostBuilderModule — executed while configuring the host builder;
• IToolkitHostModule — executed after the application has been built.

A module can implement multiple lifecycle interfaces when its configuration requires access to different stages.

For example:

public sealed class ExampleModule :
    ToolkitModule,
    IToolkitHostBuilderModule,
    IToolkitHostModule
{
    public override string Name => "Example";

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

    public void Apply(IHostApplicationBuilder builder)
    {
        // Configure services and the host builder.
    }

    public void Apply(IServiceProvider services)
    {
        // Perform post-build configuration.
    }
}

Modules

Modules are the primary extension point of the Toolkit.

A module encapsulates configuration for a specific part of the application and exposes its configuration independently from other modules.

Modules inherit from ToolkitModule:

public sealed class ExampleModule : ToolkitModule
{
    public override string Name => "Example";

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

The base ToolkitModule provides module state management, including:

• module configuration state;
• enabled/disabled state;
• module name;
• common enable/disable behavior.

Registering a Module

A module type can be registered using AddModule<TModule>():

toolkit.Modules.AddModule<ExampleModule>();

An existing module instance can also be registered:

var module = new ExampleModule();

toolkit.Modules.AddModuleInstance(module);

The Toolkit stores one instance of each registered module.

Getting a Module

A registered module can be retrieved by its type:

var module = toolkit.Modules.GetModule<ExampleModule>();

Configuration

The Toolkit supports two primary configuration approaches.

Configuration using IConfiguration

Modules can read their configuration from the application's IConfiguration:

toolkit.Modules
    .GetModule<ExampleModule>()
    .Configure(builder.Configuration);

When multiple modules are registered, all of them can be configured at once:

toolkit.Modules.ConfigureAll(builder.Configuration);

Each module is responsible for reading and validating its own configuration section.

Enabling and Disabling Modules

Modules can be enabled or disabled explicitly:

toolkit.Modules
    .GetModule<ExampleModule>()
    .Enable();

A module can be disabled using:

toolkit.Modules
    .GetModule<ExampleModule>()
    .Disable();

A module cannot be enabled before it has been configured.

Applying Modules

After modules have been registered and configured, their lifecycle methods must be applied.

Pre-Builder Modules

Pre-builder modules are applied before configuring the host builder:

toolkit.Modules.ApplyPreBuilderModules();

Host Builder Modules

Host builder modules receive the IHostApplicationBuilder instance:

toolkit.Modules.ApplyHostBuilderModules(builder);

This stage is intended for operations such as:

• configuring logging;
• registering services;
• configuring the host;
• modifying application builder settings.

Host Modules

Host modules are applied after the application has been built:

var app = builder.Build();

toolkit.Modules.ApplyHostModules(app.Services);

This stage is intended for operations that require the built application's service provider.

Complete Example

A typical ASP.NET application using the Toolkit can be structured as follows:

var builder = WebApplication.CreateBuilder(args);

var toolkit = Toolkit.Create();

toolkit.Modules.AddModule<ConsoleLoggingModule>();

toolkit.Modules.ConfigureAll(builder.Configuration);

toolkit.Modules.ApplyPreBuilderModules();
toolkit.Modules.ApplyHostBuilderModules(builder);

builder.Services.AddControllers();

var app = builder.Build();

toolkit.Modules.ApplyHostModules(app.Services);

app.MapControllers();

app.Run();

The Toolkit handles module orchestration while the application remains responsible for the ASP.NET Core application pipeline.

Creating a Custom Module

Custom modules can be created by inheriting from ToolkitModule and implementing the required lifecycle interfaces.

For example, a module that registers services can implement IToolkitHostBuilderModule:

public sealed class ExampleModule :
    ToolkitModule,
    IToolkitHostBuilderModule
{
    public override string Name => "Example";

    public override void Configure(IConfiguration configuration)
    {
        // Read configuration.
    }

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

The module can then be registered in the Toolkit:

toolkit.Modules.AddModule<ExampleModule>();

Once registered, it participates in the same configuration and application lifecycle as the built-in modules.

Design

The Toolkit follows a modular architecture:

Toolkit
└── ToolkitModuleContainer
    ├── Module A
    ├── Module B
    ├── Module C
    └── Module D

Each module is responsible for its own configuration and application logic.

The Toolkit is responsible for:

• module registration;
• module lookup;
• module configuration orchestration;
• module lifecycle orchestration;
• enabling and disabling modules.

Modules are responsible for:

• their own configuration;
• configuration validation;
• service registration;
• host configuration;
• application configuration.

This separation allows individual modules to remain independent while the Toolkit provides a consistent startup model.

Project Structure

A typical Toolkit-based application can keep its startup configuration small:

Program.cs
│
├── Create Toolkit
├── Register modules
├── Configure modules
├── Apply module lifecycle
└── Build and run application

Individual modules contain their own configuration and implementation details, keeping Program.cs focused on application composition rather than implementation details.