Environments and Configuration Bootstrap

Every ASP.NET Core application targets one of three environments: Development (local developer machine), Staging (pre-production, mirrors production), or Production (live). The active environment is set via the ASPNETCORE_ENVIRONMENT environment variable. This single variable drives which configuration files are loaded, which middleware is registered, how detailed error messages are, and which feature flags are active. Getting environment management right is a critical operational discipline that prevents configuration secrets from leaking to developers and debug information from reaching users.

Environment Variables and Configuration Order #

// ── ASPNETCORE_ENVIRONMENT — set before running the app ───────────────────
// Shell:   export ASPNETCORE_ENVIRONMENT=Development
// Windows: $env:ASPNETCORE_ENVIRONMENT = "Development"
// Docker:  ENV ASPNETCORE_ENVIRONMENT=Production
// launchSettings.json: "environmentVariables": { "ASPNETCORE_ENVIRONMENT": "Development" }

// ── Configuration loading order (later sources override earlier) ──────────
// Host defaults:
//   1. appsettings.json           (base settings — committed to source control)
//   2. appsettings.{env}.json     (env-specific — Development version committed,
//                                    Production version NOT committed)
//   3. User Secrets (Dev only)    (sensitive dev settings — never committed)
//   4. Environment variables      (CI/CD, Docker, cloud platform settings)
//   5. Command-line arguments     (highest priority — for testing and overrides)

// ── Checking the current environment ──────────────────────────────────────
var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
    app.UseDeveloperExceptionPage();  // detailed stack traces in browser
}

if (app.Environment.IsProduction())
{
    app.UseHsts();              // HTTP Strict Transport Security header
    app.UseHttpsRedirection();  // redirect HTTP to HTTPS
}

// Custom environment check
if (app.Environment.IsEnvironment("Staging"))
{
    app.UseStatusCodePages();
}

// IWebHostEnvironment in a service
public class FeatureService(IWebHostEnvironment env)
{
    public bool IsDetailedLoggingEnabled => env.IsDevelopment();
}

Environment-Specific Service Registration #

// Register different implementations based on environment
if (builder.Environment.IsDevelopment())
{
    // Use an in-memory email sender in development — no real emails sent
    builder.Services.AddSingleton<IEmailSender, InMemoryEmailSender>();

    // Use a fake payment processor in development
    builder.Services.AddScoped<IPaymentProcessor, FakePaymentProcessor>();
}
else
{
    // Real implementations for staging and production
    builder.Services.AddSingleton<IEmailSender, SmtpEmailSender>();
    builder.Services.AddScoped<IPaymentProcessor, StripePaymentProcessor>();
}

// appsettings.json — base settings
{
    "Logging": { "LogLevel": { "Default": "Warning" } },
    "AllowedHosts": "*"
}

// appsettings.Development.json — development overrides
{
    "Logging": { "LogLevel": { "Default": "Debug", "Microsoft.AspNetCore": "Warning" } },
    "ConnectionStrings": { "Default": "Server=(localdb)\\mssqllocaldb;Database=BlogApp_Dev" }
}

Common Mistakes #

Mistake 1 — Committing production secrets in appsettings.Production.json #

❌ Wrong — connection strings, API keys in source control are a security incident waiting to happen.

✅ Correct — production secrets via environment variables, Key Vault, or Secrets Manager only.

Mistake 2 — Not validating required configuration at startup #

❌ Wrong — application starts successfully but crashes on first database access with an opaque error.

✅ Correct — validate required configuration values in Program.cs before Build() and fail fast with clear error messages.