MVC Program.cs — Services, Middleware and Static Files

The Program.cs for an MVC application configures two complementary phases: the service registration phase (what services are available) and the middleware pipeline phase (how requests flow through the application). The key differences from a Web API Program.cs are the use of AddControllersWithViews() (registers Razor view engine), UseStaticFiles() (serves wwwroot content), and MapControllerRoute() (conventional routing instead of attribute routing). Getting these right — including their order — determines whether CSS loads, views render, and sessions work correctly.

Full MVC Program.cs #

// ── Build phase: register all services ───────────────────────────────────
var builder = WebApplication.CreateBuilder(args);

// Core MVC services — registers controllers, views, and Razor view engine
builder.Services.AddControllersWithViews(options =>
{
    // Global action filters applied to all controllers
    options.Filters.Add<ValidateModelStateFilter>();
    options.Filters.Add(new AutoValidateAntiforgeryTokenAttribute()); // CSRF on all POSTs
});

// Session (server-side per-user state)
builder.Services.AddDistributedMemoryCache();   // required by AddSession
builder.Services.AddSession(options =>
{
    options.IdleTimeout        = TimeSpan.FromMinutes(30);
    options.Cookie.HttpOnly    = true;
    options.Cookie.IsEssential = true;
    options.Cookie.SameSite    = SameSiteMode.Strict;
});

// Response compression (for large HTML pages)
builder.Services.AddResponseCompression(opts =>
    opts.EnableForHttps = true);

// Application services
builder.Services.AddScoped<IPostService, PostService>();
builder.Services.AddDbContext<AppDbContext>(opts =>
    opts.UseSqlServer(builder.Configuration.GetConnectionString("Default")));

var app = builder.Build();

// ── Run phase: configure middleware pipeline ───────────────────────────────

// Exception handling (first — catches all downstream exceptions)
if (app.Environment.IsDevelopment())
    app.UseDeveloperExceptionPage();
else
{
    app.UseExceptionHandler("/Home/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseResponseCompression();     // compress responses (before UseStaticFiles)
app.UseStaticFiles();             // serve wwwroot — before routing for short-circuiting
app.UseRouting();
app.UseAuthentication();          // if using identity
app.UseAuthorization();
app.UseSession();                 // must be after routing, before MapControllerRoute

app.MapControllerRoute(
    name:    "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.Run();

Static Files Configuration #

// ── UseStaticFiles serves wwwroot by default ───────────────────────────────
app.UseStaticFiles();

// ── Serve files from a different directory ────────────────────────────────
app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(builder.Environment.ContentRootPath, "StaticAssets")),
    RequestPath = "/assets",  // /assets/file.jpg → StaticAssets/file.jpg
    OnPrepareResponse = ctx =>
    {
        // Cache static assets for 1 year in browser cache
        ctx.Context.Response.Headers["Cache-Control"] = "public, max-age=31536000";
    }
});

// ── Default files (serve index.html for directory requests) ──────────────
app.UseDefaultFiles();   // must be BEFORE UseStaticFiles
app.UseStaticFiles();

Common Mistakes #

Mistake 1 — UseSession before UseRouting (session not in request context) #

❌ Wrong — session middleware cannot access route data; session setup incomplete.

✅ Correct — UseSession after UseRouting and after UseAuthentication/UseAuthorization.

Mistake 2 — Not calling UseStaticFiles (CSS and JS return 404) #

❌ Wrong — omitting UseStaticFiles means all wwwroot requests return 404.

✅ Correct — always include UseStaticFiles in MVC applications that serve static assets.