­

如何創建一個自定義的`ErrorHandlerMiddleware`方法

  • 2020 年 3 月 16 日
  • 筆記

在本文中，我將講解如何通過自定義ExceptionHandlerMiddleware，以便在中間件管道中發生錯誤時創建自定義響應，而不是提供一個「重新執行」管道的路徑。

作者：依樂祝
譯文：https://www.cnblogs.com/yilezhu/p/12497937.html
原文：https://andrewlock.net/creating-a-custom-error-handler-middleware-function/

Razor頁面中的異常處理

所有的.NET應用程式都有可能會產生錯誤，並且不幸地引發異常，因此在ASP.NET中間件管道中處理這些異常顯得非常重要。伺服器端呈現的應用程式（如Razor Pages）通常希望捕獲這些異常並重定向到一個錯誤頁面。

例如，如果您創建一個使用Razor Pages（dotnet new webapp）的新Web應用程式，您將在Startup.Configure中看到如下的中間件配置：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)  {      if (env.IsDevelopment())      {          app.UseDeveloperExceptionPage();      }      else      {          app.UseExceptionHandler("/Error");      }        // .. other middleware not shown  }

在Development環境中運行時，應用程式將捕獲處理請求時引發的所有異常，並使用一個非常有用的DeveloperExceptionMiddleware方法將其以網頁的形式進行顯示：

開發人員例外頁面

這在本地開發期間非常有用，因為它使您可以快速檢查堆棧跟蹤，請求標頭，路由詳細資訊以及其他內容。

當然，這些都是您不想在生產中公開的敏感資訊。因此，當不在開發階段時，我們將使用其他異常處理程式ExceptionHandlerMiddleware。此中間件允許您提供一個請求路徑，默認情況下是"/Error"，並使用它「重新執行」中間件管道，以生成最終響應：

使用以下命令重新執行管道

Razor Pages應用程式的最終結果是，每當生產中發生異常時，就會返回這個Error.cshtml 的Razor 頁面：

生產中的例外頁面

這涵蓋了razor 頁面的異常處理，但是Web API呢？

Web API的異常處理

Web API模板（dotnet new webapi）中的默認異常處理類似於Razor Pages使用的異常處理，但有一個重要的區別：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)  {      if (env.IsDevelopment())      {          app.UseDeveloperExceptionPage();      }        // .. other middleware not shown  }

如您所見DeveloperExceptionMiddleware，在Development環境中仍會添加，但是在生產中根本沒有添加錯誤處理！這沒有聽起來那麼糟糕：即使沒有異常處理中間件，ASP.NET Core也會在其底層架構中捕獲該異常，將其記錄下來，並向客戶端返回一個空白的500響應：

一個例外

如果您正在使用該[ApiController]屬性（你可能應該這樣使用），並且該錯誤來自您的Web API控制器，那麼ProblemDetails默認情況下會得到一個結果，或者您可以進一步對其進行自定義。

對於Web API客戶端來說，這實際上還不錯。您的API使用者應能夠處理錯誤響應，因此最終用戶將不會看到上面的「中斷」頁面。但是，它通常不是那麼簡單。

例如，也許您使用的是錯誤的標準格式，例如ProblemDetails格式。如果您的客戶期望所有錯誤都具有該格式，那麼在某些情況下生成的空響應很可能導致客戶端中斷。同樣，在Development環境中，當客戶端期望返回JSON時而你返回一個HTML開發人員異常頁面，這可能會導致問題！

官方文檔中描述了一種解決方案，建議您創建ErrorController並具有兩個終結點的：

[ApiController]  public class ErrorController : ControllerBase  {      [Route("/error-local-development")]      public IActionResult ErrorLocalDevelopment() => Problem(); // Add extra details here        [Route("/error")]      public IActionResult Error() => Problem();  }

然後使用Razor Pages應用程式中使用的相同「重新執行」功能來生成響應：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)  {      if (env.IsDevelopment())      {          app.UseExceptionHandler("/error-local-development");      }      else      {          app.UseExceptionHandler("/error");      }        // .. other middleware  }

這可以正常工作，但是對於使用生成異常的同一基礎結構（例如Razor Pages或MVC）來生成異常消息，總有一些困擾我。由於被第二次拋出異常，我多次被失敗的錯誤響應所困擾！因此，我喜歡採取稍微不同的方法。

使用ExceptionHandler代替ExceptionHandlingPath

當我第一次開始使用ASP.NET Core時，解決此問題的方法是編寫自己的自定義ExceptionHandler中間件來直接生成響應。「處理異常不是那麼難，對吧」？

事實證明，這要複雜得多（我知道，令人震驚）。您需要處理各種邊緣情況，例如：

  • 如果在發生異常時響應已經開始發送，則您將無法攔截它。
  • 如果在EndpointMiddleware發生異常時已執行，則需要對選定的端點進行一些處理
  • 您不想快取錯誤響應

ExceptionHandlerMiddleware處理所有這些情況，所以重新寫你自己的版本不是一條要走的路。幸運的是，儘管通常顯示的方法是為中間件提供重新執行的路徑，但還有另一種選擇-直接提供處理函數。

在ExceptionHandlerMiddleware中有一個ExceptionHandlerOptions參數。該選項對象具有兩個屬性：

public class ExceptionHandlerOptions  {      public PathString ExceptionHandlingPath { get; set; }      public RequestDelegate ExceptionHandler { get; set; }  }

當你向UseExceptionHandler(path)方法提供重新執行的路徑時，實際上是在options對象上設置ExceptionHandlingPath。同樣的，如果需要的話，您可以設置ExceptionHandler屬性，並使用UseExceptionHandler()將ExceptionHandlerOptions的實例直接傳遞給中間件：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)  {      app.UseExceptionHandler(new ExceptionHandlerOptions      {          ExceptionHandler = // .. to implement      });        // .. othe middleware  }

另外，您可以使用UseExceptionHandler()的另一個重載方法並配置一個迷你中間件管道來生成響應：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)  {      app.UseExceptionHandler(err => err.UseCustomErrors(env)); // .. to implement        // .. othe middleware  }

兩種方法都是等效的，因此更多是關於喜好的問題。在本文中，我將使用第二種方法並實現該UseCustomErrors()功能。

創建自定義異常處理函數

對於此示例，我將假設我們在中間件管道中遇到異常時需要生成一個ProblemDetails的對象。我還要假設我們的API僅支援JSON。這就避免了我們不必擔心XML內容協商等問題。在開發環境中，ProblemDetails響應將包含完整的異常堆棧跟蹤，而在生產環境中，它將僅顯示一般錯誤消息。

ProblemDetails是返回HTTP響應中錯誤的機器可讀詳細資訊的行業標準方法。這是從ASP.NET Core 3.x（在某種程度上在2.2版中）的Web API返回錯誤消息的普遍支援的方法。

我們將從在靜態幫助器類中定義UseCustomErrors函數開始。該幫助類將一個生成響應的中間件添加到IApplicationBuilder方法擴展中。在開發環境中，它最終會調用WriteResponse方法，並且設置includeDetails: true。在其他環境中，includeDetails`設置為false。

using System;  using System.Diagnostics;  using System.Text.Json;  using System.Threading.Tasks;  using Microsoft.AspNetCore.Builder;  using Microsoft.AspNetCore.Diagnostics;  using Microsoft.AspNetCore.Hosting;  using Microsoft.AspNetCore.Http;  using Microsoft.AspNetCore.Mvc;  using Microsoft.Extensions.Hosting;    public static class CustomErrorHandlerHelper  {      public static void UseCustomErrors(this IApplicationBuilder app, IHostEnvironment environment)      {          if (environment.IsDevelopment())          {              app.Use(WriteDevelopmentResponse);          }          else          {              app.Use(WriteProductionResponse);          }      }        private static Task WriteDevelopmentResponse(HttpContext httpContext, Func<Task> next)          => WriteResponse(httpContext, includeDetails: true);        private static Task WriteProductionResponse(HttpContext httpContext, Func<Task> next)          => WriteResponse(httpContext, includeDetails: false);        private static async Task WriteResponse(HttpContext httpContext, bool includeDetails)      {          // .. to implement      }  }

剩下的就是實現WriteResponse方法來生成我們的響應的功能。這將從ExceptionHandlerMiddleware（通過IExceptionHandlerFeature）中檢索異常，並構建一個包含要顯示的詳細資訊的ProblemDetails對象。然後，它使用System.Text.Json序列化程式將對象寫入Response流。

private static async Task WriteResponse(HttpContext httpContext, bool includeDetails)  {      // Try and retrieve the error from the ExceptionHandler middleware      var exceptionDetails = httpContext.Features.Get<IExceptionHandlerFeature>();      var ex = exceptionDetails?.Error;        // Should always exist, but best to be safe!      if (ex != null)      {          // ProblemDetails has it's own content type          httpContext.Response.ContentType = "application/problem+json";            // Get the details to display, depending on whether we want to expose the raw exception          var title = includeDetails ? "An error occured: " + ex.Message : "An error occured";          var details = includeDetails ? ex.ToString() : null;            var problem = new ProblemDetails          {              Status = 500,              Title = title,              Detail = details          };            // This is often very handy information for tracing the specific request          var traceId = Activity.Current?.Id ?? httpContext?.TraceIdentifier;          if (traceId != null)          {              problem.Extensions["traceId"] = traceId;          }            //Serialize the problem details object to the Response as JSON (using System.Text.Json)          var stream = httpContext.Response.Body;          await JsonSerializer.SerializeAsync(stream, problem);      }  }

您可以在序列化ProblemDetails之前記錄從HttpContext中檢索的自己喜歡的任何其他值。

請注意，在調用異常處理程式方法之前，ExceptionHandlerMiddleware會 清除路由值，以使這些值不可用。

如果您的應用程式現在在Development環境中引發異常，則您將在響應中獲取作為JSON返回的完整異常：

開發中的ProblemDetails響應

在生產環境中，您仍然會得到ProblemDetails響應，但是省略了詳細資訊：

生產中的ProblemDetails響應

與MVC /重新執行路徑方法相比，此方法顯然具有一些局限性，即您不容易獲得模型綁定，內容協商，簡單的序列化或本地化（取決於您的方法）。

如果您需要其中任何一個（例如，也許您使用PascalCase而不是camelCase從MVC進行序列化），那麼使用此方法可能比其價值更麻煩。如果是這樣，那麼所描述的Controller方法可能是明智的選擇。

如果您不關心這些，那麼本文中顯示的簡單處理程式方法可能是更好的選擇。無論哪種方式，都不要嘗試實現自己的版本ExceptionHandlerMiddleware-使用可用的擴展點！?

總結

在這篇文章中，我描述了Razor Pages和Web API的默認異常處理中間件方法。我著重指出了默認Web API模板配置的問題，尤其是在客戶端期望有效JSON的情況下，即使出現錯誤也是如此。

然後，我從官方文檔中展示了建議的方法，該方法使用MVC控制器為API 生成ProblemDetails響應。這種方法效果很好，除非問題出在您的MVC配置本身上，否則嘗試執行ErrorController將會失敗。

作為替代方案，我展示了如何使用ExceptionHandlerMiddleware為生成響應提供訂製的異常處理功能。我最後展示了一個示例處理程式，該處理程式將ProblemDetails對象序列化為JSON，包括Development環境中的詳細資訊，並在其他環境中將其排除在外。

VirMach 便宜 VPS

QNews

QNews