App startup in ASP.NET Core

By Rick Anderson

ASP.NET Core apps created with the web templates contain the application startup code in the Program.cs file.

For Blazor startup guidance, which adds to or supersedes the guidance in this article, see ASP.NET Core Blazor startup.

The following app startup code supports several app types:

• Blazor Web Apps
• Razor Pages
• MVC controllers with views
• Web API with controllers
• Minimal APIs

using WebAll.Components;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseAuthorization();

app.MapGet("/hi", () => "Hello!");

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

app.UseAntiforgery();

app.Run();

Apps that use EventSource can measure the startup time to understand and optimize startup performance. The ServerReady event in Microsoft.AspNetCore.Hosting represents the point where the server is ready to respond to requests.

Extend Startup with startup filters

Use IStartupFilter:

• To configure middleware at the beginning or end of an app's middleware pipeline without an explicit call to Use{Middleware}. Use IStartupFilter to add defaults to the beginning of the pipeline without explicitly registering the default middleware. IStartupFilter allows a different component to call Use{Middleware} on behalf of the app author.
• To create a pipeline of Configure methods. IStartupFilter.Configure can set a middleware to run before or after middleware added by libraries.

An IStartupFilter implementation implements Configure, which receives and returns an Action<IApplicationBuilder>. An IApplicationBuilder defines a class to configure an app's request pipeline. For more information, see Create a middleware pipeline with IApplicationBuilder.

Each IStartupFilter implementation can add one or more middlewares in the request pipeline. The filters are invoked in the order they were added to the service container. Filters can add middleware before or after passing control to the next filter, thus they append to the beginning or end of the app pipeline.

The following example demonstrates how to register a middleware with IStartupFilter. The RequestSetOptionsMiddleware middleware sets an options value from a query string parameter:

public class RequestSetOptionsMiddleware
{
    private readonly RequestDelegate _next;

    public RequestSetOptionsMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    // Test with https://localhost:5001/Privacy/?option=Hello
    public async Task Invoke(HttpContext httpContext)
    {
        var option = httpContext.Request.Query["option"];

        if (!string.IsNullOrWhiteSpace(option))
        {
            httpContext.Items["option"] = WebUtility.HtmlEncode(option);
        }

        await _next(httpContext);
    }
}

The RequestSetOptionsMiddleware is configured in the RequestSetOptionsStartupFilter class:

public class RequestSetOptionsStartupFilter : IStartupFilter
{
    public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next)
    {
        return builder =>
        {
            builder.UseMiddleware<RequestSetOptionsMiddleware>();
            next(builder);
        };
    }
}

The IStartupFilter implementation is registered in Program.cs:

using WebStartup.Middleware;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.AddTransient<IStartupFilter,
                      RequestSetOptionsStartupFilter>();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

When a query string parameter for option is provided, the middleware processes the value assignment before the ASP.NET Core middleware renders the response:

@page
@model PrivacyModel
@{
    ViewData["Title"] = "Privacy Policy";
}
<h1>@ViewData["Title"]</h1>

<p> Append query string ?option=hello</p>
Option String: @HttpContext.Items["option"];

Middleware execution order is set by the order of IStartupFilter registrations:

• Multiple IStartupFilter implementations might interact with the same objects. If ordering is important, order their IStartupFilter service registrations to match the order that their middlewares should run.

• Libraries can add middleware with one or more IStartupFilter implementations that run before or after other app middleware registered with IStartupFilter. To invoke an IStartupFilter middleware before a middleware added by a library's IStartupFilter:

  • Position the service registration before the library is added to the service container.
  • To invoke afterward, position the service registration after the library is added.

You can't extend the ASP.NET Core app when you override Configure. For more information, see this GitHub issue.

Add configuration at startup from an external assembly

An IHostingStartup implementation allows adding enhancements to an app at startup from an external assembly outside of the app's Program.cs file. For more information, see Use hosting startup assemblies in ASP.NET Core.

Startup, ConfigureServices, and Configure

For information on using the ConfigureServices and Configure methods with the minimal hosting model, see:

• Use Startup with the minimal hosting model
• The ASP.NET Core 5.0 version of this article:
  • The ConfigureServices method
  • The Configure method