ASP.NET Core自定義中介軟體的方式詳解

2022-08-20 14:01:27

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>委託物件，那麼這就代表我們可以定義一個與該委託具有一致宣告的方法作為自定義中介軟體的方式。具體的程式碼實現方式如下：

//建立應用
var app = WebApplication.Create(args);

//轉換獲得應用建造者
IApplicationBuilder appBuilder = app;

//註冊自定義的中介軟體
appBuilder.Use(SayHi);

//執行應用
app.Run();

//定義為Fun<RequestDelegate,RequestDelegate>型別的方法
static RequestDelegate SayHi(RequestDelegate  request)
    => 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，我們將其定義在建構函式的參數列上，以便依賴注入容器提供相應的範例。

/// <summary>
    /// 強型別中介軟體
    /// </summary>
    public class SeasonMiddleware : IMiddleware
    {
        //依賴型別，通過建構函式進行依賴注入
        private readonly ISeasonTips _seasonTips;
        public SeasonMiddleware(ISeasonTips seasonTips)
        {
            _seasonTips = seasonTips;
        }

        //呼叫依賴的「季節提示型別」，根據當前時間獲取當前季節的注意事項，並進行響應輸出
        public async Task InvokeAsync(HttpContext context, RequestDelegate next)
        {
            await context.Response.WriteAsync(_seasonTips.Prompt(DateTimeOffset.Now));

            //呼叫管道中的下一個中介軟體
            await next(context);
        }  // END InvokeAsync()

    }  // END Class

在下面的程式碼中我們對自定義的“強型別中介軟體”進行了應用。由於“強型別中介軟體”的範例以及依賴都是由依賴注入容器提供的，所以不僅要對依賴的服務進行註冊，還要對自身的中介軟體型別進行服務註冊。在服務註冊之後，我們使用WebApplication物件的UseMiddleware<SeasonMiddleware>擴充套件方法，將該中介軟體新增到應用程式的請求管道中。由於在該中介軟體後沒有其他中介軟體的處理，所以我們通過呼叫Run擴充套件方法註冊了管道末端的中介軟體，以便結束當前請求，將響應輸出到使用者端。

using dotNet6Demo;

//建立「應用建造者」
var builder = WebApplication.CreateBuilder(args);

//服務註冊
builder.Services.AddSingleton<ISeasonTips, SeasonTips>().AddSingleton<SeasonMiddleware>();

//構建應用
var app = builder.Build();

//參照強型別中介軟體
app.UseMiddleware<SeasonMiddleware>();

//末端的中介軟體
app.Run(async (context) =>
{
    await context.Response.WriteAsync("請求結束");
});

//執行應用
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型別改造為“基於約定的中介軟體”，程式碼如下：

/// <summary>
    /// 基於約定的中介軟體
    /// </summary>
    public class SeasonMiddleware
    {
        private readonly ISeasonTips _seasonTips;
        private readonly RequestDelegate _next;

        public SeasonMiddleware(ISeasonTips seasonTips, RequestDelegate next)
        {
            _seasonTips = seasonTips;
            _next = next;
        }

        //呼叫依賴的「季節提示型別」，根據當前時間獲取當前季節的注意事項，並進行響應輸出
        public async Task InvokeAsync(HttpContext context)
        {
            await context.Response.WriteAsync(_seasonTips.Prompt(DateTimeOffset.Now));
            //呼叫管道中的下一個中介軟體
            await _next(context);

        }  // END InvokeAsync()

    }  // END Class

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

public static class SeasonMiddlewareExtensions
    {
        public static IApplicationBuilder UseSeason(this IApplicationBuilder builder)
        {
            return builder.UseMiddleware<SeasonMiddleware>();
        }
    }

接下來在範例應用方面，將其調整為使用“基於約定中介軟體”的形式，並使用擴充套件方法參照中介軟體。

using dotNet6Demo;

//建立「應用建造者」
var builder = WebApplication.CreateBuilder(args);

//服務註冊
builder.Services.AddSingleton<ISeasonTips, SeasonTips>();

//構建應用
var app = builder.Build();

//通過自定義擴充套件方法 參照中介軟體
app.UseSeason();

//末端的中介軟體
app.Run(async (context) =>
{
    await context.Response.WriteAsync("請求結束");
});

//執行應用
app.Run();

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

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

“強型別中介軟體”的範例並不是在應用啟動時提供的，它需要根據服務註冊時指定的生命週期，來決定建立提供的時機。例如“強型別中介軟體”註冊的生命週期為“Scoped”，那麼依賴注入容器會根據使用者端的請求實時建立中介軟體的範例，請求處理完成後才會被釋放。

總結

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

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

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

如果想了解更多關於自定義 ASP.NET Core 中介軟體的方式，可以存取如下的官方檔案：

寫入自定義 ASP.NET Core 中介軟體 | Microsoft Docs

到此這篇關於ASP.NET Core自定義中介軟體的方式的文章就介紹到這了,更多相關ASP.NET Core自定義中介軟體內容請搜尋it145.com以前的文章或繼續瀏覽下面的相關文章希望大家以後多多支援it145.com！