Modularis.Json 0.1.0

Modularis

Modularis is a trusted in-process plugin runtime for .NET hosts. It gives a host a small contract layer, JSON package discovery, shadow-copy loading, collectible load contexts, reload, unload, diagnostics, and typed contribution lookup.

The first baseline targets explicit, trusted extensions. It is not a sandbox. Plugins run inside the host process and can use the permissions available to that process.

Packages

• Modularis.Abstractions: plugin and host contracts.
• Modularis.Hosting: runtime loading, reload, unload, diagnostics, and typed contribution indexing.
• Modularis.Json: plugin.json reading and filesystem package discovery.

Documentation

• Getting started
• Plugin package format
• Trusted runtime model
• Release process
• Changelog
• Current release notes

Minimal Host Setup

using Modularis.Hosting;
using Modularis.Json;

var discovery = new JsonPluginPackageDiscovery();
var host = new PluginHost(discovery);

var result = await host.LoadAsync(new PluginHostLoadRequest(
    @"D:\AppData\Plugins",
    ["sample.plugin"],
    [typeof(ICommandContribution)]));

if (!result.IsSuccess)
{
    throw new InvalidOperationException(result.Message);
}

if (host.TryGetContribution<ICommandContribution>("open-settings", out var contribution))
{
    await contribution.Instance.ExecuteAsync(CancellationToken.None);
}

Hosts choose the trusted plugin ids and the contribution contract types that a load request may register. Any contribution outside the allowed contract list is rejected and reported through diagnostics.

Minimal Plugin Module

using Modularis;

public sealed class SettingsPluginModule : IPluginModule
{
    public ValueTask ConfigureAsync(
        IPluginRegistration registration,
        PluginContext context,
        CancellationToken cancellationToken = default)
    {
        registration.Add<ICommandContribution>(
            "open-settings",
            new OpenSettingsCommand(),
            new PluginContributionMetadata(
                DisplayName: "Open Settings",
                Description: "Opens the host settings view."));

        return ValueTask.CompletedTask;
    }
}

Plugin projects should reference Modularis.Abstractions and the host-owned contract assembly for the contributions they expose. They should not reference a specific host implementation package unless that host intentionally publishes one.

Plugin Package Shape

The default manifest filename is plugin.json. Discovery accepts either a manifest in the configured root directory or one manifest per immediate child directory.

plugins/
  sample.plugin/
    plugin.json
    Sample.Plugin.dll
    dependency.dll

Example manifest:

{
  "id": "sample.plugin",
  "displayName": "Sample Plugin",
  "version": "1.0.0",
  "description": "Sample package.",
  "entryAssembly": "Sample.Plugin.dll",
  "entryType": "Sample.Plugin.SettingsPluginModule"
}

entryAssembly and entryType are required in v0.1. The loader resolves the declared type directly and does not scan assemblies for plugin modules.

Runtime Behavior

• Packages are loaded from a shadow copy so original package files can be replaced after load.
• Each loaded package gets its own collectible load context.
• Shared contract assemblies are loaded from the host side.
• LoadAsync can load valid trusted packages while reporting diagnostics for skipped or failed packages.
• ReloadAsync builds the next state before applying it and preserves the last good state if the new load reports an error.
• UnloadAll clears host-visible contributions and requests unload for loaded plugin contexts.

Build, Test, Pack

dotnet build Modularis.sln
dotnet test Modularis.sln
dotnet pack Modularis.sln -c Release -o artifacts/packages

Current Limitations

• v0.1 is trusted in-process only.
• There is no automatic file watcher or hot reload loop.
• There is no dependency-injection helper package yet.
• There is no out-of-process runtime for untrusted plugins.