MechaOnion 0.1.0-preview
See the version list below for details.
dotnet add package MechaOnion --version 0.1.0-preview
NuGet\Install-Package MechaOnion -Version 0.1.0-preview
<PackageReference Include="MechaOnion" Version="0.1.0-preview" />
<PackageVersion Include="MechaOnion" Version="0.1.0-preview" />
<PackageReference Include="MechaOnion" />
paket add MechaOnion --version 0.1.0-preview
#r "nuget: MechaOnion, 0.1.0-preview"
#:package MechaOnion@0.1.0-preview
#addin nuget:?package=MechaOnion&version=0.1.0-preview&prerelease
#tool nuget:?package=MechaOnion&version=0.1.0-preview&prerelease
MechaOnion
MechaOnion is a single-assembly, modular base library for .NET (net10.0). Each module
lives in its own folder and namespace (MechaOnion.<Module>) and can be enabled or
disabled by configuration.
Current version: 0.1.0-preview.
Three-line setup
var builder = WebApplication.CreateBuilder(args);
builder.AddMechaOnion(builder.Configuration); // 1) configuration and options
builder.Services.AddMechaOnion(); // 2) services, repositories and providers
var app = builder.Build();
app.UseMechaOnion(); // 3) middlewares and endpoints
app.Run();
UseMechaOnion applies a fixed pipeline order regardless of module discovery order:
CORS → Routing → Tenant → Permissions → Tracing → Errors → endpoints → health checks.
Modules
| Flag | Module | Responsibility |
|---|---|---|
Core |
Core | Entities, contracts, exceptions, attributes, helpers and validations |
Auth |
Auth | JWT validation, permissions and CORS |
Configs |
Configs | Tenant/app key-value configuration |
Tenants |
Tenants | Tenants, themes and resolution |
Users |
Users | Users, login, profiles, groups, roles and fields |
Events |
Events | Event catalog, automations, webhooks and integrations |
Configuration |
Configuration | Host sources, environment/project info and OpenAPI helpers |
Database |
Database | EF Core base context and repository infrastructure |
Messaging |
Messaging | Local and RabbitMQ providers, retry, scheduling and DLQ |
MessagingAdmin |
MessagingAdmin | Administration API for the local and RabbitMQ providers |
Observability |
Observability | Structured logging, tracing and correlation ids |
HealthChecks |
HealthChecks | Readiness and liveness endpoints |
Web |
Web | CORS, error handling, ProblemDetails, JSON options and OpenAPI/Scalar docs |
Enrich |
Enrich | Data enrichment pipeline and contracts |
Flags are combined through MechaOnion:Modules (default All). Dependencies are
auto-enabled and registered in topological order.
Configuration
"MechaOnion": {
"Modules": "All",
"ServiceName": "MechaOnion",
"EnableTenantFilter": true,
"MigrationsAssembly": "",
"DefaultTenantId": null,
"EnableSingleTenantFallback": false
}
Extending the library
Default implementations are registered with TryAdd; the last registration wins, so
consumers can replace services without editing the library.
// Replace a service through its public contract.
builder.Services.Replace(ServiceDescriptor.Scoped<IEnrichmentRepository, MyEnrichRepository>());
// Replace the database provider through options.
builder.Services.AddSingleton(new MechaOnionDbContextOptions
{
MigrationsAssembly = "MyHost",
EnableTenantFilter = true,
ConfigureProvider = options => options.UseNpgsql(connectionString),
});
// Register a custom tenant resolver after the library (last one wins).
builder.Services.AddScoped<ITenantResolver, MyTenantResolver>();
E-mail delivery is decoupled through IEmailDispatcher (MechaOnion.Communication). The
host registers an adapter for its e-mail service:
builder.Services.Replace(
ServiceDescriptor.Singleton<IEmailDispatcher, MyEmailDispatcher>());
Persistence and migrations
The library does not apply migrations; the consumer owns the schema. The sample host
uses MechaOnionDbContext directly with Database.EnsureCreated():
using var scope = app.Services.CreateScope();
var dbContext = scope.ServiceProvider.GetRequiredService<MechaOnionDbContext>();
dbContext.Database.EnsureCreated();
A production host can inherit from MechaOnionDbContext to add its own mappings and seeds,
and keep the migrations in its own assembly:
public sealed class AppDbContext : MechaOnionDbContext
{
public AppDbContext(
DatabaseSettings databaseSettings,
ITenantContext? tenantContext = null,
MechaOnionDbContextOptions? options = null)
: base(databaseSettings, tenantContext, options)
{
}
}
Set MechaOnion:MigrationsAssembly (or MechaOnionDbContextOptions.MigrationsAssembly) to
the assembly that contains the migrations.
Tenant resolution
The tenant is resolved in this order:
X-Tenant-Idheadertenant_idclaimtenantIdroute valueMechaOnion:DefaultTenantId(fixed fallback)- Single-tenant fallback (
MechaOnion:EnableSingleTenantFallback)
The single-tenant fallback queries the Tenant table on demand. It only applies when the
endpoint requires a tenant and no other resolver found one:
- Multi-tenant: leave
EnableSingleTenantFallbackdisabled. Requests without an explicit tenant keep returning400. - Single-tenant: enable
EnableSingleTenantFallback. If the database contains exactly one tenant, that tenant is used automatically. If it contains zero or multiple tenants, the request still fails with400. - Fixed tenant: set
DefaultTenantIdwhen the fallback must be a specific tenant regardless of the database contents.
API documentation
The Web module registers and maps the OpenAPI document and the Scalar UI:
GET /docs— Scalar UIGET /openapi/v1.json— OpenAPI document
Both endpoints are anonymous and explicitly opt out of the tenant requirement, so they
can be opened directly in a browser without X-Tenant-Id, a tenant route value or a
resolved tenant. Mapping is skipped when EnvironmentSettings:EnvironmentType is
production.
Messaging administration (v1/MessagingAdmin)
The MessagingAdmin module (MechaOnionModules.MessagingAdmin) exposes a single
v1/MessagingAdmin API over two providers:
- local — messages persisted in the application database through the local messaging
provider (
MechaOnionDbContext); - rabbitmq — queues and exchanges of a vhost accessed through the RabbitMQ Management HTTP API (the management plugin must be enabled).
Enabling the module is just a flag: MechaOnion:Modules = "All" already includes it. The
Messaging, Auth, Database and Configuration dependencies are auto-enabled, and the
permissions remain system_admin/admin.
Settings
"MessagingAdminSettings": {
"ManagementUrl": "http://rabbitmq:15672",
"Username": "",
"Password": "",
"VirtualHost": "/",
"TimeoutSeconds": 10,
"MaxPageSize": 200
}
Username and Password are sensitive: provide them through environment variables,
user-secrets or the orchestrator's secret manager — never commit real credentials.
Without ManagementUrl/credentials the local provider keeps working; rabbitmq
responds 503 with an explicit message.
Provider selection
Every route accepts provider=local|rabbitmq as an optional query parameter:
- without
provider, the default islocalwhenMessagingSettings.Local=trueandrabbitmqwhenfalse; provider=localwithMessagingSettings.Local=falsereturns409 Conflict;provider=rabbitmqforces the external provider regardless ofMessagingSettings.Local;- an unknown
providerreturns400 Bad Request; - Management API errors never fall back silently to the local provider:
401/403unauthorized,404not found,409duplicate,502invalid response and503timeout/unavailable.
Capability matrix
| Operation | local | rabbitmq |
|---|---|---|
| List/detail queues and topics/exchanges | ✅ | ✅ |
| Create/remove queues and exchanges | ✅ | ✅ |
| List paginated messages | ✅ (queues and topics) | ✅ (queues only) |
| Inspect a message without consuming | ✅ | ✅ (ack_requeue_true, MaxPageSize window) |
| Individual message removal | ✅ | ❌ (400, capability not available) |
| Purge | ✅ (pending/scheduled; optional DLQ) | ✅ (queues only) |
| Purge an exchange | ✅ (local topics) | ❌ (not offered by the Management API) |
| Requeue/reprocess | ✅ (back to Pending) |
✅ (publish + best-effort removal) |
Limitations
- Exchange purge: the RabbitMQ Management API does not support purging an exchange;
the operation returns
400citing the missing capability. - Individual message removal: the Management API cannot remove an arbitrary message;
the
rabbitmqprovider refuses with400. - Listing messages from an exchange: exchanges do not store messages, so listing and
inspection on RabbitMQ exchanges return
400. - Best-effort requeue: the external message is republished to its origin
(
x-death[0].queue) or to the explicittarget, and the origin is removed withack_requeue_false. The operation is at-least-once; duplicates and concurrency are possible. Withoutx-deathand withouttarget, the response is400. - Credentials: they never appear in logs, responses or exceptions;
Authorizationis not logged.
Running the sample
The MechaOnion.Demo host composes the library with the three lines, creates its own
schema with EnsureCreated() and seeds a tenant, an admin role and an admin user. It covers
login, tenant, configuration and messaging.
dotnet run --project samples/MechaOnion.Demo/MechaOnion.Demo.csproj
The JWT secret comes from MECHAONION_DEMO_JWT_SECRET; without the variable the demo
generates an ephemeral key valid only for the current process.
Build, test and pack
dotnet restore MechaOnion.slnx
dotnet build MechaOnion.slnx
dotnet test tests/MechaOnion.Tests/MechaOnion.Tests.csproj
dotnet pack src/MechaOnion/MechaOnion.csproj -c Release -o artifacts
Integration tests use PostgreSQL and are skipped unless a test connection is configured:
MECHAONION_TEST_DB_CONNECTION="Host=localhost;Database=mechaonion;Username=postgres;Password=postgres" \
dotnet test tests/MechaOnion.Tests/MechaOnion.Tests.csproj
The optional RabbitMQ end-to-end tests are skipped unless the Management API is configured:
MECHAONION_TEST_RABBITMQ_MANAGEMENT_URL="http://localhost:15672" \
MECHAONION_TEST_RABBITMQ_USER="guest" \
MECHAONION_TEST_RABBITMQ_PASSWORD="guest" \
dotnet test tests/MechaOnion.Tests/MechaOnion.Tests.csproj --filter "FullyQualifiedName~RabbitMq"
Preview limitations
- The library does not apply migrations, does not include ASP.NET Identity, 2FA, social login, a database per tenant or automatic data migration.
License
MIT. See LICENSE.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- AutoMapper (= 14.0.0)
- DynamicLanguageRuntime (>= 1.3.5)
- Jint (>= 4.10.1)
- Microsoft.AspNetCore.Authentication.JwtBearer (>= 10.0.9)
- Microsoft.AspNetCore.OpenApi (>= 10.0.9)
- Microsoft.EntityFrameworkCore (>= 10.0.9)
- Microsoft.EntityFrameworkCore.Relational (>= 10.0.9)
- MoonSharp (>= 2.0.0)
- NCrontab.Signed (>= 3.4.0)
- Npgsql (>= 10.0.3)
- Npgsql.EntityFrameworkCore.PostgreSQL (>= 10.0.2)
- RabbitMQ.Client (>= 6.8.1)
- Scalar.AspNetCore (>= 2.16.7)
- Serilog (>= 4.3.1)
- Serilog.Enrichers.AspNetCore (>= 1.0.0)
- Serilog.Enrichers.Environment (>= 3.0.1)
- Serilog.Enrichers.Process (>= 3.0.0)
- Serilog.Sinks.Console (>= 6.1.1)
- Serilog.Sinks.OpenTelemetry (>= 4.2.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 0.4.0-preview | 50 | 11/20/2026 |
| 0.3.0-preview | 59 | 11/18/2026 |
| 0.2.0-preview | 55 | 11/17/2026 |
| 0.1.0-preview | 82 | 11/8/2026 |