TCIS.Pluggable.Engine.AspNetCore 1.0.0-rc.16

TCIS.Pluggable.Engine.AspNetCore

Lets a plugin expose its own HTTP endpoints — Minimal APIs, gRPC services or SignalR hubs — without the Platform host knowing they exist.

Split out of TCIS.Pluggable.Engine on purpose: a Worker Service, a console app or a Hangfire host can use the pipeline engine without dragging in the whole of ASP.NET Core.

Table of contents

1. Registration

dotnet add package TCIS.Pluggable.Engine.AspNetCore

var app = builder.Build();

app.UseTCISCore();
app.UseRequestTimeouts();

app.MapControllers();
app.MapPluggableEndpoints();   // <- maps endpoints declared by loaded modules

app.Run();

The namespace stays TCIS.Pluggable.Engine.Modules even though the types now live in a separate assembly — existing code only needs to add the package reference, not touch its using directives.

2. Exposing endpoints from a plugin

Implement IPluggableEndpointModule — it extends ISiteModule, so one class both registers services and maps routes:

public sealed class CatLaiModule : IPluggableEndpointModule
{
    public string SiteCode => "CATLAI";

    public void RegisterServices(IServiceCollection services, IConfiguration configuration)
    {
        services.AddScoped<ICustomsGateway, CatLaiCustomsGateway>();
    }

    public void MapEndpoints(IEndpointRouteBuilder endpoints)
    {
        var group = endpoints.MapGroup("/api/v1/sites/catlai")
                             .RequireAuthorization()
                             .WithTags("CatLai");

        group.MapPost("/customs/webhook", async (
            CustomsCallback payload,
            ICustomsGateway gateway,
            CancellationToken ct) =>
        {
            await gateway.HandleCallbackAsync(payload, ct);
            return Results.Accepted();
        });
    }
}

This is the sanctioned way to add a port-specific integration — a customs webhook, a partner callback, a scale-house feed — without touching the Platform routing table.

3. How mapping works

MapPluggableEndpoints() walks IModuleRegistry, and for every module that implements IPluggableEndpointModule it calls MapEndpoints during startup.

That means:

• Only modules actually loaded for this host contribute endpoints. A plugin the host never passed to AddSitePlugins maps nothing.
• Mapping happens once at startup, not per request. There is no routing cost at runtime.
• A Platform module can implement the interface too, if the endpoint is genuinely standard business.

4. Routing conventions

Endpoints coming from plugins are still public API, so Chapter 1 applies in full. In particular:

Prefix plugin routes with the site (/api/v1/sites/catlai/...) so two ports cannot collide on the same path when several small ports share one deployment. Nothing enforces this automatically; a collision would surface as an ambiguous-route exception at startup, which is loud but late.

5. Pitfalls