SilverLABS.SilverSHELL.AMS

App Module Service (AMS) - A powerful plugin system for building modular Blazor applications.

Features

• Dynamic Module Loading - Load and unload modules at runtime
• Navigation Endpoints - Modules can register navigation menu items
• Dashboard Widgets - Modules can provide dashboard widgets
• Search Providers - Integrated search across all modules
• Module Testing - Built-in test framework for module validation
• Dependency Management - Automatic dependency resolution
• Module Context - Shared context for cross-module communication

Installation

dotnet add package SilverLABS.SilverSHELL.AMS

Quick Start

1. Create a Module

using SilverSHELL.AMS.Interfaces;
using SilverSHELL.AMS.Models;

public class MyModule : IAppModule
{
    public string Name { get; set; } = "My Module";
    public bool Enabled { get; set; } = true;
    public string Icon { get; set; } = "📦";
    public Version Version => new Version(1, 0, 0);
    public string Description { get; set; } = "My custom module";
    public List<string> Dependencies { get; set; } = new();

    public List<ModuleEndPoint> EndPoints { get; } = new()
    {
        new ModuleEndPoint
        {
            Name = "My Page",
            Path = "/mypage",
            Icon = "📄",
            RequiredRoles = new[] { "User" }
        }
    };

    public List<ModuleWidget> Widgets { get; } = new();
    public IModuleSearchProvider? SearchProvider => null;
    public IModuleTest? Tests => null;

    public Task InitializeAsync(ModuleContext context)
    {
        // Initialize module
        return Task.CompletedTask;
    }

    public Task DisposeAsync()
    {
        // Cleanup resources
        return Task.CompletedTask;
    }
}

2. Register Module Service

using SilverSHELL.AMS.Extensions;

var builder = WebAssemblyHostBuilder.CreateDefault(args);

// Register AMS
builder.Services.AddSilverShellAMS(options =>
{
    options.EnableAutoDiscovery = true;
    options.ModulesPath = "/modules";
});

// Register your modules
builder.Services.AddModule<MyModule>();

await builder.Build().RunAsync();

3. Configure Router for Module Components

IMPORTANT: If your modules contain Razor components (pages with @page directive), you must register their assemblies with Blazor's Router.

In your App.razor:

@using SilverSHELL.AMS
@inject IServiceProvider ServiceProvider

<Router AppAssembly="@typeof(App).Assembly"
        AdditionalAssemblies="AMSAssemblyReference.GetModuleAssemblies(ServiceProvider)">
    <Found Context="routeData">
        <RouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)" />
    </Found>
</Router>

Alternative: If you know your module types at compile time:

@using SilverSHELL.AMS

<Router AppAssembly="@typeof(App).Assembly"
        AdditionalAssemblies="AMSAssemblyReference.GetModuleAssemblies(
            typeof(MyModule),
            typeof(AnotherModule)
        )">
    <Found Context="routeData">
        <RouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)" />
    </Found>
</Router>

Note: This step is only required if your modules contain Razor components. If your modules only provide services or logic without UI components, you can skip this step.

4. Use Module Registry

@inject ModuleRegistry Registry

<h3>Loaded Modules</h3>

@foreach (var module in Registry.GetAllModules())
{
    <div>
        <h4>@module.Icon @module.Name</h4>
        <p>@module.Description</p>
        <p>Version: @module.Version</p>
    </div>
}

Module Components

Navigation Endpoints

public List<ModuleEndPoint> EndPoints { get; } = new()
{
    new ModuleEndPoint
    {
        Name = "Dashboard",
        Path = "/dashboard",
        Icon = "📊",
        Order = 1,
        RequiredRoles = new[] { "Admin" }
    }
};

Dashboard Widgets

public List<ModuleWidget> Widgets { get; } = new()
{
    new ModuleWidget
    {
        Title = "Stats Widget",
        ComponentType = typeof(StatsWidget),
        Width = 6,
        Order = 1
    }
};

Search Provider

public class MySearchProvider : IModuleSearchProvider
{
    public async Task<IEnumerable<SearchResult>> SearchAsync(string query)
    {
        // Implement search logic
        return results;
    }
}

Module Tests

public class MyModuleTests : IModuleTest
{
    public async Task<TestResult> RunTestsAsync()
    {
        // Run module tests
        return new TestResult { Passed = true };
    }
}

API Reference

IAppModule Interface

• string Name - Module name
• bool Enabled - Enable/disable module
• string Icon - Module icon
• Version Version - Module version
• string Description - Module description
• List<string> Dependencies - Module dependencies
• List<ModuleEndPoint> EndPoints - Navigation endpoints
• List<ModuleWidget> Widgets - Dashboard widgets
• IModuleSearchProvider? SearchProvider - Search provider
• IModuleTest? Tests - Test suite
• Task InitializeAsync(ModuleContext context) - Initialize module
• Task DisposeAsync() - Dispose module

ModuleRegistry Service

• void RegisterModule(IAppModule module) - Register a module
• void UnregisterModule(string moduleName) - Unregister a module
• IAppModule? GetModule(string name) - Get module by name
• IEnumerable<IAppModule> GetAllModules() - Get all modules
• IEnumerable<ModuleEndPoint> GetAllEndPoints() - Get all navigation endpoints
• IEnumerable<ModuleWidget> GetAllWidgets() - Get all widgets

AMSAssemblyReference

• Assembly[] GetModuleAssemblies(IServiceProvider serviceProvider) - Get all registered module assemblies from DI container
• Assembly[] GetModuleAssemblies(params Type[] moduleTypes) - Get assemblies from specific module types

Changelog

v1.1.0

• ✨ NEW: AMSAssemblyReference helper for automatic Blazor Router assembly registration
• 🔧 IMPROVED: Simplified setup for modules with Razor components
• 📚 DOCS: Added Router configuration guide for module component discovery
• 🎯 FEATURE: Two methods for assembly registration - runtime (via IServiceProvider) and compile-time (via Type[])

v1.0.0

• Initial release

Documentation

• Full Documentation
• Integration Guide

Support

• Issues: GitLab Issues
• Email: support@silverlabs.uk

License

This project is licensed under the MIT License.

Made with ❤️ by SilverLABS