如何建立一個自定義的`ErrorHandlerMiddleware`方法
阿新 • • 發佈:2020-03-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`中看到如下的中介軟體配置:
```csharp
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Error");
}
// .. other middleware not shown
}
```
在`Development`環境中執行時,應用程式將捕獲處理請求時引發的所有異常,並使用一個非常有用的`DeveloperExceptionMiddleware`方法將其以網頁的形式進行顯示:
![開發人員例外頁面](https://img2018.cnblogs.com/blog/1377250/202003/1377250-20200315154017012-868453515.png)
這在本地開發期間非常有用,因為它使您可以快速檢查堆疊跟蹤,請求標頭,路由詳細資訊以及其他內容。
當然,這些都是您不想在生產中公開的敏感資訊。因此,當不在開發階段時,我們將使用其他異常處理程式`ExceptionHandlerMiddleware`。此中介軟體允許您提供一個請求路徑,預設情況下是`"/Error"`,並使用它“重新執行”中介軟體管道,以生成最終響應:
![使用以下命令重新執行管道 ](https://img2018.cnblogs.com/blog/1377250/202003/1377250-20200315154016727-1816582208.png)
Razor Pages應用程式的最終結果是,每當生產中發生異常時,就會返回這個*Error.cshtml* 的Razor 頁面:
![生產中的例外頁面](https://img2018.cnblogs.com/blog/1377250/202003/1377250-20200315154016480-1304527591.png)
這涵蓋了razor 頁面的異常處理,但是Web API呢?
## Web API的異常處理
Web API模板(`dotnet new webapi`)中的預設異常處理類似於Razor Pages使用的異常處理,但有一個重要的區別:
```csharp
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
// .. other middleware not shown
}
```
如您所見`DeveloperExceptionMiddleware`,在`Development`環境中仍會新增,但是在生產中根本沒有新增錯誤處理!這沒有聽起來那麼糟糕:即使沒有異常處理中介軟體,ASP.NET Core也會在其底層架構中捕獲該異常,將其記錄下來,並向客戶端返回一個空白的`500`響應:
![一個例外](https://img2018.cnblogs.com/blog/1377250/202003/1377250-20200315154016245-827862740.png)
如果您正在使用該`[ApiController]`屬性(你可能應該這樣使用),並且該錯誤來自您的Web API控制器,那麼`ProblemDetails`預設情況下會得到一個結果,或者您可以進一步對其進行自定義。
對於Web API客戶端來說,這實際上還不錯。您的API使用者應能夠處理錯誤響應,因此終端使用者將不會看到上面的“中斷”頁面。但是,它通常不是那麼簡單。
例如,也許您使用的是錯誤的標準格式,例如[ProblemDetails](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.mvc.problemdetails)格式。如果您的客戶期望所有錯誤都具有該格式,那麼在某些情況下生成的空響應很可能導致客戶端中斷。同樣,在`Development`環境中,當客戶端期望返回JSON時而你返回一個HTML開發人員異常頁面,這可能會導致問題!
[官方文件中](https://docs.microsoft.com/en-us/aspnet/core/web-api/handle-errors?view=aspnetcore-3.1#exception-handler)描述了一種解決方案,建議您建立`ErrorController`並具有兩個終結點的:
```csharp
[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應用程式中使用的相同“重新執行”功能來生成響應:
```csharp
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`處理所有這些情況](https://github.com/dotnet/aspnetcore/blob/6255c1ed960f5277d2e96ac2d0968c2c7e844ce2/src/Middleware/Diagnostics/src/ExceptionHandler/ExceptionHandlerMiddleware.cs),所以重新寫你自己的版本不是一條要走的路。幸運的是,儘管通常顯示的方法是為中介軟體提供重新執行的路徑,但還有另一種選擇-直接提供處理函式。
在`ExceptionHandlerMiddleware`中有一個`ExceptionHandlerOptions`引數。[該選項物件具有兩個屬性](https://github.com/dotnet/aspnetcore/blob/6255c1ed960f5277d2e96ac2d0968c2c7e844ce2/src/Middleware/Diagnostics/src/ExceptionHandler/ExceptionHandlerOptions.cs):
```csharp
public class ExceptionHandlerOptions
{
public PathString ExceptionHandlingPath { get; set; }
public RequestDelegate ExceptionHandler { get; set; }
}
```
當你向`UseExceptionHandler(path)`方法提供重新執行的路徑時,實際上是在options物件上設定`ExceptionHandlingPath`。同樣的,如果需要的話,您可以設定`ExceptionHandler`屬性,並使用`UseExceptionHandler()`將`ExceptionHandlerOptions`的例項直接傳遞給中介軟體:
```csharp
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
app.UseExceptionHandler(new ExceptionHandlerOptions
{
ExceptionHandler = // .. to implement
});
// .. othe middleware
}
```
另外,您可以使用`UseExceptionHandler()`的另一個過載方法並配置一個迷你中介軟體管道來生成響應:
```csharp
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響應中錯誤的機器可讀詳細資訊[的行業標準](https://tools.ietf.org/html/rfc7807)方法。這是從ASP.NET Core 3.x(在某種程度上在2.2版中)的Web API返回錯誤訊息的普遍支援的方法。
我們將從在靜態幫助器類中定義`UseCustomErrors`函式開始。該幫助類將一個生成響應的中介軟體新增到`IApplicationBuilder`方法擴充套件中。在開發環境中,它最終會呼叫`WriteResponse`方法,並且設定includeDetails: true`。在其他環境中,`includeDetails`設定為false。
```csharp
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 next)
=> WriteResponse(httpContext, includeDetails: true);
private static Task WriteProductionResponse(HttpContext httpContext, Func next)
=> WriteResponse(httpContext, includeDetails: false);
private static async Task WriteResponse(HttpContext httpContext, bool includeDetails)
{
// .. to implement
}
}
```
剩下的就是實現`WriteResponse`方法來生成我們的響應的功能。這將從`ExceptionHandlerMiddleware`(通過`IExceptionHandlerFeature`)中檢索異常,並構建一個包含要顯示的詳細資訊的`ProblemDetails`物件。然後,它使用`System.Text.Json`序列化程式將物件寫入Response流。
```csharp
private static async Task WriteResponse(HttpContext httpContext, bool includeDetails)
{
// Try and retrieve the error from the ExceptionHandler middleware
var exceptionDetails = httpContext.Features.Get();
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`會 [清除路由值](https://github.com/dotnet/aspnetcore/blob/6255c1ed960f5277d2e96ac2d0968c2c7e844ce2/src/Middleware/Diagnostics/src/ExceptionHandler/ExceptionHandlerMiddleware.cs#L107),以使這些值不可用。
如果您的應用程式現在在`Development`環境中引發異常,則您將在響應中獲取作為JSON返回的完整異常:
![開發中的ProblemDetails響應](https://img2018.cnblogs.com/blog/1377250/202003/1377250-20200315154015954-1557303213.png)
在生產環境中,您仍然會得到ProblemDetails響應,但是省略了詳細資訊:
![生產中的ProblemDetails響應](https://img2018.cnblogs.com/blog/1377250/202003/1377250-20200315154015122-1465272789.png)
與MVC /重新執行路徑方法相比,此方法顯然具有一些侷限性,即您不容易獲得模型繫結,內容協商,簡單的序列化或本地化(取決於您的方法)。
如果您需要其中任何一個(例如,也許您使用PascalCase而不是camelCase從MVC進行序列化),那麼使用此方法可能比其價值更麻煩。如果是這樣,那麼[所描述的Controller方法](https://docs.microsoft.com/en-us/aspnet/core/web-api/handle-errors?view=aspnetcore-3.1#exception-handler)可能是明智的選擇。
如果您不關心這些,那麼本文中顯示的簡單處理程式方法可能是更好的選擇。無論哪種方式,都不要嘗試實現自己的版本`ExceptionHandlerMiddleware`-使用可用的擴充套件點!