Services Registration & Lifetimes

Overview

BeepService is the top-level container that wires together all core BeepDM components (IDMEEditor, IConfigEditor, IAssemblyHandler, etc.) and exposes them through a single IBeepService interface suitable for dependency injection.

// Desktop equivalent of the proposed AddBeepForDesktop()
IBeepService beep = services.AddBeepServices()
    .WithDirectory(AppContext.BaseDirectory)
    .WithAppRepo("MyApp")
    .WithConfigType(BeepConfigType.Application)
    .WithMapping()
    .WithAssemblyLoading()
    .AsSingleton()          // .AsScoped() for web / Blazor Server
    .Build();

// Optional, and genuinely available:
services.AddBeepLoggingForDesktop("MyApp");
services.AddBeepAuditForDesktop("MyApp");

The services layer provides these registration styles:

Files in this module

BeepService

BeepService implements IBeepService and IDisposable. It creates and owns all core BeepDM component instances during Configure().

Properties

Configure()

Initialises all components. Called automatically by the DI registration helpers or manually for direct instantiation.

// Direct instantiation (no DI):
var beep = new BeepService();
beep.Configure(
    directorypath: AppContext.BaseDirectory,
    containername: "MyApp",
    configType: BeepConfigType.DataConnector,
    AddasSingleton: false
);

Initialisation order inside Configure():

1. Sets AppRepoName, ConfigureationType, BeepDirectory
2. Creates ErrorsInfo, DMLogger, JsonLoader
3. Creates ConfigEditor (reads JSON configs from {BeepDirectory}/Beep)
4. Creates Util, AssemblyHandler, DMEEditor
5. Optionally registers all instances into IServiceCollection (singleton or scoped)
6. Calls LoadConfigurations() — loads data-source configs, mappings

LoadServicesScoped() / LoadServicesSingleton()

// Called automatically by Configure(); exposed for advanced scenarios
beep.LoadServicesSingleton();  // registers IDMLogger, IConfigEditor, IDMEEditor, IUtil, IJsonLoader, IAssemblyHandler
beep.LoadServicesScoped();     // registers same interfaces using AddKeyedScoped

BeepServiceOptions

The canonical options object used by all registration helpers.

Validation Exceptions

Desktop Registration

The proposal was for AddBeepForDesktop to cover WinForms, WPF, and any long-running desktop process, always registering as Singleton.

DesktopBeepOptions

Registration

// In Program.cs (WinForms / WPF with IHost):
var host = Host.CreateDefaultBuilder(args)
    .ConfigureServices((context, services) =>
    {
        services.AddBeepForDesktop(opts =>
        {
            opts.DirectoryPath = AppContext.BaseDirectory;
            opts.AppRepoName = "MyDesktopApp";
            opts.EnableProgressReporting = true;
            opts.EnableAutoMapping = true;
            opts.EnableAssemblyLoading = true;
        });
    })
    .Build();

// Resolve after host is built:
var beepService = host.Services.GetRequiredService<IBeepService>();

With Progress Reporting

var progress = new Progress<PassedArgs>(args =>
{
    Console.WriteLine($"[{args.EventType}] {args.Messege}");
});

// If your desktop extension surfaces a UseBeepForDesktop method:
var beepService = host.UseBeepForDesktop(progress);

Web / ASP.NET Core Registration

The proposal was for AddBeepForWeb to cover ASP.NET Core Web API and MVC applications, always registering as Scoped (one instance per HTTP request).

WebBeepOptions

Registration & Middleware

// Program.cs — options pattern
builder.Services.AddBeepForWeb(opts =>
{
    opts.DirectoryPath = Path.Combine(builder.Environment.ContentRootPath, "Beep");
    opts.AppRepoName = "MyWebApi";
    opts.EnableConnectionPooling = true;
    opts.EnableRequestIsolation = true;
});

var app = builder.Build();
app.UseBeepForWeb();   // Registers connection cleanup middleware
app.MapControllers();
app.Run();

Fluent Builder (Web)

builder.Services.AddBeepForWeb()
    .InDirectory(Path.Combine(basePath, "Beep"))
    .WithAppRepo("MyWebApi")
    .WithConnectionPooling()
    .WithRequestIsolation()
    .WithApiDiscovery()
    .WithMapping()
    .Build();

Controller Injection Example

[ApiController]
[Route("api/[controller]")]
public class DataSourceController : ControllerBase
{
    private readonly IBeepService _beep;
    public DataSourceController(IBeepService beep) => _beep = beep;

    [HttpGet("list")]
    public IActionResult GetDataSources()
    {
        var sources = _beep.DMEEditor.DataSources
            .Select(ds => new { ds.DatasourceName, Type = ds.DatasourceType.ToString() });
        return Ok(sources);
    }
}

Blazor Registration

The proposal was for two separate extension methods covering the two Blazor hosting models.

BlazorBeepOptions

Blazor Server

// Program.cs — Blazor Server
builder.Services.AddBeepForBlazorServer(opts =>
{
    opts.DirectoryPath = Path.Combine(builder.Environment.ContentRootPath, "Beep");
    opts.AppRepoName = "MyBlazorServerApp";
    opts.EnableSignalRProgress = true;    // real-time progress via SignalR
    opts.EnableCircuitHandlers = true;    // cleanup on circuit disconnect
});
// Lifetime = Scoped (one per Blazor circuit)

Blazor WebAssembly

// Program.cs — Blazor WASM
builder.Services.AddBeepForBlazorWasm(opts =>
{
    opts.DirectoryPath = "Beep";          // browser virtual path
    opts.AppRepoName = "MyBlazorWasmApp";
    opts.UseBrowserStorage = true;        // persist config in localStorage
});
// Lifetime = Singleton (WASM has single user per process)

Blazor Component Usage

@inject IBeepService BeepService
@inject IJSRuntime JSRuntime

@code {
    private List<string> dataSources = new();

    protected override async Task OnInitializedAsync()
    {
        var ds = BeepService.DMEEditor.GetDataSource("mydb");
        if (ds != null)
        {
            var entities = await Task.Run(() => ds.GetEntities("", new List<ReportFilter>()));
            dataSources = entities.Select(e => e.EntityName).ToList();
        }
    }
}

Fluent Builder API

AddBeepServices() (no arguments) returns an IBeepServiceBuilder for method-chained configuration. This provides the best IntelliSense experience and is platform-agnostic.

IBeepServiceBuilder Methods

Usage

// Desktop (singleton)
services.AddBeepServices()
    .WithDirectory(AppContext.BaseDirectory)
    .WithAppRepo("MyApp")
    .WithConfigType(BeepConfigType.Application)
    .WithMapping()
    .WithAssemblyLoading()
    .AsSingleton()
    .Build();

// Web (scoped)
services.AddBeepServices()
    .WithDirectory(Path.Combine(basePath, "Beep"))
    .WithAppRepo("MyWebApi")
    .WithProperty("EnableConnectionPooling", true)
    .AsScoped()
    .Build();

Options Pattern (alternative)

IBeepService beep = services.AddBeepServices(opts =>
{
    opts.DirectoryPath = AppContext.BaseDirectory;
    opts.AppRepoName = "MyApp";
    opts.ConfigType = BeepConfigType.DataConnector;
    opts.ServiceLifetime = ServiceLifetime.Singleton;
    opts.EnableAutoMapping = true;
    opts.EnableAssemblyLoading = true;
});

Legacy Registration API

Register() is preserved for backward compatibility. Prefer the platform-specific helpers for new code.

// Backward-compatible simple registration
IBeepService beep = services.Register(
    directoryPath: AppContext.BaseDirectory,
    containerName: "MyApp",
    configType: BeepConfigType.DataConnector,
    addAsSingleton: true
);

EnvironmentService

EnvironmentService is a static helper that resolves platform-appropriate data folder paths and populates BeepDM mapping configurations. It is called internally by BeepService.Configure() but can also be used directly.

Folder Creation

// Create the root Beep folder in a platform-appropriate location:
// Windows: %APPDATA%\TheTechIdea\Beep  (or AppContext.BaseDirectory\TheTechIdea\Beep)
// Linux/macOS: ~/.local/share/TheTechIdea/Beep
string mainFolder = EnvironmentService.CreateMainFolder();

// Create a named application repository sub-folder:
string appFolder = EnvironmentService.CreateAppRepofolder("MyApp");

// Extension form — callable on an IDMEEditor instance:
string path = dmeEditor.CreateMainFolder();

Beep Mapping Setup

// Registers all connection configs, datasource mappings, and query configs for an editor:
dmeEditor.CreateBeepMapping();

ServiceCollectionExtensions

Low-level IServiceCollection extensions for registering individual BeepDM components.

JsonLoader

// Singleton (default for long-lived apps)
services.AddJsonLoader();

// Scoped (per-request in web apps)
services.AddJsonLoaderScoped();

// Transient (new instance each time)
services.AddJsonLoaderTransient();

DMEEditor

// Register as singleton with existing handler + logger instances
services.AddDMEEditor(assemblyHandler, logger);

ServiceHelper

ServiceHelper is a static service-locator that wraps a cached IServiceProvider. Use it sparingly — prefer constructor injection wherever possible.

// Typically called once in Program.cs / App.xaml.cs after building the host:
ServiceHelper.Initialize(host.Services);

// Resolve a service anywhere, without constructor injection:
var beep = ServiceHelper.GetService<IBeepService>();
var editor = ServiceHelper.GetService<IDMEEditor>();

Lifetime Selection Guide

BeepConfigType Values

End-to-End Examples

// Example 1 (WinForms) and Example 4 (Blazor WASM) -> Singleton
services.AddBeepServices()
    .WithDirectory(AppContext.BaseDirectory).WithAppRepo("MyApp")
    .WithConfigType(BeepConfigType.Application)
    .WithMapping().WithAssemblyLoading()
    .AsSingleton().Build();

// Example 2 (Web API) and Example 3 (Blazor Server) -> Scoped
builder.Services.AddBeepServices()
    .WithDirectory(AppContext.BaseDirectory).WithAppRepo("MyApp")
    .WithConfigType(BeepConfigType.Application)
    .AsScoped().Build();

Example 1 — WinForms with IHost

// Program.cs
[STAThread]
static void Main()
{
    var host = Host.CreateDefaultBuilder()
        .ConfigureServices((ctx, services) =>
        {
            services.AddBeepForDesktop(opts =>
            {
                opts.DirectoryPath = AppContext.BaseDirectory;
                opts.AppRepoName = "MyDesktopApp";
                opts.EnableProgressReporting = true;
            });
            services.AddSingleton<MainForm>();
        })
        .Build();

    ServiceHelper.Initialize(host.Services);
    var beepService = host.Services.GetRequiredService<IBeepService>();

    Application.Run(host.Services.GetRequiredService<MainForm>());
}

Example 2 — ASP.NET Core Web API

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddBeepForWeb(opts =>
{
    opts.DirectoryPath = Path.Combine(builder.Environment.ContentRootPath, "Beep");
    opts.AppRepoName = "MyWebApi";
    opts.EnableConnectionPooling = true;
});

builder.Services.AddControllers();

var app = builder.Build();
app.UseBeepForWeb();
app.MapControllers();
app.Run();

Example 3 — Blazor Server

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorComponents().AddInteractiveServerComponents();
builder.Services.AddBeepForBlazorServer(opts =>
{
    opts.AppRepoName = "MyBlazorApp";
    opts.EnableSignalRProgress = true;
    opts.EnableCircuitHandlers = true;
});

var app = builder.Build();
app.MapRazorComponents<App>().AddInteractiveServerRenderMode();
app.Run();

Example 4 — Blazor WebAssembly

// Program.cs
var builder = WebAssemblyHostBuilder.CreateDefault(args);
builder.RootComponents.Add<App>("#app");

builder.Services.AddBeepForBlazorWasm(opts =>
{
    opts.AppRepoName = "MyBlazorWasmApp";
    opts.UseBrowserStorage = true;
});

await builder.Build().RunAsync();

Example 5 — Direct Instantiation (No DI)

// Useful for unit tests, console scripts, or legacy code
var beep = new BeepService();
beep.Configure(
    directorypath: Path.Combine(Path.GetTempPath(), "BeepTest"),
    containername: "TestContainer",
    configType: BeepConfigType.DataConnector,
    AddasSingleton: false
);

var ds = beep.DMEEditor.GetDataSource("northwind");
ds.Openconnection();

Example 6 — Fluent Builder (Generic / CLI)

var host = Host.CreateDefaultBuilder(args)
    .ConfigureServices((ctx, services) =>
    {
        services.AddBeepServices()
            .WithDirectory(AppContext.BaseDirectory)
            .WithAppRepo("BeepShell")
            .WithConfigType(BeepConfigType.Application)
            .WithAssemblyLoading()
            .WithMapping()
            .AsSingleton()
            .Build();
    })
    .Build();

var beep = host.Services.GetRequiredService<IBeepService>();