Remove the importance of app configuration order

[steveoh]

The problem

I was reading the docs on upgrading a 2.1 app to 3.1 which used endpoint routing and could not figure out why my routes were not being picked up. It turned out that app.UseEndpoints(...) needed to be placed before app.UseSpa(...).

There were many warnings in the migration docs about the configuration order eg:

If the app calls UseStaticFiles, place UseStaticFiles before UseRouting.

For most apps, calls to UseAuthentication, UseAuthorization, and UseCors must appear between the calls to UseRouting and UseEndpoints to be effective.

There were no warnings about endpoints and spa. I had to generate a new SPA template to look at the order to finally figure out what the issue was.

Describe the solution you'd like

It would be great if the order of app.UseX was not so critical to a functioning application. All of the gotchas and warnings would be unnecessary. I know there are technical reasons for pipeline registration but I would think that something could sit in the middle and build the configuration in the proper order.

Since I'm sure you've already discussed this and decided to push this onto the developers, I think some documentation around the endpoints and spa needs to be specifically added. Maybe some sort of ordered master list info graphic of when to register what could help.

I was getting tripped up because the spa static files were being returned instead of the api route even though my use endpoints and use routing configuration were after the use static files and use spa static files.

As you point out they have probably have discussed this and have good reasons but... I totally agree a master list of app.Usex would be useful. With short call outs to explain why.

[javiercn]

@steveoh thanks for contacting us.

@Rick-Anderson Can we get the SPA middleware added to this table? https://docs.microsoft.com/en-us/aspnet/core/fundamentals/middleware/?view=aspnetcore-3.1#built-in-middleware

[poke]

It would be great if the order of app.UseX was not so critical to a functioning application.

While that would be desirable to greatly simplify the setup, it would also cripple the flexibility a lot. Right now, the application developer is in control of what middlewares run when and how. The order of the middleware registrations is the order in which the middlewares will attempt to respond to requests.

In that sense, it makes sense that a MVC/routing middleware would usually run before the “catch-all SPA middleware to enable client-side routing” middleware in order to make the MVC routes still work. Similarly, you usually want to authenticate and authorize before you handle requests. Or if you add UseStaticFiles after authentication, then those requests would also be authenticated (which can be a useful decision).

The biggest complexity comes with endpoint routing and the split between UseRouting and UseEndpoints. With that split comes the additional decision of what to run before routing and what in between routing and endpoints. It does become a lot clearer though if you understand exactly what these middlewares do:

• UseRouting looks at the route of the request and decides which endpoint to take.
• UseEndpoints uses the information from the earlier routing and executes the endpoint.

The configuration you pass to UseEndpoints there is the endpoint configuration which UseRouting will use to decide, and which UseEndpoints will use to execute. In that way, the configuration applies to both middlewares simultaneously.

Now, any middleware that should make use of the endpoint information, i.e. what endpoint UseRouting decided to take, should come after UseRouting but before the endpoint gets executed in UseEndpoints. So middlewares like authentication, authorization and CORS usually go between them.

---

The middleware setup surely could be more convention based, without requiring developers to set it up themselves. But that would also mean that you lose a lot of flexibility and in particular the opt-in functionality ASP.NET Core has where you just pay for what you need.

It would be difficult to have a single setup that attempted to work for everybody: Applications are very different. Some people may want to use SPAs, others don’t. Some use Razor pages, some MVC, and some even both. Some need CORS support, other may not need authorization. And that doesn’t even take all those custom middlewares into account that people may come up with which could be added into literally any place in the middleware pipeline.

Could the documentation be more clear about middleware pipeline ordering? Probably. But should we make it “easier” for people by removing choice and attempting to provide one-fits-all solutions which won’t fit all? Probably not. And we already have templates that attempt to provide the correct middleware ordering for specific scenarios.

[steveoh]

I think a data structure could exist to help with the ordering for most cases. It would help those that don't want to understand how everything works, which are the same people that are not creating custom middleware and yada yada. It would be another way to register middleware so it would not cripple those that want to tweak everything.

It's a bummer that this is the first place a developer has to focus and there are so many very important things happening with a lot of consequence. It is very easy to foul things up and have to learn a lot of details not related to why you started to use asp net core in the first place. The templates are great when you start new, so maybe this is only an upgrade pain...

Like I stated, I know there are reasons not to mess with this and the simple solution is to update the docs like @javiercn requested.

[Rick-Anderson]

@javiercn maybe we could add UseMiddlewareOrderErrorPage warnings for 5.0

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
        app.UseDatabaseErrorPage();
        app.UseMiddlewareOrderErrorPage(); <-- Warn's may not be in right order, fwlink to table
    }
    else
    {
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

    ...

[javiercn]

@Rick-Anderson I believe there's already an analyzer for it.

If you want, file an issue for it and it'll get triaged.

[Rick-Anderson]

PR dotnet/AspNetCore.Docs#16852 address this.

[Rick-Anderson]

Close this issue. Fixed in dotnet/AspNetCore.Docs#16852