dotnet / dotnet/AspNetCore.Docs
update middleware images and list of middleware
- Dominant language
- C#
- Stars
- 13.1k
- Forks
- 24.6k
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 97
Description
***EDIT by @Rick-Anderson :***
Update middleware doc
The documentation page [Routing in ASP.NET Core § Routing basics](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/routing?view=aspnetcore-6.0#routing-basics) has this to say:
> Apps typically don't need to call `UseRouting` or `UseEndpoints`. [WebApplicationBuilder](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.builder.webapplicationbuilder) configures a middleware pipeline that wraps middleware added in `Program.cs` with `UseRouting` and `UseEndpoints`. However, apps can change the order in which `UseRouting` and `UseEndpoints` run by calling these methods explicitly.
So the conclusion is that it is fine to default to not calling `UseRouting` in `Program.cs`?
The documentation page [ASP.NET Core Middleware § Middleware order](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/middleware/?view=aspnetcore-6.0#middleware-order) seems to disagree:
> The following diagram shows the complete request processing pipeline for ASP.NET Core MVC and Razor Pages apps. You can see how, in a typical app, existing middlewares are ordered and where custom middlewares are added. You have full control over how to reorder existing middlewares or inject new custom middlewares as necessary for your scenarios.
>
> 
>
> The **Endpoint** middleware in the preceding diagram executes the filter pipeline for the corresponding app type—MVC or Razor Pages.
>
> The **Routing** middleware in the preceding diagram is shown following **Static Files**. This is the order that the project templates implement by explicitly calling [app.UseRouting](xref:Microsoft.AspNetCore.Builder.EndpointRoutingApplicationBuilderExtensions.UseRouting%2A). If you don't call `app.UseRouting`, the **Routing** middleware runs at the beginning of the pipeline by default. For more information, see [Routing](xref:fundamentals/routing).
>
> 
>
> The order that middleware components are added in the `Program.cs` file defines the order in which the middleware components are invoked on requests and the reverse order for the response. The order is **critical** for security, performance, and functionality.
>
> The following highlighted code in `Program.cs` adds security-related middleware components in the typical recommended order:
>
> ```cs
> using IndividualAccountsExample.Data;
> using Microsoft.AspNetCore.Identity;
> using Microsoft.EntityFrameworkCore;
>
> var builder = WebApplication.CreateBuilder(args);
>
> // Add services to the container.
> var connectionString = builder.Configuration.GetConnectionString("DefaultConnection");
> builder.Services.AddDbContext(options =>
> options.UseSqlServer(connectionString));
> builder.Services.AddDatabaseDeveloperPageExceptionFilter();
>
> builder.Services.AddDefaultIdentity(options => options.SignIn.RequireConfirmedAccount = true)
> .AddEntityFrameworkStores();
> builder.Services.AddRazorPages();
>
> var app = builder.Build();
>
> // Configure the HTTP request pipeline.
> if (app.Environment.IsDevelopment())
> {
> app.UseMigrationsEndPoint();
> }
> else
> {
> app.UseExceptionHandler("/Error");
> // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
> app.UseHsts();
> }
>
> app.UseHttpsRedirection();
> app.UseStaticFiles();
> // app.UseCookiePolicy();
>
> app.UseRouting();
> // app.UseRequestLocalization();
> // app.UseCors();
>
> app.UseAuthentication();
> app.UseAuthorization();
> // app.UseSession();
> // app.UseResponseCompression();
> // app.UseResponseCaching();
>
> app.MapRazorPages();
> app.MapControllerRoute(
> name: "default",
> pattern: "{controller=Home}/{action=Index}/{id?}");
>
> app.Run();
> ```
(Highlighted are lines from `// Configure the HTTP request pipeline.` to `// app.UseResponseCaching();`, inclusively.)
So the bottom line of this docs page seems to be:
- In a typical recommended scenario `UseRouting` should be called explicitly in this precise order, this is also what `dotnet new` templates are doing
- You may reorder middleware registrations or not call `UseRouting` explicitly at all, in which case it will be implicitly called in the beginning of the pipeline, however
- You need to know what you're doing, because you risk having security vulnerabilities, lagging performance and diminished functionality if you deviate from the templates.
This is quite different from the recommendation from the doc page about Routing, which says that "*Apps typically don't need to call `UseRouting`*".
I believe the docs pages should be reconciled. Either the Routing page or the Middleware page (or even both) should be edited depending on where the Routing middleware should be registered and if the order is critical for security, performance and functionality.
---
#### Document Details
⚠ *Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.*
* ID: 9898482c-fa54-7ce2-1716-d14fbe03990d
* Version Independent ID: 3926c686-0ccc-f9fe-ca52-0134612a1623
* Content: [ASP.NET Core Middleware](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/middleware/?view=aspnetcore-6.0)
* Content Source: [aspnetcore/fundamentals/middleware/index.md](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/fundamentals/middleware/index.md)
* Product: **aspnet-core**
* Technology: **aspnetcore-fundamentals**
* GitHub Login: @Rick-Anderson
* Microsoft Alias: **riande**
---
#### Document Details
⚠ *Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.*
* ID: 32374077-e02e-d6a6-1cea-05e58447b7cd
* Version Independent ID: 86aeab13-1c25-9fc1-4e56-0390cb40c242
* Content: [Routing in ASP.NET Core](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/routing?view=aspnetcore-6.0)
* Content Source: [aspnetcore/fundamentals/routing.md](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/fundamentals/routing.md)
* Product: **aspnet-core**
* Technology: **aspnetcore-fundamentals**
* GitHub Login: @Rick-Anderson
* Microsoft Alias: **riande**
Contributor guide
Assessment
This issue has not been assessed yet.