Middleware in Minimal API apps

WebApplication automatically adds the following middleware in Minimal API applications depending on certain conditions:

• UseDeveloperExceptionPage is added first when the HostingEnvironment is "Development".
• UseRouting is added second if user code didn't already call UseRouting and if there are endpoints configured, for example app.MapGet.
• UseEndpoints is added at the end of the middleware pipeline if any endpoints are configured.
• UseAuthentication is added immediately after UseRouting if user code didn't already call UseAuthentication and if IAuthenticationSchemeProvider can be detected in the service provider. IAuthenticationSchemeProvider is added by default when using AddAuthentication, and services are detected using IServiceProviderIsService.
• UseAuthorization is added next if user code didn't already call UseAuthorization and if IAuthorizationHandlerProvider can be detected in the service provider. IAuthorizationHandlerProvider is added by default when using AddAuthorization, and services are detected using IServiceProviderIsService.
• User configured middleware and endpoints are added between UseRouting and UseEndpoints.

The following code is effectively what the automatic middleware being added to the app produces:

if (isDevelopment)
{
    app.UseDeveloperExceptionPage();
}

app.UseRouting();

if (isAuthenticationConfigured)
{
    app.UseAuthentication();
}

if (isAuthorizationConfigured)
{
    app.UseAuthorization();
}

// user middleware/endpoints
app.CustomMiddleware(...);
app.MapGet("/", () => "hello world");
// end user middleware/endpoints

app.UseEndpoints(e => {});

In some cases, the default middleware configuration isn't correct for the app and requires modification. For example, UseCors should be called before UseAuthentication and UseAuthorization. The app needs to call UseAuthentication and UseAuthorization if UseCors is called:

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

If middleware should be run before route matching occurs, UseRouting should be called and the middleware should be placed before the call to UseRouting. UseEndpoints isn't required in this case as it is automatically added as described previously:

app.Use((context, next) =>
{
    return next(context);
});

app.UseRouting();

// other middleware and endpoints

When adding a terminal middleware:

• The middleware must be added after UseEndpoints.
• The app needs to call UseRouting and UseEndpoints so that the terminal middleware can be placed at the correct location.

app.UseRouting();

app.MapGet("/", () => "hello world");

app.UseEndpoints(e => {});

app.Run(context =>
{
    context.Response.StatusCode = 404;
    return Task.CompletedTask;
});

Terminal middleware is middleware that runs if no endpoint handles the request.

WebApplication automatically adds the following middleware in Minimal API applications depending on certain conditions:

• UseDeveloperExceptionPage is added first when the HostingEnvironment is "Development".

• UseRouting is added second, if the user code didn't already call UseRouting and endpoints are configured, for example app.MapGet.

• UseEndpoints is added at the end of the middleware pipeline if endpoints are configured.

• UseAuthentication is added immediately after UseRouting, if user code didn't already call UseAuthentication and if IAuthenticationSchemeProvider can be detected in the service provider. IAuthenticationSchemeProvider is added by default when you use AddAuthentication, and services are detected by using IServiceProviderIsService.

• UseAuthorization is added next, if user code didn't already call UseAuthorization and if IAuthorizationHandlerProvider can be detected in the service provider. IAuthorizationHandlerProvider is added by default when you use AddAuthorization, and services are detected by using IServiceProviderIsService.

• User configured middleware and endpoints are added between UseRouting and UseEndpoints.

The following code is effectively what the automatic middleware being added to the app produces:

if (isDevelopment)
{
    app.UseDeveloperExceptionPage();
}

app.UseRouting();

if (isAuthenticationConfigured)
{
    app.UseAuthentication();
}

if (isAuthorizationConfigured)
{
    app.UseAuthorization();
}

// User middleware/endpoints
app.CustomMiddleware(...);
app.MapGet("/", () => "hello world");
// End user middleware/endpoints

app.UseEndpoints(e => {});

In some cases, the default middleware configuration isn't correct for the app and requires modification. For example, UseCors should be called before UseAuthentication and UseAuthorization. The app needs to call UseAuthentication and UseAuthorization if UseCors is called:

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

If middleware should run before route matching occurs, UseRouting should be called and the middleware should be placed before the call to UseRouting. UseEndpoints isn't required in this case because it's automatically added as described earlier:

app.Use((context, next) =>
{
    return next(context);
});

app.UseRouting();

// Other middleware and endpoints

When adding a terminal middleware:

• The middleware must be added after UseEndpoints.

• The app needs to call UseRouting and UseEndpoints so the terminal middleware can be placed at the correct location.

app.UseRouting();

app.MapGet("/", () => "hello world");

app.UseEndpoints(e => {});

app.Run(context =>
{
    context.Response.StatusCode = 404;
    return Task.CompletedTask;
});

Terminal middleware is middleware that runs if no endpoint handles the request.

For information on antiforgery middleware in Minimal APIs, see Prevent Cross-Site Request Forgery (XSRF/CSRF) attacks in ASP.NET Core.