A lightweight and elegant .NET library for orchestrating application bootstrap operations. Define startup actions as a pipeline, track their execution status, and expose bootstrap progress via HTTP middleware.
- Pipeline-Based Bootstrap: Define and execute startup actions in a structured, sequential pipeline
- Status Monitoring: Built-in HTTP middleware to expose bootstrap status and progress
- Flexible Error Handling: Choose between service shutdown or continuation on bootstrap failure
- Dependency Injection: First-class support for .NET dependency injection
- Multi-Framework: Supports .NET 8.0 and .NET 9.0
- Lightweight: Minimal dependencies and overhead
Install via .NET CLI:
dotnet add package NullOpsDevs.Bootstrap
Or add to your .csproj file:
<ItemGroup>
<PackageReference Include="NullOpsDevs.Bootstrap" Version="1.0.0" />
</ItemGroup>
1. Create a Bootstrap Action
Define a bootstrap action by implementing IBootstrapPipelineAction:
using NullOpsDevs.Bootstrap.Base;
internal class DatabaseMigrationAction : IBootstrapPipelineAction
{
public string Name => "Database Migration";
public async Task<bool> Invoke(CancellationToken cancellationToken)
{
// Your bootstrap logic here
// For example: run database migrations, warm up caches, etc.
await RunMigrationsAsync(cancellationToken);
// Return true if successful, false otherwise
return true;
}
}
Add your bootstrap actions to the pipeline in Program.cs:
using NullOpsDevs.Bootstrap;
using NullOpsDevs.Bootstrap.Enums;
var builder = WebApplication.CreateBuilder(args);
// Register the bootstrap pipeline
builder.Services.AddBootstrapPipeline(x =>
{
x.Use<DatabaseMigrationAction>();
x.Use<CacheWarmupAction>();
x.Use<HealthCheckAction>();
});
// Register bootstrap services
builder.Services.UseBootstrap(ErrorBootstrapBehavior.Continue);
var app = builder.Build();
// Trigger bootstrap execution
app.Services.GetRequiredService<IBootstrapService>();
// Add bootstrap status middleware
app.UseBootstrapMiddleware();
app.Run();
3. Monitor Bootstrap Status
The middleware automatically exposes bootstrap status. When a request is made during bootstrap, the middleware returns:
{
"state": "InProgress",
"currentAction": "Database Migration",
"message": "Service is starting up..."
}
Error Handling Strategies
Choose how your application handles bootstrap failures:
ExitOnError (Recommended for Production)
The service will shut down on bootstrap failure. Ideal for containerized environments with automatic restart:
builder.Services.UseBootstrap(ErrorBootstrapBehavior.ExitOnError);
Use this when:
- Running in Docker, Kubernetes, or systemd with restart policies
- Bootstrap failure means the service cannot function properly
- You want to ensure a clean restart on failure
Continue (Recommended for Development)
The service continues running but the middleware always returns an error:
builder.Services.UseBootstrap(ErrorBootstrapBehavior.Continue);
Use this when:
- Developing and debugging bootstrap actions
- You need the service to stay running for diagnostics
- Bootstrap failure is non-critical
The bootstrap service tracks the following states:
State
Description
| InProgress |
Bootstrap actions are currently executing |
| Successful |
All bootstrap actions completed successfully |
| Error |
One or more bootstrap actions failed |
Dependency Injection in Actions
Bootstrap actions support constructor injection:
internal class CacheWarmupAction : IBootstrapPipelineAction
{
private readonly ILogger<CacheWarmupAction> _logger;
private readonly ICacheService _cacheService;
public string Name => "Cache Warmup";
public CacheWarmupAction(
ILogger<CacheWarmupAction> logger,
ICacheService cacheService)
{
_logger = logger;
_cacheService = cacheService;
}
public async Task<bool> Invoke(CancellationToken cancellationToken)
{
_logger.LogInformation("Starting cache warmup...");
await _cacheService.WarmupAsync(cancellationToken);
_logger.LogInformation("Cache warmup completed");
return true;
}
}
- Database Migrations: Run EF Core migrations before accepting requests
- Cache Warmup: Pre-populate caches with frequently accessed data
- Configuration Validation: Verify configuration and external dependencies
- Health Checks: Validate connectivity to external services (databases, APIs, message queues)
- Data Seeding: Initialize default data or reference tables
- Service Registration: Register with service discovery systems
The library consists of several key components:
- IBootstrapPipelineAction: Interface for defining bootstrap actions
- IBootstrapService: Service that manages pipeline execution
- BootstrapMiddleware: HTTP middleware for status reporting
- DefaultBootstrapPipeline: Default pipeline implementation
- DefaultStartupPipelineBuilder: Fluent builder for pipeline configuration
For a complete working example, check out the example project.
Contributions are welcome! Please feel free to submit a Pull Request.
This project is licensed under the MIT License - see the LICENSE file for details.