Modularis.Templates 0.2.0

Modularis

Modularis is a modern .NET runtime for reliable plugin lifecycles. It supports trusted in-process plugins with verified cooperative unloading and explicit data-only plugins in authenticated worker processes with a hard termination boundary. Its focus is dependency isolation, transactional updates, rollback, bounded execution, and actionable diagnostics—not merely loading a DLL.

The current unpublished development surface adds leak-safe application integration, verified local package management, desktop integration, and process-isolated execution to the certified foundation.

What the 1.0 foundation provides

• One collectible load context and immutable staged package per plugin generation.
• Explicit configure, initialize, state-import, start, health, drain, quiesce, stop, dispose, and unload states.
• Typed contribution leases; the normal host API never returns an untracked raw plugin instance.
• Atomic blue-green updates and stop-first updates with last-known-good rollback.
• Bounded lease drain, lifecycle timeouts, cleanup aggregation, WeakReference unload verification, and quarantine.
• A host-owned IPluginLifetime for named tasks, cleanup callbacks, and resources, with deterministic cleanup and immutable per-stage unload evidence.
• Shared host contract identity with isolated private managed dependencies, native resolution diagnostics, and satellite resources.
• Manifest compatibility gates, package/file hashes, publisher policies, and RSA-SHA256 signature policies.
• Optional state migration, directory observation, host DI integration, approved facades, logs, activities, metrics, and a compliance kit.
• Durable enable/disable/reconcile operations, immutable operational snapshots, recovery journals, health checks, and safe quarantine maintenance.
• A plugin project template plus unload-safety diagnostics for common resource, task, static-event, static-state, and native-code hazards.

Unload is cooperative. Succeeded means the collectible context was observed as collected after a bounded unload request. Arbitrary plugin code can still retain itself through threads, statics, events, timers, native code, or host references; such a generation is reported as blocked and quarantined. AssemblyLoadContext is not a security sandbox.

Packages

• Modularis.Abstractions — plugin lifecycle, registration, identity, health, and state contracts.
• Modularis.Hosting — generations, leases, staging, dependency isolation, updates, trust, diagnostics, and unload verification.
• Modularis.Json — bounded plugin.json parsing and directory discovery.
• Modularis.Extensions.DependencyInjection — concise host registration and hosted start/stop/update observation.
• Modularis.Compliance — repeatable package, activation, and verified-unload reports.
• Modularis.Packaging — key generation, complete package hashing, atomic signing, and independent verification.
• Modularis.Analyzers — build-only unload-safety diagnostics for plugin authors.
• Modularis.Templates — the installable modularis-plugin project template.
• Modularis.Tool — installable keygen, sign, and verify commands for build and deployment workflows.
• Modularis.Worker — application-local worker for authenticated process-isolated plugin execution.

Minimal host

services.AddModularis(runtime => runtime
    .UsePluginDirectory("plugins")
    .RequirePlugin<IReportProvider>("reports.plugin")
    .EnableOperations()
    .EnableHotUpdates());

services.AddHealthChecks().AddModularis();

var application = services.GetRequiredService<IPluginApplication>();
var report = await application.InvokeAsync<IReportProvider, PluginReport, ReportRow>(
    "reports.plugin",
    "monthly",
    static (provider, token) => provider.CreateAsync(token),
    static pluginReport => ReportRow.Copy(pluginReport));

RequirePlugin<T> combines required selection and contract registration. AllowPlugin<T> is the optional equivalent. IPluginApplication is the normal application boundary: it scopes the lease and returns copied state/results. PluginRuntime remains available for advanced host infrastructure and is started and stopped automatically by a generic host. Local package management requires AddModularis, signed-package trust, and durable operations. See the application-integration and operations guides before exposing administrative actions.

Documentation

• Ten-minute getting started
• Safe application integration and local packages
• Interactive server application integration
• Windows Forms application integration
• .NET MAUI Blazor Hybrid application integration
• Structured host outcomes and simple setup goal
• Structured host outcomes execution report
• Plugin authoring
• Manifest reference
• Lifecycle, leases, and updates
• Security and platform support
• Unload troubleshooting
• Observability
• Production operations and recovery
• Compliance kit
• Reference host
• v0.1 migration
• Performance baseline
• RC.5 API stability review
• Ten-minute package-only quick start
• Operator runbook
• Public API policy
• Package-only clean-room validation
• Signing and verification
• First application pilot checklist
• Release readiness
• Release promotion evidence
• RC verification report
• Process-isolated plugins
• Process isolation ADR

Verify locally

dotnet build Modularis.sln -c Release
dotnet test Modularis.sln -c Release --no-build
./eng/verify-clean-room.ps1
./eng/verify-interactive-web.ps1
./eng/verify-desktop.ps1
./eng/verify-desktop.ps1 -Mode Adversarial
./eng/verify-hybrid.ps1 -Mode All
./eng/verify-process-isolation.ps1 -Mode All
./eng/verify-signing-tool.ps1

The primary target is net10.0 on CoreCLR. See the platform matrix before choosing a UI, mobile, browser, trimming, AOT, or native-library scenario.