aspnet-conventions

ASP.NET Core Conventions

Program.cs — canonical composition order

var builder = WebApplication.CreateBuilder(args);

// 1. Configuration (auto-loaded: appsettings.json → appsettings.{Env}.json → env vars → User Secrets in dev)
// Override or extend:
builder.Configuration.AddEnvironmentVariables(prefix: "MYAPP_");

// 2. Services
builder.Services.AddControllers();            // MVC controllers
// OR for Minimal API: no AddControllers needed

// Options pattern — never inject IConfiguration directly into services
builder.Services.Configure<JwtOptions>(builder.Configuration.GetSection("Jwt"));
builder.Services.Configure<SmtpOptions>(builder.Configuration.GetSection("Smtp"));

// DI registrations
builder.Services.AddScoped<IUserRepository, UserRepository>();      // per-request state
builder.Services.AddSingleton<IEmailTemplateCache, EmailTemplateCache>(); // shared, thread-safe
builder.Services.AddTransient<IPasswordHasher, Argon2PasswordHasher>();   // stateless

// Authentication + Authorization
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(o => builder.Configuration.Bind("Jwt", o));
builder.Services.AddAuthorization(o =>
{
    o.AddPolicy("ProfileOwner", p => p.AddRequirements(new ProfileOwnerRequirement()));
});
builder.Services.AddSingleton<IAuthorizationHandler, ProfileOwnerHandler>();

// Validation (FluentValidation)
builder.Services.AddValidatorsFromAssembly(typeof(Program).Assembly);

// EF Core
builder.Services.AddDbContext<AppDbContext>(o =>
    o.UseNpgsql(builder.Configuration.GetConnectionString("DefaultConnection")
                ?? throw new InvalidOperationException("Connection string not configured.")));

// Data Protection
builder.Services.AddDataProtection()
    .SetApplicationName("MyApp")
    .PersistKeysToFileSystem(new DirectoryInfo("/var/keys"))  // prod: use Azure Blob / Redis
    .ProtectKeysWithCertificate(/* ... */);

// Health checks
builder.Services.AddHealthChecks()
    .AddDbContextCheck<AppDbContext>();

// API doc (optional)
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// 3. Middleware pipeline — ORDER MATTERS
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
    app.UseDeveloperExceptionPage();
}
else
{
    app.UseExceptionHandler("/error");   // maps to a ProblemDetails endpoint
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthentication();
app.UseAuthorization();

// 4. Endpoints
app.MapControllers();                    // MVC
app.MapUserEndpoints();                  // Minimal API extension method
app.MapHealthChecks("/health");

app.Run();