DotNetStartupGuard 1.0.0

DotNetStartupGuard

Validates application startup configuration, ensures ports are listening, and prevents silent startup failures.

Problems Solved

• Port not listening: Application starts but port isn't actually listening
• Silent crashes: Application crashes during startup without clear error messages
• Kestrel binding issues: Port binding failures not detected early
• IIS vs Kestrel confusion: Configuration differences between hosting environments
• Blocking startup code: Synchronous blocking code in Program.cs hangs startup
• Database connection hangs: Startup hangs waiting for database connection
• Missing environment variables: Required environment variables not set in production
• Wrong environment loaded: Production code running with development configuration
• Docker startup failures: Container startup issues not detected
• Missing health checks: No validation that application is ready to serve requests

Installation

dotnet add package DotNetStartupGuard

Quick Start

1. Validate Required Configuration

Problem: Missing configuration keys cause runtime failures in production.

using DotNetStartupGuard;

// ✅ GOOD: Validate configuration on startup
builder.Services.AddStartupValidation(validator =>
{
    validator.RequireEnvironmentVariable("DATABASE_CONNECTION_STRING");
    validator.RequireConfigurationKey("AppSettings:ApiKey");
    validator.RequirePortListening(5000);
});

// Validate after building the app
var app = builder.Build();
await app.ValidateStartupAsync();

2. Environment Variable Validation

Problem: Missing environment variables cause runtime errors.

// ❌ BAD: No validation, fails at runtime
var connectionString = Environment.GetEnvironmentVariable("DB_CONNECTION");

// ✅ GOOD: Validate on startup
EnvironmentHelper.RequireEnvironmentVariables(
    logger,
    "DATABASE_CONNECTION_STRING",
    "API_KEY",
    "REDIS_CONNECTION_STRING"
);

3. Port Listening Validation

Problem: Application claims to be running but port isn't listening.

// ✅ GOOD: Verify port is actually listening
var validator = new StartupValidator(configuration, logger);
validator.RequirePortListening(5000);
await validator.ValidateAsync();

4. Environment Detection

Problem: Wrong environment configuration loaded (dev config in production).

// ✅ GOOD: Validate environment is correct
EnvironmentHelper.ValidateEnvironment(
    configuration,
    logger,
    "Production", "Staging" // Only allow these environments
);

// Detect Docker environment
if (EnvironmentHelper.IsRunningInDocker())
{
    logger.LogInformation("Running in Docker container");
}

5. Health Checks for Startup

Problem: No way to verify application is ready to serve requests.

// ✅ GOOD: Add startup health checks
builder.Services.AddStartupHealthChecks()
    .AddDatabaseCheck()
    .AddPortCheck(5000)
    .AddEnvironmentVariableCheck("DATABASE_CONNECTION_STRING");

// Health check endpoint
app.MapHealthChecks("/health");

Real-World Example

var builder = WebApplication.CreateBuilder(args);

// Add startup validation
builder.Services.AddStartupValidation(validator =>
{
    // Validate environment variables
    validator.RequireEnvironmentVariable("DATABASE_CONNECTION_STRING");
    validator.RequireEnvironmentVariable("REDIS_CONNECTION_STRING");
    
    // Validate configuration keys
    validator.RequireConfigurationKey("AppSettings:ApiKey");
    validator.RequireConfigurationKey("AppSettings:JwtSecret");
    
    // Validate port is available
    validator.RequirePortListening(5000);
});

// Add health checks
builder.Services.AddStartupHealthChecks()
    .AddDatabaseCheck()
    .AddPortCheck(5000);

var app = builder.Build();

// Validate before running
await app.ValidateStartupAsync();

// Validate environment
EnvironmentHelper.ValidateEnvironment(
    app.Configuration,
    app.Logger,
    "Production", "Staging"
);

app.Run();

Complete Startup Validation Example

public class Program
{
    public static async Task Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);
        
        // Configure services
        builder.Services.AddControllers();
        builder.Services.AddDbContext<AppDbContext>(options =>
            options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection")));
        
        // Add startup validation
        builder.Services.AddStartupValidation(validator =>
        {
            validator.RequireEnvironmentVariable("DATABASE_CONNECTION_STRING");
            validator.RequireConfigurationKey("AppSettings:ApiKey");
        });
        
        // Add health checks
        builder.Services.AddStartupHealthChecks()
            .AddDatabaseCheck()
            .AddPortCheck(5000);
        
        var app = builder.Build();
        
        // Validate startup before accepting requests
        try
        {
            await app.ValidateStartupAsync();
            app.Logger.LogInformation("Startup validation passed");
        }
        catch (StartupValidationException ex)
        {
            app.Logger.LogCritical(ex, "Startup validation failed");
            Environment.Exit(1);
        }
        
        app.MapControllers();
        app.MapHealthChecks("/health");
        
        app.Run();
    }
}

Best Practices

1. Validate all required configuration before accepting requests
2. Check environment variables that are required for operation
3. Verify ports are listening to catch binding issues early
4. Use health checks to verify application readiness
5. Validate environment to prevent wrong config in production
6. Fail fast - exit immediately if validation fails

API Reference

• StartupValidator - Validates configuration, environment variables, and ports
• EnvironmentHelper - Utilities for environment variable validation
• StartupHealthChecks - Health check implementations for startup validation
• AddStartupValidation() - Extension method to add validation to services
• ValidateStartupAsync() - Extension method to validate on app startup