ASP.NET Core自定義中間件的方式

ASP.NET Core應用本質上，其實就是由若幹個中間件構建成的請求處理管道。管道相當於一個故事的框架，而中間件就相當於故事中的某些情節。同一個故事框架採用不同的情節拼湊，最終會體現出不同風格的故事。而我們的ASP.NET Core應用也正是如此，同一管道採用不同的中間件組合，最終也會呈現出不同的 ...

ASP.NET Core應用本質上，其實就是由若幹個中間件構建成的請求處理管道。管道相當於一個故事的框架，而中間件就相當於故事中的某些情節。同一個故事框架採用不同的情節拼湊，最終會體現出不同風格的故事。而我們的ASP.NET Core應用也正是如此，同一管道採用不同的中間件組合，最終也會呈現出不同的應用形態。

從上述的概念種可以看出，中間件在ASP.NET Core應用有著舉足輕重的地位。雖然ASP.NET Core為我們提供了一組豐富的內置中間件，但有些時候我們可能會需要自定義一些中間件，將其穿插到管道中，以便滿足我們特定業務場景的需求，所以本文將介紹3種方式來滿足自定義中間件的需求。

1.委托形式

在應用程式代碼中，我們可以從用於註冊中間件的Use方法中看出，所謂管道中的中間件其實就是一種委托類型的對象，這個具體的委托對象體現為“Fun<RequestDelegate,RequestDelegate>”。

從Fun<RequestDelegate,RequestDelegate>委托的定義可以看出，該委托類型的入參和返回值都是一個RequestDelegate委托類型的對象。RequestDelegate委托類型其實就是管道在代碼中的體現形式，該委托類型承載很多關於請求響應的重要信息，定義如下：

public delegate Task RequestDelegate(HttpContext context);

Fun<RequestDelegate,RequestDelegate>委托中，入參的RequestDelegate對象表示由上一個中間件構建的管道，返回值的RequestDelegate對象表示：將當前中間件基於上一個管道處理後生成的新管道。由於中間件體現為一個Fun<RequestDelegate,RequestDelegate>委托對象，那麼這就代表我們可以定義一個與該委托具有一致聲明的方法作為自定義中間件的方式。具體的代碼實現方式如下：

 1 //創建應用
 2 var app = WebApplication.Create(args);
 3 
 4 //轉換獲得應用建造者
 5 IApplicationBuilder appBuilder = app;
 6 
 7 //註冊自定義的中間件
 8 appBuilder.Use(SayHi);
 9 
10 //運行應用
11 app.Run();
12 
13 //定義為Fun<RequestDelegate,RequestDelegate>類型的方法
14 static RequestDelegate SayHi(RequestDelegate  request)
15     => httpContext => httpContext.Response.WriteAsync("Hello");

上面的代碼是在一個原始的控制台程式中編寫的，並且自行進行了主機應用的構建。在代碼中定義了一個和Fun<RequestDelegate,RequestDelegate>委托簽名一致的SayHi方法，並以此方法作為中間件進行了引用。雖然這是一個可行的方式，但在實際開發的工作場景中，其實很少會使用委托形式作為自定義中間件的方式。在此處之所以演示這種形式，主要是為了錶面中間件本質是一個委托，並且不管通過什麼形式去定義中間件，它最終都會體現為一個Fun<RequestDelegate,RequestDelegate>委托對象。

2.強類型中間件

在實際的開發過程中，基本上都會將自定義的中間件定義為一個具體類型，而對於使用強類型的中間件而言，則我們定義的中間件類型必須實現IMiddleware介面。既然通過一個具體類型來定義中間件，類型在使用上則勢必會與其他類型產生依賴關聯性，那麼對於中間件類型中依賴服務的實例化，框架則要求我們使用依賴註入的方式。接下來我們將通過代碼示例演示如何定義一個強類型的中間件。

2.1.定義中間件的依賴

下麵代碼定義的類型是我們預先為中間件類型定義的依賴項，ISeasonTips介面類型的作用主要是，根據不同月份獲取對應的季節，並輸出對應季節的註意事項，其中SeasonTips類型是介面的預設實現。

    public interface ISeasonTips
    {
        string Prompt(DateTimeOffset time);
    }

    public class SeasonTips : ISeasonTips
    {
        //根據不同月份提示季節註意事項
        public string Prompt(DateTimeOffset time) => time.Month switch
        {
            var h when h >= 3 && h <= 5 => "春天到了，早晚溫差比較大，要註意別感冒。",
            var h when h >= 6 && h <= 8 => "夏天到了，天氣炎熱，要註意別防嗮。",
            var h when h >= 9 && h <= 11 => "秋天到了，天氣乾燥，要註意多喝水。",
            _ => "冬天到了，天氣寒冷，要註意防寒保暖。"

        }; //END Prompt()  

    }

2.2.定義中間件類型

下麵的代碼中，我們定義了一個名為SeasonMiddleware的中間件類型，並實現IMiddleware介面。該中間件的處理請求的邏輯在InvokeAsync方法中，該方法調用其依賴類型的Prompt方法，根據當前時間獲取當前季節的註意事項進行輸出。在該調用該方法後，我們還對InvokeAsync的另一個參數：“RequestDelegate類型的委托對象”進行了調用，以便執行管道中的下一個中間件。另外，對於中間件依賴的類型ISeasonTips，我們將其定義在構造函數的參數列表上，以便依賴註入容器提供相應的實例。

 1    /// <summary>
 2     /// 強類型中間件
 3     /// </summary>
 4     public class SeasonMiddleware : IMiddleware
 5     {
 6         //依賴類型，通過構造函數進行依賴註入
 7         private readonly ISeasonTips _seasonTips;
 8         public SeasonMiddleware(ISeasonTips seasonTips)
 9         {
10             _seasonTips = seasonTips;
11         }
12 
13         //調用依賴的“季節提示類型”，根據當前時間獲取當前季節的註意事項，併進行響應輸出
14         public async Task InvokeAsync(HttpContext context, RequestDelegate next)
15         {
16             await context.Response.WriteAsync(_seasonTips.Prompt(DateTimeOffset.Now));
17 
18             //調用管道中的下一個中間件
19             await next(context);
20         }  // END InvokeAsync()
21 
22     }  // END Class

2.3.應用中間件

在下麵的代碼中我們對自定義的“強類型中間件”進行了應用。由於“強類型中間件”的實例以及依賴都是由依賴註入容器提供的，所以不僅要對依賴的服務進行註冊，還要對自身的中間件類型進行服務註冊。在服務註冊之後，我們使用WebApplication對象的UseMiddleware<SeasonMiddleware>擴展方法，將該中間件添加到應用程式的請求管道中。由於在該中間件後沒有其他中間件的處理，所以我們通過調用Run擴展方法註冊了管道末端的中間件，以便結束當前請求，將響應輸出到客戶端。

 1 using dotNet6Demo;
 2 
 3 //創建“應用建造者”
 4 var builder = WebApplication.CreateBuilder(args);
 5 
 6 //服務註冊
 7 builder.Services.AddSingleton<ISeasonTips, SeasonTips>().AddSingleton<SeasonMiddleware>();   
 8 
 9 //構建應用
10 var app = builder.Build();
11  
12 //引用強類型中間件
13 app.UseMiddleware<SeasonMiddleware>();
14 
15 //末端的中間件
16 app.Run(async (context) =>
17 {
18     await context.Response.WriteAsync("請求結束");
19 });
20 
21 //運行應用
22 app.Run();

到目前為止，結合本示例以上的3個步驟，啟動運行程式就可以驗證自定義強類型中間件的效果了。

3.基於約定的中間件

對於ASP.NET的開發者而言，基於約定的編程模式應該不會陌生。例如在ASP.NET MVC框架中，“Action”預設查找視圖就有一種基於約定的規則，即“Action”首先會在Views目錄中查找與當前“Controller”同名的目錄，然後在該目錄中查找與“Action”同名的視圖文件。這種基於約定的設計方式，在自定義中間件領域也同樣使用到了，即基於約定的中間件。

3.1.約定規則

基於約定的中間件它不必像強類型中間件那樣，必須實現IMiddleware介面或繼承某些基類，它只用按照框架約定的方式定義中間件類型即可，具體的約定規則如下：

中間件類型必須要定義為一個公共的、可供外界實例化的類型，靜態類型無效；
構造函數的參數中必須包含RequestDelegate類型，如果存在依賴類型則也必須包含在構造函數中；
必須定義InvokeAsync或Invoke方法，方法簽名為：public Task Invoke(HttpContext context);

對以上的約定進行一個補充說明：構造函數的參數列表要包含依賴的類型，是為了依賴註入容器對依賴類型提供實例；RequestDelegate參數具有傳遞性，表示由後續中間件構建的管道，當前中間件利用它將請求轉交給後續管道進行處理。InvokeAsync或Invoke方法主要是代表中間件在管道中處理請求的邏輯。

3.2.應用實現

下麵我們在“強類型中間件”示例的基礎上，根據約定規則將SeasonMiddleware類型改造為“基於約定的中間件”，代碼如下：

 1     /// <summary>
 2     /// 基於約定的中間件
 3     /// </summary>
 4     public class SeasonMiddleware
 5     {
 6         private readonly ISeasonTips _seasonTips;
 7         private readonly RequestDelegate _next;
 8 
 9         public SeasonMiddleware(ISeasonTips seasonTips, RequestDelegate next)
10         {
11             _seasonTips = seasonTips;
12             _next = next;
13         }
14 
15         //調用依賴的“季節提示類型”，根據當前時間獲取當前季節的註意事項，併進行響應輸出
16         public async Task InvokeAsync(HttpContext context)
17         {
18             await context.Response.WriteAsync(_seasonTips.Prompt(DateTimeOffset.Now));
19             //調用管道中的下一個中間件
20             await _next(context);
21 
22         }  // END InvokeAsync()
23 
24     }  // END Class

在中間件引用方面，“基於約定的中間件”同樣可以使用“app.UseMiddleware<SeasonMiddleware>()”的方式進行引用，但是在此我們介紹一種較為常用的方式，就是將自定義中間件的引用方式進行封裝，將其作為IApplicationBuilder類型的擴展方法來使用，擴展方法定義的代碼如下：

1     public static class SeasonMiddlewareExtensions
2     {
3         public static IApplicationBuilder UseSeason(this IApplicationBuilder builder)
4         {
5             return builder.UseMiddleware<SeasonMiddleware>();
6         }
7     }

接下來在示例應用方面，將其調整為使用“基於約定中間件”的形式，並使用擴展方法引用中間件。

 1 using dotNet6Demo;
 2 
 3 //創建“應用建造者”
 4 var builder = WebApplication.CreateBuilder(args);
 5 
 6 //服務註冊
 7 builder.Services.AddSingleton<ISeasonTips, SeasonTips>();   
 8 
 9 //構建應用
10 var app = builder.Build();
11 
12 //通過自定義擴展方法 引用中間件
13 app.UseSeason();
14 
15 //末端的中間件
16 app.Run(async (context) =>
17 {
18     await context.Response.WriteAsync("請求結束");
19 });
20 
21 //運行應用
22 app.Run();

3.3.提供方式

在對以上中間件應用方面，我們能可以看出“基於約定的中間件”類型並沒有進行服務註冊，而“強類型中間件”類型卻進行了服務註冊，這是因為兩者在提供實例的方式上有著本質的區別。

“基於約定的中間件”的實例是在應用啟動時便可提供的，並且只能指定的一個固定的生命周期模式“Singleton”，所以該類型中間件具有和應用程式一樣的生存期，直到應用程式關閉才會釋放。

“強類型中間件”的實例並不是在應用啟動時提供的，它需要根據服務註冊時指定的生命周期，來決定創建提供的時機。例如“強類型中間件”註冊的生命周期為“Scoped”，那麼依賴註入容器會根據客戶端的請求實時創建中間件的實例，請求處理完成後才會被釋放。

總結

中間件的使用地位在ASP.NET Core中絕對是毋庸置疑的，那麼對於較為複雜的項目而言，自定義中間件的需求絕對是“繞不開的彎”，所以我們必須掌握自定義中間件的方式。

本文介紹了3種可以實現自定義ASP.NET Core中間件的方式。其中第一種並不推崇作為實戰運用的手段，其目的是為了讓我們明白：中間件最終的體現形式其實就是一個委托對象，該委托對象承載了請求上下信息，並具有傳遞性。在實際的使用中，我們可以在第二種和第三種中進行選擇，也就是“強類型中間件”和“基於約定的中間件”，從兩者的特點上來看，“基於約定的中間件”在使用方面會更加的方便，但是其生命周期模式只能局限於Singleton。而“強類型中間件”可以通過服務註冊為中間件實例指定任意的生命周期模式，相比更加靈活。

對於具體的選擇，我們想我們還是交給我們實際的運用場景。

如果想瞭解更多關於自定義 ASP.NET Core 中間件的方式，可以訪問如下的官方文檔：

寫入自定義 ASP.NET Core 中間件 | Microsoft Docs

知識改變命運