ASP.NET Core应用的错误处理[4]：StatusCodePagesMiddleware中间件如何针对响应码呈现错误页面

StatusCodePagesMiddleware中间件与ExceptionHandlerMiddleware中间件比较类似，它们都是在后续请求处理过程中“出错”的情况下利用一个错误处理器来完成最终的请求处理与响应的任务。它们之间的差异在于对“错误”的界定上，对于ExceptionHandlerMiddleware中间件来说，它所谓的错误就是抛出异常，但是对于StatusCodePagesMiddleware中间件来说，则将介于400~599之间的响应状态码视为错误。如下面的代码片段所示，StatusCodePagesMiddleware中间件也采用“标准”的定义方式，针对它的配置选项通过一个对应的对象以Options模式的形式提供给它。 [本文已经同步到《ASP.NET Core框架揭秘》之中]

public class StatusCodePagesMiddleware
{
    public StatusCodePagesMiddleware(RequestDelegate next, IOptions<StatusCodePagesOptions> options);
    public Task Invoke(HttpContext context);
}

除了针对错误的界定，StatusCodePagesMiddleware和ExceptionHandlerMiddleware这两个中间件对于错误处理器的表达也不相同。我们知道ExceptionHandlerMiddleware中间件使用的错误处理器实际上就是一个类型为RequestDelegate的委托对象，但是错误处理器之于StatusCodePagesMiddleware中间件来说则是一个类型为Func<StatusCodeContext, Task>的委托对象。如下面的代码片段所示，为StatusCodePagesMiddleware中间件提供配置选项的StatusCodePagesOptions对象的唯一目的就是提供这个作为错误处理器的委托对象。

public class StatusCodePagesOptions
{
    public Func<StatusCodeContext, Task> HandleAsync { get; set; }
}

我们知道一个RequestDelegate对象相当于一个类型为Func<HttpContext, Task>类型的委托对象，而一个StatusCodeContext对象实际上也是对一个HttpContext对象的封装，所以StatusCodePagesMiddleware中间件和ExceptionHandlerMiddleware中间件所使采用的错误处理器并没有本质上的不同。如下面的代码片段所示，除了从StatusCodeContext对象中获取代表当前请求上下文的HttpContext对象之外，我们还可以通过其Next属性得到一个RequestDelegate对象，它代表由后续中间件组成的请求处理管道。至于另一个属性Options，很明显它返回我们在创建StatusCodePagesMiddleware中间件所指定的StatusCodePagesOptions对象。

public class StatusCodeContext
{
    public HttpContext             HttpContext { get; }
    public RequestDelegate         Next { get; }
    public StatusCodePagesOptions  Options { get; }

    public StatusCodeContext(HttpContext context, StatusCodePagesOptions options, RequestDelegate next);
}

一、针对响应状态码的错误处理

由于采用了针对响应状态码的错误处理策略，所以实现在StatusCodePagesMiddleware中间件中的所有错误处理操作只会发生在当前响应状态码在400~599之间的情况，如下所示的代码片段体现了这一点。从下面给出的代码片段可以看出，StatusCodePagesMiddleware中间件在决定是否执行错误处理操作时除了会查看当前响应状态码之外，还会查看响应内容以及媒体类型，如果已经包含了响应内容或者设置了媒体类型，该中间件将不会执行任何操作。

public class StatusCodePagesMiddleware
{
    private  RequestDelegate            _next;
    private  StatusCodePagesOptions     _options;

public StatusCodePagesMiddleware(RequestDelegate next,
    IOptions<StatusCodePagesOptions> options)
    {
        _next         = next;
        _options      = options.Value;
    }

    public async Task Invoke(HttpContext context)
    {
        await _next(context);
        var response = context.Response;
        if ((response.StatusCode >= 400 && response.StatusCode <= 599) &&!response.ContentLength.HasValue && string.IsNullOrEmpty(response.ContentType))
        {
            await _options.HandleAsync(new StatusCodeContext(context, _options, _next));
        }
    }
}

StatusCodePagesMiddleware中间件针对错误的处理非常简单，它只需要从StatusCodePagesOptions对象中提取出作为错误处理器的这个Func<StatusCodeContext, Task>对象，然后创建一个StatusCodeContext对象作为输入参数调用这个委托对象即可。

二、阻止异常处理

如果当前响应已经被写入了内容，或者响应的媒体类型已经被预先设置，那么StatusCodePagesMiddleware中间件将不会再执行任何的错误处理操作。这种情况实际上代表由后续中间件构成的管道可能需要自行控制当前的响应，所以StatusCodePagesMiddleware中间件不应该再做任何的干预。从这个意义上来讲，StatusCodePagesMiddleware中间件仅仅是作为一种后备的错误处理机制而已。

更进一步来将，如果后续的某个中间件返回了一个状态码在400~599之间的响应，并且这个响应只有报头集合没有主体（媒体类型自然也不会设置），那么按照我们在上面给出的错误处理逻辑，StatusCodePagesMiddleware中间件还是会按照自己的策略来处理并响应请求。为了解决这种情况下，我们必须赋予后续中间件一个能够阻止StatusCodePagesMiddleware中间件进行错误处理的能力。

阻止StatusCodePagesMiddleware中间件进行错误处理的机制是借助于一个名为StatusCodePagesFeature的特性来实现的。StatusCodePagesFeature对应如下这个IStatusCodePagesFeature接口，它具有唯一的布尔类型的属性成员Enabled。默认使用的StatusCodePagesFeature类型实现了这个接口，默认情况下这个开关是开启的。

public interface IStatusCodePagesFeature
{
    bool Enabled { get; set; }
}

public class StatusCodePagesFeature : IStatusCodePagesFeature
{
    public bool Enabled { get; set; } = true ;
}

StatusCodePagesMiddleware中间件在将请求交付给后续管道之前，它会创建一个StatusCodePagesFeature特性对象并将其添加到当前HttpContext之中。当最终决定是否执行错误处理操作的时候，它还会通过这个特性检验是否某个后续的中间件不希望自己“画蛇添足”地进行不必要的错误处理，如下的代码片段很好的体现了这一点。

public class StatusCodePagesMiddleware
{
    …
    public async Task Invoke(HttpContext context)
    {
        StatusCodePagesFeature feature = new StatusCodePagesFeature();
        context.Features.Set<IStatusCodePagesFeature>(feature);

        await _next(context);
        var response = context.Response;
        if ((response.StatusCode >= 400 && response.StatusCode <= 599) && !response.ContentLength.HasValue &&string.IsNullOrEmpty(response.ContentType) &&
            feature.Enabled)
        {
            await _options.HandleAsync(new StatusCodeContext(context, _options, _next));
        }
    }
}

我们通过一个简单的实例来演示如果利用这个StatusCodePagesFeature特性来屏蔽StatusCodePagesMiddleware中间件。在下面这个应用中，我们将针对请求的处理定义在Invoke方法中，该方法会返回一个状态码为“401 Unauthorized”的响应。我们通过随机数让这个方法会在50%的情况下利用StatusCodePagesFeature特性来阻止StatusCodePagesMiddleware中间件自身对错误的处理。我们通过调用扩展方法UseStatusCodePages注册的StatusCodePagesMiddleware中间件会直接响应一个内容为“Error occurred!”的字符串。

public class Program
{
    public static void Main()
    {
        new WebHostBuilder()
            .UseKestrel()
            .Configure(app => app
                .UseStatusCodePages(async context => await context.HttpContext.Response.WriteAsync("Error occurred!"))
                .Run(Invoke))
            .Build()
            .Run();
    }

    private static Random _random = new Random();
    private static Task Invoke(HttpContext context)
    {
        context.Response.StatusCode = 401;

        if (_random.Next() % 2 == 0)
        {
            context.Features.Get<IStatusCodePagesFeature>().Enabled = false;
        }
        return Task.CompletedTask;
    }
}

对于针对该应用的请求来说，我们会得到如下两种不同的响应。没有主体内容响应是通过Invoke方法产生的，这种情况下发生在StatusCodePagesMiddleware中间件通过StatusCodePagesFeature特性被屏蔽的时候。具有主体内容的响应则来源于StatusCodePagesMiddleware中间件。

HTTP/1.1 401 Unauthorized
Date: Sun, 18 Dec 2016 01:59:37 GMT
Server: Kestrel
Content-Length: 15

Error occurred!


HTTP/1.1 401 Unauthorized
Date: Sun, 18 Dec 2016 01:59:38 GMT
Content-Length: 0
Server: Kestrel

三、注册StatusCodePagesMiddleware中间件

我们在大部分情况下都会调用ApplicationBuilder相应的扩展方法来注册StatusCodePagesMiddleware中间件。对于StatusCodePagesMiddleware中间件的注册来说，除了我们已经很熟悉的UseStatusCodePages方之外，还具有额外一些扩展方法供我们选择。

UseStatusCodePages

我们可以调用如下三个UseStatusCodePages方法重载来注册StatusCodePagesMiddleware中间件。不论我们调用那个重载，系统最终都会根据提供的StatusCodePagesOptions对象调用构造函数来创建这个中间件对象，而且这个StatusCodePagesOptions必须具有一个作为错误处理器的Func<StatusCodeContext, Task>对象。如果没有指定任何参数，StatusCodePagesOptions对象需要以Options模式的形式注册为服务。

public static class StatusCodePagesExtensions
{
    public static IApplicationBuilder UseStatusCodePages(this IApplicationBuilder app)
    {
        return app.UseMiddleware<StatusCodePagesMiddleware>();
    }

    public static IApplicationBuilder UseStatusCodePages(this IApplicationBuilder app, StatusCodePagesOptions options)
    {
        return app.UseMiddleware<StatusCodePagesMiddleware>(Options.Create(options));
    }

    public static IApplicationBuilder UseStatusCodePages(this IApplicationBuilder app, Func<StatusCodeContext, Task> handler)
    {
        return app.UseStatusCodePages(new StatusCodePagesOptions
        {
            HandleAsync = handler
        });
    }
}

由于StatusCodePagesMiddleware中间件最终的目的还是将定制的错误信息响应给客户端，所以我们可以在注册该中间件的时候直接指定响应的内容和媒体类型，这样的注册方式可以通过调用如下这个UseStatusCodePages方法来完成。从如下所示的代码片段我们不难看出，我们通过bodyFormat方法指定的实际上是一个模板，它可以包含一个表示响应状态的占位符（“{0}”）。

public static class StatusCodePagesExtensions
{
    public static IApplicationBuilder UseStatusCodePages(this IApplicationBuilder app, string contentType, string bodyFormat)
    {
        return app.UseStatusCodePages(context =>
        {
            var body = string.Format(CultureInfo.InvariantCulture, bodyFormat, context.HttpContext.Response.StatusCode);
            context.HttpContext.Response.ContentType = contentType;
            return context.HttpContext.Response.WriteAsync(body);
        });
    }
}

UseStatusCodePagesWithRedirects

如果我们调用UseStatusCodePagesWithRedirects方法，可以让注册的StatusCodePagesMiddleware中间件向指定的路径发送一个客户端重定向。从如下所示的实现代码可以看出，这个作为参数locationFormat的重定向地址也是一个模板，它可以包含一个表示响应状态的占位符（“{0}”）。我们可以指定一个完整的地址，也可以指定一个相对于PathBase的相对路径，后者需要包含表示基地址的“~/”前缀。

public static class StatusCodePagesExtensions
{
    public static IApplicationBuilder UseStatusCodePagesWithRedirects(this IApplicationBuilder app, string locationFormat)
    {
        if (locationFormat.StartsWith("~"))
        {
            locationFormat = locationFormat.Substring(1);
            return app.UseStatusCodePages(context =>
            {
                var location = string.Format(CultureInfo.InvariantCulture, locationFormat, context.HttpContext.Response.StatusCode);
                context.HttpContext.Response.Redirect(context.HttpContext.Request.PathBase + location);
                return Task.CompletedTask;
            });
        }
        else
        {
            return app.UseStatusCodePages(context =>
            {
                var location = string.Format(CultureInfo.InvariantCulture, locationFormat, context.HttpContext.Response.StatusCode);
                context.HttpContext.Response.Redirect(location);
                return Task.CompletedTask;
            });
        }
    }
}

我们通过一个简单的应用来演示针对客户端重定向的错误页面呈现方式。我们在如下这个应用中注册了一个路由模板为“error/{statuscode}”的路由，路由参数“statuscode”自然代表响应的状态码。在作为路由处理器的HandleError方法中，我们会直接响应一个包含响应状态码的字符串。我们调用UseStatusCodePagesWithRedirects方法注册StatusCodePagesMiddleware中间件的时候将重定义路径设置为“error/{0}”。

public class Program
{
    private static Random _random = new Random();
    public static void Main()
    {
        new WebHostBuilder()
            .UseKestrel()
            .ConfigureServices(svcs => svcs.AddRouting())
            .Configure(app => app
                .UseStatusCodePagesWithRedirects("~/error/{0}")
                .UseRouter(builder=>builder.MapRoute("error/{statuscode}", HandleError))
                .Run(context=>Task.Run(()=>context.Response.StatusCode = _random.Next(400,599))))
            .Build()
            .Run();
    }

    private async static Task HandleError(HttpContext context)
    {
        var statusCode = context.GetRouteData().Values["statuscode"];
        await context.Response.WriteAsync($"Error occurred ({statusCode})");
    }
}

针对该应用的请求总是会得到一个状态码在400~599之间的响应， StatusCodePagesMiddleware在此情况下会向我们指定的路径（“~/error/{statuscode}”）发送一个客户端重定向。由于重定向请求的路径与注册的路由相匹配，所以作为路由处理器的HandleError方法会响应如图11所示的这个错误页面。

UseStatusCodePagesWithReExecute

除了采用客户端重定向的方式来呈现错误页面之外，我们还可以调用UseStatusCodePagesWithReExecute方法注册StatusCodePagesMiddleware中间件并让它采用服务端重定向的方式来处理错误请求。如下面的代码片段所示，当我们调用这个方法的时候不仅可以指定重定向的路径，还可以指定指定查询字符串。这里作为重定向地址的参数pathFormat依旧是一个路径模板，它可以包含一个表示响应状态的占位符（“{0}”）。

public static class StatusCodePagesExtensions
{
    public static IApplicationBuilder UseStatusCodePagesWithReExecute(this IApplicationBuilder app, string pathFormat, string queryFormat = null);
}

现在我们对上面演示的这个实例略作修改来演示采服务端重定向呈现出来的错误页面。如下面的代码片段所示，我们仅仅将针对UseStatusCodePagesWithRedirects方法的调用替换成针对UseStatusCodePagesWithReExecute方法的调用而已。

public class Program
{
    private static Random _random = new Random();
    public static void Main()
    {
        new WebHostBuilder()
            .UseKestrel()
            .ConfigureServices(svcs => svcs.AddRouting())
            .Configure(app => app
                .UseStatusCodePagesWithReExecute("/error/{0}")
                .UseRouter(builder=>builder.MapRoute("error/{statuscode}", HandleError))
                .Run(context=>Task.Run(()=>context.Response.StatusCode = _random.Next(400,599))))
            .Build()
            .Run();
    }

    private async static Task HandleError(HttpContext context)
    {
        var statusCode = context.GetRouteData().Values["statuscode"];
        await context.Response.WriteAsync($"Error occurred ({statusCode})");
    }
}

对于前面演示的实例，由于错误页面是通过客户端重定向的方式呈现出来的，所以浏览器地址栏显示的是重定向地址。我们在选择这个实例中采用了服务端重定向，虽然显示的页面内容并没有不同，但是地址栏上的地址是不会发生改变的

之所以被命名为UseStatusCodePagesWithReExecute，是因为通过这方法注册的StatusCodePagesMiddleware中间件进行错误处理的时候，它仅仅是提供的重定向路径和查询字符串应用到当前HttpContext，然后递交给后续管道重新执行。UseStatusCodePagesWithReExecute方法中注册StatusCodePagesMiddleware中间件的实现总体上可以由如下所示的代码片段来体现。

public static class StatusCodePagesExtensions
{
    public static IApplicationBuilder UseStatusCodePagesWithReExecute(this IApplicationBuilder app,string pathFormat,string queryFormat = null)
    {
        return app.UseStatusCodePages(async context =>
        {
            var newPath = new PathString(string.Format(CultureInfo.InvariantCulture, pathFormat, context.HttpContext.Response.StatusCode));
            var formatedQueryString = queryFormat == null ? null :string.Format(CultureInfo.InvariantCulture, queryFormat, context.HttpContext.Response.StatusCode);
            context.HttpContext.Request.Path = newPath;
            context.HttpContext.Request.QueryString = newQueryString;
            await context.Next(context.HttpContext);
        });
    }
}

与ExceptionHandlerMiddleware中间价类似，StatusCodePagesMiddleware中间件在处理请求的过程中会改变当前请求上下文的状态，具体体现在将指定的请求路径和查询字符串重新应用到当前请求上下文中。为了不影响前置中间件对请求的正常处理，StatusCodePagesMiddleware中间件在完成自身处理流程之后必须将当前请求上下文恢复到原始的状态。StatusCodePagesMiddleware中间件依旧是采用一个特性来保存原始的路径和查询字符串。这个特性对应的接口为具有如下定义的IStatusCodeReExecuteFeature，令人费解的是该接口仅仅包含两个针对路径的属性，并没有我们希望的用于携带原始查询上下文的属性，但是默认实现类型StatusCodeReExecuteFeature包含了这个属性。

public interface IStatusCodeReExecuteFeature
{
    string OriginalPath { get; set; }
    string OriginalPathBase { get; set; }
}

public class StatusCodeReExecuteFeature : IStatusCodeReExecuteFeature
{
    public string OriginalPath { get; set; }
    public string OriginalPathBase { get; set; }
    public string OriginalQueryString { get; set; }
}

当StatusCodePagesMiddleware中间件在处理异常请求的过程中，在将指定的重定向路径和查询字符串应用到当前请求上下文上之前，它会根据原始的上下文创建一个StatusCodeReExecuteFeature特性对象并将其添加到当前HttpContext之上。当整个请求处理过程结束之后，StatusCodePagesMiddleware中间件还会负责将这个特性从当前HttpContext中移除，并恢复原始的请求路径和查询字符串。如下所示的代码片段体现了UseStatusCodePagesWithReExecute方法的真实逻辑。

public static class StatusCodePagesExtensions
{
    public static IApplicationBuilder UseStatusCodePagesWithReExecute(this IApplicationBuilder app,string pathFormat,string queryFormat = null)
    {
        return app.UseStatusCodePages(async context =>
        {
            var newPath = new PathString(string.Format(CultureInfo.InvariantCulture, pathFormat, context.HttpContext.Response.StatusCode));
            var formatedQueryString = queryFormat == null ? null :string.Format(CultureInfo.InvariantCulture, queryFormat, context.HttpContext.Response.StatusCode);
            var newQueryString = queryFormat == null ? QueryString.Empty : new QueryString(formatedQueryString);

            var originalPath = context.HttpContext.Request.Path;
            var originalQueryString = context.HttpContext.Request.QueryString;

            context.HttpContext.Features.Set<IStatusCodeReExecuteFeature>(new StatusCodeReExecuteFeature()
            {
                OriginalPathBase = context.HttpContext.Request.PathBase.Value,
                OriginalPath = originalPath.Value,
                OriginalQueryString = originalQueryString.HasValue ? originalQueryString.Value : null,
            });

            context.HttpContext.Request.Path = newPath;
            context.HttpContext.Request.QueryString = newQueryString;
            try
            {
                await context.Next(context.HttpContext);
            }
            finally
            {
                context.HttpContext.Request.QueryString = originalQueryString;
                context.HttpContext.Request.Path = originalPath;
                context.HttpContext.Features.Set<IStatusCodeReExecuteFeature>(null);
            }
        });
    }
}

ASP.NET Core应用的错误处理[1]：三种呈现错误页面的方式
ASP.NET Core应用的错误处理[2]：DeveloperExceptionPageMiddleware中间件
ASP.NET Core应用的错误处理[3]：ExceptionHandlerMiddleware中间件
ASP.NET Core应用的错误处理[4]：StatusCodePagesMiddleware中间件