詳解ASP.NET Core中間件Middleware

Posted on 2022-01-13 by WalkonNet

本文為官方文檔譯文，官方文檔現已非機器翻譯 https://docs.microsoft.com/zh-cn/aspnet/core/fundamentals/middleware/?view=aspnetcore-2.1

什麼是中間件（Middleware）？

中間件是組裝到應用程序管道中以處理請求和響應的軟件。每個組件：

選擇是否將請求傳遞給管道中的下一個組件。
可以在調用管道中的下一個組件之前和之後執行工作。

請求委托（Request delegates）用於構建請求管道，處理每個HTTP請求。

請求委托使用Run，Map和Use擴展方法進行配置。單獨的請求委托可以以內聯匿名方法（稱為內聯中間件）指定，或者可以在可重用的類中定義它。這些可重用的類和內聯匿名方法是中間件或中間件組件。請求流程中的每個中間件組件都負責調用流水線中的下一個組件，如果適當，則負責鏈接短路。

將HTTP模塊遷移到中間件解釋瞭ASP.NET Core和以前版本（ASP.NET）中的請求管道之間的區別，並提供瞭更多的中間件示例。

使用 IApplicationBuilder 創建中間件管道

ASP.NET Core請求流程由一系列請求委托組成，如下圖所示（執行流程遵循黑色箭頭）：

每個委托可以在下一個委托之前和之後執行操作。委托還可以決定不將請求傳遞給下一個委托，這稱為請求管道的短路。短路通常是可取的，因為它避免瞭不必要的工作。例如，靜態文件中間件可以返回一個靜態文件的請求，並使管道的其餘部分短路。需要在管道早期調用異常處理委托，因此它們可以捕獲後面管道的異常。

最簡單的可能是ASP.NET Core應用程序建立一個請求的委托，處理所有的請求。此案例不包含實際的請求管道。相反，針對每個HTTP請求都調用一個匿名方法。

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;

public class Startup
{
    public void Configure(IApplicationBuilder app)
    {
        app.Run(async context =>
        {
            await context.Response.WriteAsync("Hello, World!");
        });
    }
}

第一個 app.Run 委托終止管道。

有如下代碼：

通過瀏覽器訪問，發現確實在第一個app.Run終止瞭管道。

您可以將多個請求委托與app.Use連接在一起。 next參數表示管道中的下一個委托。（請記住，您可以通過不調用下一個參數來結束流水線。）通常可以在下一個委托之前和之後執行操作，如下例所示：

public class Startup
{
    public void Configure(IApplicationBuilder app)
    {
        app.Use(async (context, next) =>
	        {
				await context.Response.WriteAsync("進入第一個委托 執行下一個委托之前\r\n");
				//調用管道中的下一個委托
		        await next.Invoke();
		        await context.Response.WriteAsync("結束第一個委托 執行下一個委托之後\r\n");
			});
	        app.Run(async context =>
	        {
		        await context.Response.WriteAsync("進入第二個委托\r\n");
				await context.Response.WriteAsync("Hello from 2nd delegate.\r\n");
		        await context.Response.WriteAsync("結束第二個委托\r\n");
			});
    }
}

使用瀏覽器訪問有如下結果：

可以看出請求委托的執行順序是遵循上面的流程圖的。

註意：

響應發送到客戶端後，請勿調用next.Invoke。響應開始之後，對HttpResponse的更改將拋出異常。例如，設置響應頭，狀態代碼等更改將會引發異常。在調用next之後寫入響應體。

可能導致協議違規。例如，寫入超過content-length所述內容長度。
可能會破壞響應內容格式。例如，將HTML頁腳寫入CSS文件。

HttpResponse.HasStarted是一個有用的提示，指示是否已發送響應頭和/或正文已寫入。

順序

在Startup。Configure方法中添加中間件組件的順序定義瞭在請求上調用它們的順序，以及響應的相反順序。此排序對於安全性，性能和功能至關重要。

Startup.Configure方法（如下所示）添加瞭以下中間件組件：

異常/錯誤處理
靜態文件服務
身份認證
MVC

public void Configure(IApplicationBuilder app)
{
    app.UseExceptionHandler("/Home/Error"); // Call first to catch exceptions
                                            								// thrown in the following middleware.

    app.UseStaticFiles();                   // Return static files and end pipeline.

    app.UseAuthentication();               // Authenticate before you access
                                           					// secure resources.

    app.UseMvcWithDefaultRoute();          // Add MVC to the request pipeline.
}

上面的代碼，UseExceptionHandler是添加到管道中的第一個中間件組件，因此它捕獲以後調用中發生的任何異常。

靜態文件中間件在管道中提前調用，因此可以處理請求和短路，而無需通過剩餘的組件。靜態文件中間件不提供授權檢查。由其提供的任何文件，包括wwwroot下的文件都是公開的。

如果請求沒有被靜態文件中間件處理，它將被傳遞給執行身份驗證的Identity中間件（app.UseAuthentication）。身份不會使未經身份驗證的請求發生短路。雖然身份認證請求，但授權（和拒絕）僅在MVC選擇特定的Razor頁面或控制器和操作之後才會發生。

授權（和拒絕）僅在MVC選擇特定的Razor頁面或Controller和Action之後才會發生。

以下示例演示瞭中間件順序，其中靜態文件的請求在響應壓縮中間件之前由靜態文件中間件處理。靜態文件不會按照中間件的順序進行壓縮。來自UseMvcWithDefaultRoute的MVC響應可以被壓縮。

public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles();         // Static files not compressed
    app.UseResponseCompression();
    app.UseMvcWithDefaultRoute();
}

Use, Run, 和 Map

你可以使用Use，Run和Map配置HTTP管道。Use方法可以使管道短路（即，可以不調用下一個請求委托）。Run方法是一個約定，並且一些中間件組件可能暴露在管道末端運行的Run [Middleware]方法。Map*擴展用作分支管道的約定。映射根據給定的請求路徑的匹配來分支請求流水線，如果請求路徑以給定路徑開始，則執行分支。

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

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

    public void Configure(IApplicationBuilder app)
    {
        app.Map("/map1", HandleMapTest1);

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

        app.Run(async context =>
        {
            await context.Response.WriteAsync("Hello from non-Map delegate. <p>");
        });
    }
}

下表顯示瞭使用以前代碼的 http://localhost:19219 的請求和響應：

請求	響應
localhost:1234	Hello from non-Map delegate.
localhost:1234/map1	Map Test 1
localhost:1234/map2	Map Test 2
localhost:1234/map3	Hello from non-Map delegate.

當使用Map時，匹配的路徑段將從HttpRequest.Path中刪除，並為每個請求追加到Http Request.PathBase。

MapWhen根據給定謂詞的結果分支請求流水線。任何類型為Func<HttpContext,bool>的謂詞都可用於將請求映射到管道的新分支。在以下示例中，謂詞用於檢測查詢字符串變量分支的存在：

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

    public void Configure(IApplicationBuilder app)
    {
        app.MapWhen(context => context.Request.Query.ContainsKey("branch"),
                               HandleBranch);

        app.Run(async context =>
        {
            await context.Response.WriteAsync("Hello from non-Map delegate. <p>");
        });
    }
}

以下下表顯示瞭使用上面代碼 http://localhost:19219 的請求和響應：

請求	響應
localhost:1234	Hello from non-Map delegate.
localhost:1234/?branch=1	Branch used = master

Map支持嵌套，例如：

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

Map也可以一次匹配多個片段，例如：

app.Map("/level1/level2", HandleMultiSeg);

內置中間件

ASP.NET Core附帶以下中間件組件：

中間件	描述
Authentication	提供身份驗證支持
CORS	配置跨域資源共享
Response Caching	提供緩存響應支持
Response Compression	提供響應壓縮支持
Routing	定義和約束請求路由
Session	提供用戶會話管理
Static Files	為靜態文件和目錄瀏覽提供服務提供支持
URL Rewriting Middleware	用於重寫 Url，並將請求重定向的支持

編寫中間件

中間件通常封裝在一個類中，並使用擴展方法進行暴露。查看以下中間件，它從查詢字符串設置當前請求的Culture：

public class Startup
{
    public void Configure(IApplicationBuilder app)
    {
        app.Use((context, next) =>
        {
            var cultureQuery = context.Request.Query["culture"];
            if (!string.IsNullOrWhiteSpace(cultureQuery))
            {
                var culture = new CultureInfo(cultureQuery);

                CultureInfo.CurrentCulture = culture;
                CultureInfo.CurrentUICulture = culture;
            }

            // Call the next delegate/middleware in the pipeline
            return next();
        });

        app.Run(async (context) =>
        {
            await context.Response.WriteAsync(
                $"Hello {CultureInfo.CurrentCulture.DisplayName}");
        });

    }
}

您可以通過傳遞Culture來測試中間件，例如 http://localhost:19219/?culture=zh-CN

以下代碼將中間件委托移動到一個類：

using Microsoft.AspNetCore.Http;
using System.Globalization;
using System.Threading.Tasks;

namespace Culture
{
    public class RequestCultureMiddleware
    {
        private readonly RequestDelegate _next;

        public RequestCultureMiddleware(RequestDelegate next)
        {
            _next = next;
        }

        public Task Invoke(HttpContext context)
        {
            var cultureQuery = context.Request.Query["culture"];
            if (!string.IsNullOrWhiteSpace(cultureQuery))
            {
                var culture = new CultureInfo(cultureQuery);

                CultureInfo.CurrentCulture = culture;
                CultureInfo.CurrentUICulture = culture;

            }

            // Call the next delegate/middleware in the pipeline
            return this._next(context);
        }
    }
}

以下通過IApplicationBuilder的擴展方法暴露中間件：

using Microsoft.AspNetCore.Builder;

namespace Culture
{
    public static class RequestCultureMiddlewareExtensions
    {
        public static IApplicationBuilder UseRequestCulture(
            this IApplicationBuilder builder)
        {
            return builder.UseMiddleware<RequestCultureMiddleware>();
        }
    }
}

以下代碼從Configure調用中間件：

public class Startup
{
    public void Configure(IApplicationBuilder app)
    {
        app.UseRequestCulture();

        app.Run(async (context) =>
        {
            await context.Response.WriteAsync(
                $"Hello {CultureInfo.CurrentCulture.DisplayName}");
        });

    }
}

中間件應該遵循顯式依賴原則，通過在其構造函數中暴露其依賴關系。中間件在應用程序生命周期構建一次。如果您需要在請求中與中間件共享服務，請參閱以下請求相關性。

中間件組件可以通過構造方法參數來解析依賴註入的依賴關系。 UseMiddleware也可以直接接受其他參數。

每個請求的依賴關系

因為中間件是在應用程序啟動時構建的，而不是每個請求，所以在每個請求期間，中間件構造函數使用的作用域生命周期服務不會與其他依賴註入類型共享。如果您必須在中間件和其他類型之間共享作用域服務，請將這些服務添加到Invoke方法的簽名中。 Invoke方法可以接受由依賴註入填充的其他參數。例如：

public class MyMiddleware
{
    private readonly RequestDelegate _next;

    public MyMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task Invoke(HttpContext httpContext, IMyScopedService svc)
    {
        svc.MyProperty = 1000;
        await _next(httpContext);
    }
}

到此這篇關於ASP.NET Core中間件Middleware詳解的文章就介紹到這瞭。希望對大傢的學習有所幫助，也希望大傢多多支持WalkonNet。

詳解ASP.NET Core中間件Middleware

什麼是中間件（Middleware）？

使用 IApplicationBuilder 創建中間件管道

順序

Use, Run, 和 Map

內置中間件

編寫中間件

推薦閱讀：

發佈留言取消回覆

近期文章

什麼是中間件（Middleware）？

使用 IApplicationBuilder 創建中間件管道

順序

Use, Run, 和 Map

內置中間件

編寫中間件

推薦閱讀：

發佈留言 取消回覆

近期文章

標籤

發佈留言取消回覆