Skip to content

Commit 9c175be

Browse files
0x25CBFC4F0x25CBFC4F
committed
Add comprehensive README and QuickStart guide for NullOpsDevs.Bootstrap, including installation, usage, and examples.
1 parent 19a3d59 commit 9c175be

File tree

2 files changed

+213
-2
lines changed

2 files changed

+213
-2
lines changed

‎README.md‎

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,213 @@
11
# 🚀 NullOpsDevs.Bootstrap
22

3+
[![NuGet](https://img.shields.io/badge/nuget-1.0.0-blue.svg)](https://www.nuget.org/packages/NullOpsDevs.Bootstrap/)
4+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
5+
[![.NET](https://img.shields.io/badge/.NET-8.0-purple.svg)](https://dotnet.microsoft.com/)
6+
[![.NET](https://img.shields.io/badge/.NET-9.0-purple.svg)](https://dotnet.microsoft.com/)
7+
[![.NET](https://img.shields.io/badge/Documentation-blue)](https://bootstrap.nullops.systems/)
8+
9+
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.
10+
11+
## ✨ Features
12+
13+
- **Pipeline-Based Bootstrap**: Define and execute startup actions in a structured, sequential pipeline
14+
- **Status Monitoring**: Built-in HTTP middleware to expose bootstrap status and progress
15+
- **Flexible Error Handling**: Choose between service shutdown or continuation on bootstrap failure
16+
- **Dependency Injection**: First-class support for .NET dependency injection
17+
- **Multi-Framework**: Supports .NET 8.0 and .NET 9.0
18+
- **Lightweight**: Minimal dependencies and overhead
19+
20+
## 📦 Installation
21+
22+
Install via .NET CLI:
23+
24+
```bash
25+
dotnet add package NullOpsDevs.Bootstrap
26+
```
27+
28+
Or add to your `.csproj` file:
29+
30+
```xml
31+
<ItemGroup>
32+
<PackageReference Include="NullOpsDevs.Bootstrap" Version="1.0.0" />
33+
</ItemGroup>
34+
```
35+
36+
## 🚀 Quick Start
37+
38+
### 1. Create a Bootstrap Action
39+
40+
Define a bootstrap action by implementing `IBootstrapPipelineAction`:
41+
42+
```csharp
43+
using NullOpsDevs.Bootstrap.Base;
44+
45+
internal class DatabaseMigrationAction : IBootstrapPipelineAction
46+
{
47+
public string Name => "Database Migration";
48+
49+
public async Task<bool> Invoke(CancellationToken cancellationToken)
50+
{
51+
// Your bootstrap logic here
52+
// For example: run database migrations, warm up caches, etc.
53+
await RunMigrationsAsync(cancellationToken);
54+
55+
// Return true if successful, false otherwise
56+
return true;
57+
}
58+
}
59+
```
60+
61+
### 2. Register the Pipeline
62+
63+
Add your bootstrap actions to the pipeline in `Program.cs`:
64+
65+
```csharp
66+
using NullOpsDevs.Bootstrap;
67+
using NullOpsDevs.Bootstrap.Enums;
68+
69+
var builder = WebApplication.CreateBuilder(args);
70+
71+
// Register the bootstrap pipeline
72+
builder.Services.AddBootstrapPipeline(x =>
73+
{
74+
x.Use<DatabaseMigrationAction>();
75+
x.Use<CacheWarmupAction>();
76+
x.Use<HealthCheckAction>();
77+
});
78+
79+
// Register bootstrap services
80+
builder.Services.UseBootstrap(ErrorBootstrapBehavior.Continue);
81+
82+
var app = builder.Build();
83+
84+
// Trigger bootstrap execution
85+
app.Services.GetRequiredService<IBootstrapService>();
86+
87+
// Add bootstrap status middleware
88+
app.UseBootstrapMiddleware();
89+
90+
app.Run();
91+
```
92+
93+
### 3. Monitor Bootstrap Status
94+
95+
The middleware automatically exposes bootstrap status. When a request is made during bootstrap, the middleware returns:
96+
97+
```json
98+
{
99+
"state": "InProgress",
100+
"currentAction": "Database Migration",
101+
"message": "Service is starting up..."
102+
}
103+
```
104+
105+
## 📖 Usage
106+
107+
### Error Handling Strategies
108+
109+
Choose how your application handles bootstrap failures:
110+
111+
#### ExitOnError (Recommended for Production)
112+
113+
The service will shut down on bootstrap failure. Ideal for containerized environments with automatic restart:
114+
115+
```csharp
116+
builder.Services.UseBootstrap(ErrorBootstrapBehavior.ExitOnError);
117+
```
118+
119+
Use this when:
120+
- Running in Docker, Kubernetes, or systemd with restart policies
121+
- Bootstrap failure means the service cannot function properly
122+
- You want to ensure a clean restart on failure
123+
124+
#### Continue (Recommended for Development)
125+
126+
The service continues running but the middleware always returns an error:
127+
128+
```csharp
129+
builder.Services.UseBootstrap(ErrorBootstrapBehavior.Continue);
130+
```
131+
132+
Use this when:
133+
- Developing and debugging bootstrap actions
134+
- You need the service to stay running for diagnostics
135+
- Bootstrap failure is non-critical
136+
137+
### Bootstrap States
138+
139+
The bootstrap service tracks the following states:
140+
141+
| State | Description |
142+
|--------------|----------------------------------------------|
143+
| `InProgress` | Bootstrap actions are currently executing |
144+
| `Successful` | All bootstrap actions completed successfully |
145+
| `Error` | One or more bootstrap actions failed |
146+
147+
### Dependency Injection in Actions
148+
149+
Bootstrap actions support constructor injection:
150+
151+
```csharp
152+
internal class CacheWarmupAction : IBootstrapPipelineAction
153+
{
154+
private readonly ILogger<CacheWarmupAction> _logger;
155+
private readonly ICacheService _cacheService;
156+
157+
public string Name => "Cache Warmup";
158+
159+
public CacheWarmupAction(
160+
ILogger<CacheWarmupAction> logger,
161+
ICacheService cacheService)
162+
{
163+
_logger = logger;
164+
_cacheService = cacheService;
165+
}
166+
167+
public async Task<bool> Invoke(CancellationToken cancellationToken)
168+
{
169+
_logger.LogInformation("Starting cache warmup...");
170+
await _cacheService.WarmupAsync(cancellationToken);
171+
_logger.LogInformation("Cache warmup completed");
172+
return true;
173+
}
174+
}
175+
```
176+
177+
## 🎯 Use Cases
178+
179+
- **Database Migrations**: Run EF Core migrations before accepting requests
180+
- **Cache Warmup**: Pre-populate caches with frequently accessed data
181+
- **Configuration Validation**: Verify configuration and external dependencies
182+
- **Health Checks**: Validate connectivity to external services (databases, APIs, message queues)
183+
- **Data Seeding**: Initialize default data or reference tables
184+
- **Service Registration**: Register with service discovery systems
185+
186+
## 🏗️ Architecture
187+
188+
The library consists of several key components:
189+
190+
- **IBootstrapPipelineAction**: Interface for defining bootstrap actions
191+
- **IBootstrapService**: Service that manages pipeline execution
192+
- **BootstrapMiddleware**: HTTP middleware for status reporting
193+
- **DefaultBootstrapPipeline**: Default pipeline implementation
194+
- **DefaultStartupPipelineBuilder**: Fluent builder for pipeline configuration
195+
196+
## 📚 Examples
197+
198+
For a complete working example, check out the [example project](https://github.com/NullOpsDevs/NullOpsDevs.Bootstrap/tree/main/src/NullOpsDevs.Bootstrap.Example).
199+
200+
## 🤝 Contributing
201+
202+
Contributions are welcome! Please feel free to submit a Pull Request.
203+
204+
## 📄 License
205+
206+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
207+
208+
## 🔗 Links
209+
210+
- [Documentation](https://bootstrap.nullops.systems/)
211+
- [NuGet Package](https://www.nuget.org/packages/NullOpsDevs.Bootstrap/)
212+
- [GitHub Repository](https://github.com/NullOpsDevs/NullOpsDevs.Bootstrap)
213+
- [Report Issues](https://github.com/NullOpsDevs/NullOpsDevs.Bootstrap/issues)

‎docs/Writerside/topics/QuickStart.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,13 @@
55
<tabs>
66
<tab id="dotnet-CLI-install" title="dotnet CLI">
77
<code-block lang="shell">
8-
dotnet add Void.Libs.Bootstrap
8+
dotnet add NullOpsDevs.Bootstrap
99
</code-block>
1010
</tab>
1111
<tab id="csproj-install" title=".csproj">
1212
<code-block lang="xml">
1313
&lt;ItemGroup&gt;
14-
&lt;PackageReference Include=&quot;Void.Libs.Bootstrap&quot; Version=&quot;&lt;...&gt;&quot; /&gt;
14+
&lt;PackageReference Include=&quot;NullOpsDevs.Bootstrap&quot; Version=&quot;&lt;...&gt;&quot; /&gt;
1515
&lt;/ItemGroup&gt;
1616
</code-block>
1717
</tab>

0 commit comments

Comments
 (0)