ASP.NET Core 中介軟體

中介軟體為組成應用程式管線的軟體，用以處理要求與回應。 每種中介軟體：

• 選擇是否將請求轉交給管線中的下一個中介軟體。
• 可以在管道中下一個中介軟體之前及之後執行工作。

要求委派用於建構請求管線。 請求委派會處理每個 HTTP 要求。

要求委派的設定方式為使用 Run、Map 和 Use 擴充方法。 個別請求代理可以以內嵌方式指定為匿名方法（稱為內嵌中介軟體），或在可重用類別中定義。 這些內嵌匿名方法或可重用類別稱為 中介軟體 或 中介軟體元件。 請求管線中的每個中介軟體負責呼叫下一個中介軟體或短路該管線。 當中介軟體短路時，稱為「終端中介軟體」，因為它會防止接下來的中介軟體處理要求。

欲了解更多關於 ASP.NET Core 與 ASP.NET 4.x 中請求管線及額外中介軟體範例的差異，請參見 「將 HTTP 模組遷移至 ASP.NET Core 中介軟體」。

中介軟體依應用程式類型的角色

伺服器端 Blazor、 Razor Pages 和 MVC 則透過中介軟體處理伺服器上的瀏覽器請求。 本文中的指引適用於這些類型的應用程式。

獨立 Blazor WebAssembly 應用程式會在用戶端上完全執行，且不會使用中間件管線處理要求。 本文中的指引不適用於獨立 Blazor WebAssembly 應用程式。

中介軟體程式碼分析

欲了解更多關於 ASP.NET Core 編譯器平台分析器，用於檢查應用程式程式碼品質，請參閱 ASP.NET Core 應用程式中的程式碼分析。

使用 WebApplication 建立中介軟體管線

ASP.NET Core 要求管線由要求委派序列組成，並會一個接著一個呼叫。 下圖說明此概念。 執行線程按照黑色箭頭的方向執行。

每一個委派皆能在下個委派的前後執行作業。 處理例外狀況的委派應該在管線中較早呼叫，以便能捕捉到管線後續階段中發生的例外狀況。

注意

若要在本地試驗本節的程式碼範例，請使用 ASP.NET Core Empty 專案範本建立一個 ASP.NET Core 應用程式。 若使用 .NET CLI，範本短名稱為 web （dotnet new web）。

最簡單的 ASP.NET Core 應用程式會呼叫 Run，以設置單一終端 middleware，作為匿名函數請求代理來處理沒有請求管線的請求。

在以下範例中：

• 每次請求都會呼叫 RunExtensions.Run 並將「Hello world!」寫入回應中。
• 程式碼區塊結束時的呼叫 WebApplication.Run 會執行應用程式並阻擋呼叫執行緒直到主機關機。

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

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

app.Run();

在瀏覽器中存取該應用程式啟動網址時的回應：

Hello world!

使用 Use 鏈結多個委派請求。 next 參數代表管線中的下個委派。 你通常可以在委派（delegate）之前 next 和之後執行相關行動。

下列範例示範：

• 兩個 Use 呼叫，每個都寫入控制台：
  • 其中可以執行可寫入回應（context.Response， HttpResponse）的工作。
  • 在next參數被呼叫後，可以執行不寫入回應的作業。
• 終端請求委派，呼叫RunExtensions.Run以將"Hello world!"寫入回應。
• 最終的 Use 呼叫，由於跟隨 Run 終端請求代理，所以未被執行。
• 在程式碼區塊的結尾呼叫 WebApplication.Run，以運行應用程式並封鎖呼叫執行緒，直到主機關閉。

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

app.Use(async (context, next) =>
{
    Console.WriteLine("Work that can write to the response. (1)");
    await next.Invoke(context);
    Console.WriteLine("Work that doesn't write to the response. (1)");
});

app.Use(async (context, next) =>
{
    Console.WriteLine("Work that can write to the response. (2)");
    await next.Invoke(context);
    Console.WriteLine("Work that doesn't write to the response. (2)");
});

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

app.Use(async (context, next) =>
{
    Console.WriteLine("This statement isn't reached. (3)");
    await next.Invoke(context);
    Console.WriteLine("This statement isn't reached. (3)");
});

app.Run();

在應用程式執行時的主控台視窗：

能夠寫出回應的作品。 (1)
能夠寫出回應的作品。 (2)
不會寫入回應的工作。 (2)
不會寫入回應的工作。 (1)

中斷請求管線通常是理想的選擇，因為這樣可以避免不必要的處理。 例如，靜態檔案中間件 可以做為 終端中間件，方法是處理靜態檔案的要求，並縮短管線的其餘部分。 在終端中介軟體之前加入管線的中介軟體，仍會在其敘述後處理程式碼。 如果您不計劃調用 next.Invoke ，因為目標是終止管道，請使用 Run 委託 來代替調用 Use 擴展方法。

在回應傳送期間或之後，不要呼叫 next.Invoke 。 啟動HttpResponse後，變更會導致例外狀況。 例如，在回應開始後，設定標頭或回應狀態碼 會導致拋出例外。 致電 next 後寫信給回應機構，可能：

• 造成協定違規，例如寫入比回應內容長度Content-Length （標頭值）更多的位元組。
• 破壞主體格式，例如在 CSS 檔案中寫入 HTML 頁腳。

要判斷反應是否已開始，請檢查 的 HasStarted值。

如需詳細資訊，請參閱路由後的短路中介軟體。

Run 委派

Run代表不會收到next參數。 第一 Run 位代表總是終止該管線。 Run 也是一種慣例，有些中介軟體可能會公開 Run 在管線末端執行的方法。

在第一位Run代表之後的代表UseRun將不會被呼叫。

分支中介軟體管線

Map 擴充功能被用作分支請求處理管線的慣例。 Map 會依據指定要求路徑的相符項目將要求管線分支。 如果要求路徑以指定路徑為開頭，則會執行分支。

以下範例中，對/map1的請求會呼叫HandleMap1，而對/map2的請求會呼叫HandleMap2：

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

app.Map("/map1", HandleMap1);
app.Map("/map2", HandleMap2);

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

app.Run();

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

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

下表顯示使用上述程式碼的請求與回應。

請求	回應
/	Hello from the non-Map delegate.
/map1	Map 1
/map2	Map 2
/map3	Hello from the non-Map delegate.

使用 Map 時，會將相符的路徑線段從 HttpRequest.Path 移除，並附加至每個要求的 HttpRequest.PathBase。

Map 可同時匹配多個片段：

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

app.Map("/map1/segment1", HandleMultipleSegments);

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

app.Run();

private static void HandleMultipleSegments(IApplicationBuilder app)
{
    app.Run(async context =>
    {
        await context.Response.WriteAsync("Processing '/map1/segment1'");
    });
}

下表顯示使用上述程式碼的請求與回應。

請求	回應
/	Hello from the non-Map delegate.
/map1/segment1	Processing '/map1/segment1'

Map 支援巢狀結構：

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

app.Map("/level1", level1App => {
    level1App.Map("/level2a", level2AApp => {
        app.Run(async context =>
        {
            await context.Response.WriteAsync("Processing '/level1/level2a'");
        });
    });
    level1App.Map("/level2b", level2BApp => {
        app.Run(async context =>
        {
            await context.Response.WriteAsync("Processing '/level1/level2b'");
        });
    });
});

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

app.Run();

下表顯示使用上述程式碼的請求與回應。

請求	回應
/	Hello from the non-Map delegate.
/level1/level2a	Processing '/level1/level2a'
/level1/level2b	Processing '/level1/level2b'

MapWhen 會根據指定述詞的結果對請求管線進行分支。 Func<HttpContext, bool> 類型的任何述詞皆可用來將要求對應至管線的新分支。 在以下範例中，使用謂詞來偵測名為「branch」的查詢字串變數的存在：

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

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

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

app.Run();

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

下表顯示使用上述程式碼的請求與回應。

請求	回應
/	Hello from the non-Map delegate.
/?branch=main	Branch used = 'main'

UseWhen 可以根據給定謂詞條件的結果分支請求管線。 與 MapWhen不同，若分支不包含終端機中介軟體，則會重新連接至主管線：

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

app.UseWhen(context => context.Request.Query.ContainsKey("branch"),
    appBuilder => HandleBranchAndRejoin(appBuilder));

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

app.Run();

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.ToString());

        Console.WriteLine("Work that can write to the response.");
        await next.Invoke(context);
        Console.WriteLine("Work that doesn't write to the response.");
    });
}

在前述範例中，對於所有請求都寫下「Hello from the non-Map delegate.」的回應。 如果請求包含名為「」branch的查詢字串變數，其值會在主管線重新加入前被記錄。

中介軟體順序

應用程式檔案中 Program 中介軟體出現的順序，定義了請求中中介軟體被呼叫的順序，回應則是相反的順序。

你可以完全掌控中介軟體的順序，並能為請求處理情境新增自訂中介軟體，請記住中介軟體的順序對安全性、效能和功能都至關重要。

以下範例展示了常見應用場景中的中介軟體排序。 每個中介軟體擴充方法都透過Microsoft.AspNetCore.Builder命名空間WebApplicationBuilder暴露：

1. 例外狀況/錯誤處理
   • 當應用程式在 Development 環境中執行時：
     • 開發人員例外狀況頁面中介軟體 (UseDeveloperExceptionPage) 會回報應用程式執行階段錯誤。
     • 資料庫錯誤頁面中介軟體 (UseDatabaseErrorPage) 會回報資料庫執行階段錯誤。
   • 當應用程式在 Production 環境中執行時：
     • 例外狀況處理中介軟體 (UseExceptionHandler) 會捕捉在下列中介軟體中擲回的例外狀況。
     • HTTP 靜態傳輸安全性通訊協定 (HSTS) 中介軟體 (UseHsts) 會新增 Strict-Transport-Security 標頭。
2. HTTPS 重新導向中介軟體 (UseHttpsRedirection) 會將 HTTP 要求重新導向到 HTTPS。
3. 靜態檔案中介軟體（如有需要）UseStaticFiles 會回傳靜態檔案，並停止進一步的請求處理。
4. Cookie Policy MiddlewareUseCookiePolicy（）使應用程式符合歐盟通用資料保護規範（GDPR）。
5. 路由中介軟體 (UseRouting) 來路由請求。
6. 驗證中介軟體 (UseAuthentication) 會嘗試在允許使用者存取安全資源之前先驗證使用者。
7. 授權中介軟體 (UseAuthorization) 可授權使用者存取安全資源。
8. 防偽造中介軟體（UseAntiforgery）將防偽造中介軟體加入管線 UseAntiforgery ，必須在呼叫到 UseAuthentication 和 UseAuthorization後放置。
9. Session Middleware（Razor 僅限 Pages 和 MVC UseSession）負責建立並維護會話狀態。 如果應用程式使用 session 狀態，請在 Policy 中介軟體之後 Cookie、Pages/MVC 中介軟體之前 Razor 呼叫 Session 中介軟體。
10. 端點路由中介軟體

• MapRazorComponents 將元件端點加入 Razor 請求管線。
• MapRazorPages 將 Pages 端點加入 Razor 請求管線。
• MapControllerRoute 將控制器端點加入請求管線。

典型的中介軟體流程：Blazor Web App

app.UseWebAssemblyDebugging(); // Development environment with client-side rendering
app.UseMigrationsEndPoint(); // Development environment with ASP.NET Core Identity

app.UseExceptionHandler("/Error", createScopeForErrors: true); // Non-Development environment
app.UseHsts(); // Non-Development environment with HTTPS protocol

app.UseStatusCodePagesWithReExecute("/not-found", createScopeForStatusCodePages: true);

app.UseHttpsRedirection(); // With HTTPS protocol

app.UseAntiforgery();

app.MapStaticAssets();

app.MapRazorComponents<App>(); // With additional extension methods for render modes

app.MapAdditionalIdentityEndpoints(); // With ASP.NET Core Identity

app.Run();

典型的 Pages/MVC 中介軟體流程：Razor

app.UseMigrationsEndPoint(); // Development environment with ASP.NET Core Identity

app.UseExceptionHandler("/Error"); // Non-Development environment
app.UseHsts(); // Non-Development environment with HTTPS protocol

app.UseHttpsRedirection(); // With HTTPS protocol

// app.UseCookiePolicy();
app.UseRouting(); // If not called, runs at the beginning of the pipeline by default
// app.UseRateLimiter();
// app.UseRequestLocalization();
// app.UseCors();

// app.UseAuthentication(); // Called internally for ASP.NET Core Identity
app.UseAuthorization();
// app.UseSession();
// app.UseResponseCompression();
// app.UseResponseCaching();

app.MapStaticAssets();

app.MapControllerRoute(...); // For MVC controllers

app.MapRazorPages(); // For Razor Pages pages

app.MapControllers(); // With authentication in a Razor Pages app

app.Run();

在上述程式碼中：

• CORS 中介軟體（UseCors）、認證中介軟體（UseAuthentication）、以及授權中介軟體（UseAuthorization）必須依所示順序出現。
• CORS 中介軟體（UseCors）必須出現在回應快取中介軟體（UseResponseCaching）之前，以便在每個請求（包括快取回應）上新增 CORS 標頭。 欲了解更多資訊，請參閱 尚不清楚 UseCORS 是否必須優先於 UseResponseCaching（dotnet/aspnetcore #23218）。
• 請求在地化中介軟體UseRequestLocalization（）必須出現在任何可能檢查請求文化的中介軟體之前，例如靜態檔案中介軟體（UseStaticFiles）。
• 當使用限速端點專用 API 時，必須在路由中介軟體（UseRateLimiter）之後呼叫速率限制中介軟體（UseRouting）。 例如，若使用該 [EnableRateLimiting] 屬性 ，必須在路由中介軟體後呼叫速率限制中介軟體。 當只呼叫全域限制器時，速率限制中介軟體可以在路由中介軟體之前呼叫。

在某些情況下，中介軟體有不同的排序。 例如，快取與壓縮排序取決於應用程式的規格。 接下來的順序中，透過快取壓縮回應可能會降低 CPU 使用率，但應用程式可能最終會以不同的壓縮演算法（如 Gzip 或 Brotli）快取同一資源的多個版本：

app.UseResponseCaching();
app.UseResponseCompression();

靜態資產通常會在流程早期提供，以便應用程式能短路請求處理來提升效能。

驗證不會直接跳過未經驗證的請求。 雖然認證中介軟體負責驗證請求，但授權是在框架選擇RazorBlazor Web App元件、頁面應用程式中的Razor一個頁面，或控制器與 MVC 應用程式中的動作後才發生的。

如需單頁應用程式的相關資訊，請參閱 React 和 Angular 專案範本的指南。

UseCors 以及 UseStaticFiles 秩序

關於訂購UseCors與 UseStaticFiles的更多資訊，請參見 ASP.NET 核心中的啟用跨來源請求（CORS）。

轉發標頭中介軟體的順序

先執行轉發標頭中介軟體，先於其他中介軟體，以確保依賴轉發標頭資訊的中介軟體能消耗標頭值進行處理。 若要在診斷與錯誤處理中介軟體後執行轉發標頭中介軟體，請參見 轉發標頭中介軟體順序。

內建的中介軟體

最新版本的 ASP.NET Core 內建以下中介軟體。 UI 堆疊欄位表示中介軟體使用的典型 UI 堆疊 [All， Blazor Web App （BWA）、 Razor Pages 與 MVC （RP/MVC）]。 「順序」欄提供關於中介軟體在請求處理管道中的位置的註解，以及在何種情況下中介軟體可能終止請求處理。 當中介軟體終止要求處理管線並防止後續的下游中介軟體處理要求時，我們稱之為「終端中介軟體」。 欲了解更多短路相關資訊，請參閱「建立中WebApplication介軟體管線」章節。

中介軟體	描述	使用者介面堆疊	訂單
防偽	提供反要求偽造支援。	全部	在端點之前進行驗證和授權。
驗證	提供驗證支援。	全部	必須先完成 HttpContext.User。 OAuth 回呼的終端機。
授權	提供授權支援。	全部	緊接在驗證中介軟體之後。
Cookie 政策	追蹤使用者對用於儲存個人資訊的同意，並強制執行 cookie 欄位的最低標準，例如 secure 和 SameSite。	全部	在發出 Cookie 的中介軟體之前。 範例：驗證、工作階段、MVC (TempData)。
CORS	設定跨原始來源資源共用。	全部	在使用 CORS 的中介軟體出現之前。 UseCors 必須在 UseResponseCaching之前。 欲了解更多資訊，請參閱 目前不清楚 UseCORS 是否必須優先於 UseResponseCaching（dotnet/aspnetcore #23218）。
開發人員例外狀況頁面	產生一個頁面，包含僅供 Development 環境使用的錯誤資訊。	全部	中介軟體在產生錯誤之前。 當環境為 Development時，專案範本會自動將此中介軟體註冊為管線中的第一個中介軟體。
診斷	數個不同的中介軟體，可提供開發人員例外狀況頁面、例外狀況處理、狀態字碼頁，以及新應用程式的預設網頁。	全部	在中介軟體產生錯誤之前。 管理例外狀況的終端，或為新應用程式提供預設首頁。
轉送標頭	將設為 Proxy 的標頭轉送到目前要求。	全部	在中介軟體會消耗更新欄位之前。 範例：配置、主機，用戶端 IP、方法。
健康狀態檢查	檢查 ASP.NET Core 應用程式及其相依性的健康狀態，例如檢查資料庫可用性。	全部	如果某個請求符合健康檢查端點，則將終止。
標頭傳播	將 HTTP 標頭從傳入要求傳播至傳出 HTTP 用戶端要求。
全部
HTTP 記錄	記錄 HTTP 要求和回應。	全部	中介軟體管線的開頭。
HTTP 方法覆寫	允許傳入的 POST 要求覆寫方法。	全部	在中介軟體使用更新後的方法之前。
HTTPS 重新導向	將所有 HTTP 要求都重新導向至 HTTPS。	全部	在中介軟體會消耗 URL 之前。
HTTP 嚴格的傳輸安全性 (HSTS)	增強安全性的中介軟體，可新增特殊的回應標頭。	全部	在回覆發送之前，以及在修改請求的中介程式之後。 範例：轉送的標頭、URL 重寫。
MVC	使用 MVC/Razor Pages 處理要求。	RP/MVC	如果請求符合路由，則停止操作。
OWIN	以 OWIN 為基礎的應用程式、伺服器和中介軟體的互操作性。	RP/MVC	如果 OWIN 中介軟體完全處理了請求，則終止。
輸出快取	提供支援以根據設定進行回應快取。	RP/MVC	在需要快取的中介軟體出現之前。 UseRouting 和 UseCors 必須在 UseOutputCache 之前。
回應快取	提供快取回應的支援。 這需要用戶端參與才能運作。 使用輸出快取來完全控制伺服器。	RP/MVC	在需要快取的中介軟體出現之前。 UseCors 必須位於 UseResponseCaching 之前。 回應快取通常對 UI 應用程式（如 Razor Pages）不利，因為瀏覽器通常會設定請求標頭來防止快取。 輸出快取 對 UI 應用程式有益。
要求解壓縮	提供解壓縮要求的支援。	全部	在中介軟體讀取請求主體之前。
回應壓縮	提供壓縮回應的支援。	全部	在需要壓縮的中介軟體出現之前。
要求當地語系化	提供當地語系化支援。	全部	在進行本地化之前，需考慮的敏感中介軟體。 使用 RouteDataRequestCultureProvider 時，必須在路由中介軟體之後出現。
要求逾時	提供設置請求超時的支援，包括全域設定和針對每個端點的設定。	全部	UseRequestTimeouts 必須在 UseExceptionHandler、UseDeveloperExceptionPage 和 UseRouting 後面。
端點路由。	定義並限制要求路由。	全部	比對路由的終端機。
礦泉	從中介軟體鏈中此點開始，透過回傳單頁應用程式（SPA）的預設頁面來處理所有請求。	全部	它出現在管線的較晚階段，因此其他用於托管靜態檔案的中介軟體，如 MVC 動作，會優先執行。
會話	提供管理使用者工作階段的支援。	RP/MVC	在需要 Session 的中介軟體出現之前。
靜態檔案	支援靜態檔案的提供和目錄瀏覽。	全部	如果請求符合檔案，則終止處理。
URL 重寫	提供重寫 URL 及重新導向要求的支援。	全部	在中介軟體會消耗 URL 之前。
W3C 日誌記錄	以 W3C 擴充記錄檔格式產生伺服器存取記錄。	全部	中介軟體管線的開頭。
Blazor WebAssembly 除錯	在 Chromium 開發工具中進行除錯，針對採用客戶端渲染（CSR）的 Blazor Web App。	BWA	中介軟體管線的開頭。
WebSocket	啟用 WebSockets 通訊協定。	全部	在中介軟體必須接受 WebSocket 請求之前。

其他資源

• 終身與註冊選項（包含中介軟體範例）
• 撰寫自訂的 ASP.NET Core 中介軟體
• 測試 ASP.NET Core 中介軟體
• 在 ASP.NET Core 中設定 gRPC-Web
• 將 HTTP 模組遷移至 ASP.NET Core 中間件
• ASP.NET Core 中的應用程式啟動
• ASP.NET Core 中的要求功能
• ASP.NET Core 的 Factory 中介軟體啟用
• 在 ASP.NET Core 中以協力廠商容器啟用中介軟體