netcore Map/Run/Use 的区别

Map和MapWhen

Map 扩展用作约定来创建管道分支。 Map 基于给定请求路径的匹配项来创建请求管道分支。 如果请求路径以给定路径开头，则执行分支。

var app = builder.Build();

app.Map("/map1", HandleMapTest1);

app.Map("/map2", HandleMapTest2);



static void HandleMapTest1(IApplicationBuilder app)
{
    app.Run(async context =>
    {
        await context.Response.WriteAsync("Map Test 1");
    });
}

static void HandleMapTest2(IApplicationBuilder app)
{
    app.Run(async context =>
    {
        await context.Response.WriteAsync("Map Test 2");
    });
}

使用 Map 时，将从 HttpRequest.Path 中删除匹配的路径段，并针对每个请求将该路径段追加到 HttpRequest.PathBase。

Map 支持嵌套，例如：

app.Map("/level1", level1App => {
    level1App.Map("/level2a", level2AApp => {
        // "/level1/level2a" processing
    });
    level1App.Map("/level2b", level2BApp => {
        // "/level1/level2b" processing
    });
});

此外，Map 还可同时匹配多个段：

var app = builder.Build();

app.Map("/map1/seg1", HandleMultiSeg);

MapWhen 基于给定谓词的结果创建请求管道分支。 Func<HttpContext, bool> 类型的任何谓词均可用于将请求映射到管道的新分支。 在以下示例中，谓词用于检测查询字符串变量 branch 是否存在：

var app = builder.Build();

app.MapWhen(context => context.Request.Query.ContainsKey("branch"), HandleBranch);


static void HandleBranch(IApplicationBuilder app)
{
    app.Run(async context =>
    {
        var branchVer = context.Request.Query["branch"];
        await context.Response.WriteAsync($"Branch used = {branchVer}");
    });
}

               //app.MapWhen(context => context.Request.Path.StartsWithSegments("/admin"), appBuilder =>
               //{
               //    appBuilder.Run(async (context) =>
               //    {
               //        context.Response.StatusCode = StatusCodes.Status404NotFound;
               //        await context.Response.WriteAsync("");
               //    });
               //});

UseWhen 也基于给定谓词的结果创建请求管道分支。 与 MapWhen 不同的是，如果这个分支不发生短路或包含终端中间件，则会重新加入主管道：

var app = builder.Build();

app.UseWhen(context => context.Request.Query.ContainsKey("branch"),
    appBuilder => HandleBranchAndRejoin(appBuilder));
    
    
void HandleBranchAndRejoin(IApplicationBuilder app)
{
    var logger = app.ApplicationServices.GetRequiredService<ILogger<Program>>(); 

    app.Use(async (context, next) =>
    {
        var branchVer = context.Request.Query["branch"];
        logger.LogInformation("Branch used = {branchVer}", branchVer);

        // Do work that doesn't write to the Response.
        await next();
        // Do other work that doesn't write to the Response.
    });
}

在前面的示例中，为所有请求写入 Hello from non-Map delegate. 响应。 如果请求中包含查询字符串变量 branch，则在重新加入主管道之前会记录其值。

Use

使用 RunMap 和 Use 扩展方法来配置请求委托。 可将一个单独的请求委托并行指定为匿名方法（称为并行中间件），或在可重用的类中对其进行定义。 这些可重用的类和并行匿名方法即为中间件，也叫中间件组件。 请求管道中的每个中间件组件负责调用管道中的下一个组件，或使管道短路。 当中间件短路时，它被称为“终端中间件”，因为它阻止中间件进一步处理请求。

ASP.NET Core 请求管道包含一系列请求委托，依次调用。 下图演示了这一概念。 沿黑色箭头执行。

每个委托均可在下一个委托前后执行操作。 应尽早在管道中调用异常处理委托，这样它们就能捕获在管道的后期阶段发生的异常。

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.Run(async context =>
{
    await context.Response.WriteAsync("Hello world!");
});

app.Run();

用 Use 将多个请求委托链接在一起。 next 参数表示管道中的下一个委托。 可通过不调用 参数使管道短路。 通常可在 next 委托前后执行操作，如以下示例所示：

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.Use(async (context, next) =>
{
    // Do work that doesn't write to the Response.
    await next.Invoke();
    // Do logging or other work that doesn't write to the Response.
});

app.Run(async context =>
{
    await context.Response.WriteAsync("Hello from 2nd delegate.");
});

app.Run();

当委托不将请求传递给下一个委托时，它被称为“让请求管道短路”。 通常需要短路，因为这样可以避免不必要的工作。 例如，静态文件中间件可以处理对静态文件的请求，并让管道的其余部分短路，从而起到终端中间件的作用。 如果中间件添加到管道中，且位于终止进一步处理的中间件前，它们仍处理 next.Invoke 语句后面的代码。 不过，请参阅下面有关尝试对已发送的响应执行写入操作的警告。

警告

在向客户端发送响应后，请勿调用 next.Invoke。 响应启动后，针对 HttpResponse 的更改将引发异常。 例如，设置标头和状态代码更改将引发异常。 调用 next 后写入响应正文：

• 可能导致违反协议。 例如，写入的长度超过规定的 Content-Length。
• 可能损坏正文格式。 例如，向 CSS 文件中写入 HTML 页脚。

HasStarted 是一个有用的提示，指示是否已发送标头或已写入正文。

Run

Run 委托不会收到 next 参数。 第一个 Run 委托始终为终端，用于终止管道。 Run 是一种约定。 某些中间件组件可能会公开在管道末尾运行的 Run[Middleware] 方法：

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.Use(async (context, next) =>
{
    // Do work that doesn't write to the Response.
    await next.Invoke();
    // Do logging or other work that doesn't write to the Response.
});



                app.Use(async (context, next) =>
                {
                    await context.Response.WriteAsync("First  Start<br/>");
                    //调用下一个中间件
                    await next.Invoke();
                    await context.Response.WriteAsync("First End<br/>");
                });



app.Run(async context =>
{
    await context.Response.WriteAsync("Hello from 2nd delegate.");
});

app.Run();

在前面的示例中，Run 委托将 "Hello from 2nd delegate." 写入响应，然后终止管道。 如果在 Run 委托之后添加了另一个 Use 或 Run 委托，则不会调用该委托。