NeedlrBootstrapper

NexusLabs.Needlr.Hosting

NeedlrBootstrapper Class

Wraps an application entry point with bootstrap lifecycle management: a pre-DI logger, a pre-DI Microsoft.Extensions.Configuration.IConfiguration, top-level exception handling, and guaranteed cleanup.

public sealed record NeedlrBootstrapper : System.IEquatable<NexusLabs.Needlr.Hosting.NeedlrBootstrapper>

Inheritance System.Object 🡒 NeedlrBootstrapper

Implements System.IEquatable<NeedlrBootstrapper>

Example

await new NeedlrBootstrapper()
    .ConfigureBootstrapConfiguration(builder => builder
        .AddJsonFile("appsettings.json", optional: true)
        .AddEnvironmentVariables())
    .RunAsync(async (ctx, ct) =>
    {
        var host = new Syringe()
            .UsingSourceGen()
            .ForHost()
            .UsingOptions(() => CreateHostOptions.Default.UsingCurrentProcessArgs())
            .BuildHost();

        await host.RunAsync(ct);
    });

Remarks

By default a console logger and an emptyMicrosoft.Extensions.Configuration.IConfiguration are created automatically. Override with UsingLoggerFactory(this NeedlrBootstrapper, ILoggerFactory) to supply your own factory (e.g. a Serilog two-stage init factory), and ConfigureBootstrapConfiguration(this NeedlrBootstrapper, Action<IConfigurationBuilder>) to add configuration sources needed during the bootstrap phase.

The bootstrap configuration is not the same Microsoft.Extensions.Configuration.IConfiguration that the application's DI container will provide. They are independent instances. See BootstrapConfiguration for details.

Unexpected exceptions from the callback are logged at Critical and rethrown after cleanup so a top-level caller produces a nonzero process exit code. Cooperative cancellation completes normally without a critical log.

Methods

NeedlrBootstrapper.RunAsync(Func<NeedlrBootstrapContext,CancellationToken,Task>, CancellationToken) Method

Runs the application entry point with full bootstrap lifecycle management.

public System.Threading.Tasks.Task RunAsync(System.Func<NexusLabs.Needlr.Hosting.NeedlrBootstrapContext,System.Threading.CancellationToken,System.Threading.Tasks.Task> runAsync, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

runAsync System.Func<NeedlrBootstrapContext,System.Threading.CancellationToken,System.Threading.Tasks.Task>

The application callback. Receives a NeedlrBootstrapContext containing the bootstrap logger and bootstrap configuration, and the System.Threading.CancellationToken passed to this method.

cancellationToken System.Threading.CancellationToken

Optional cancellation token forwarded to the callback.

Returns

System.Threading.Tasks.Task
A System.Threading.Tasks.Task that completes when the application exits normally or through cooperative cancellation, and faults after cleanup for an unexpected exception.

Example

await new NeedlrBootstrapper().RunAsync(async (ctx, ct) =>
{
    ctx.Logger.LogInformation("Application starting...");
    var path = ctx.BootstrapConfiguration["SomeSetting"];
    await RunMyAppAsync(ct);
});