difference between Map and MapWhen branch in asp.net core Middleware?

Question

When to use Map and MapWhen branch in asp.net core middleware while we are authenticating request.

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.Map("", (appBuilder) =>
    {
        appBuilder.Run(async (context) => {
            await context.Response.WriteAsync("");
        });
    });

    app.MapWhen(context => context.Request.Query.ContainsKey(""), (appBuilder) =>
    {
        appBuilder.Run(async (context) =>
        {
            await context.Response.WriteAsync("");
        });

    });
}

Argue

Answer 1

Map could branch the request based on match of the specified request path only. MapWhen is more powerful and allows branching the request based on result of specified predicate that operates with current HttpContext object. As far HttpContext contains all information about HTTP request, MapWhen allows you to use very specific conditions for branching request pipeline.

Any Map call could be easily converted to MapWhen, but not vice versa. For example this Map call:

app.Map("SomePathMatch", (appBuilder) =>
{
    appBuilder.Run(async (context) => {

        await context.Response.WriteAsync("");
    });
});

is equivalent to the following MapWhen call:

app.MapWhen(context => context.Request.Path.StartsWithSegments("SomePathMatch"), (appBuilder) =>
{
    appBuilder.Run(async (context) =>
    {
        await context.Response.WriteAsync("");
    });
});

So answering your question "When to use Map and MapWhen branch": use Map when you branch request based on request path only. Use MapWhen when you branch request based on other data from the HTTP request.

Choric

CodeFuller this is not entirely true, see @alex-lorimer 's answer below with an example in my comment. – Alcmene

Answer 2

The accepted answer is helpful, but not entirely accurate. Apart from the predicate logic, key differences between Map and MapWhen are that Map will add MapMiddleware to the pipeline (see here), while MapWhen will add MapWhenMiddleware to the pipeline (see here). The effect of this is that Map will update the Request.Path and Request.PathBase to account for branching based on path (trimming the matched path segment off Request.Path and appending it to Request.PathBase), while a seemingly equivalent MapWhen predicate will not. This affects anything downstream that uses the path, such as routing!

Douma

This should be the accepted answer. This is especially true if the middleware inside the map is expecting the first part of the path. For example, if UseMvc() expects the prefix /api in the route, app.Map("/api", builder => builder.UseMvc()) will not work. Instead it's better to use app.UseWhen(context => context.Request.Path.StartsWithSegments("/api"), ... ); – Alcmene

This answer explains a very important aspect of using .Map( – Kaylyn