ASP.NET Core应用针对静态文件请求的处理[4]: DirectoryBrowserMiddleware中间件如何呈现目录结构

和StaticFileMiddleware中间件一样，DirectoryBrowserMiddleware中间本质上还是定义了一个请求地址与某个物理目录之间的映射关系，而目标目录体现为一个FileProvider对象。当这个中间件接收到匹配的请求后，会根据请求地址解析出对应目录的相对路径，并利用这个FileProvider获取目录的内容。目录的内容最终会以一个HTML文档的形式被定义，而此HTML最终会被这个中间件作为响应的内容，“目录浏览器”的实现原理就这么简单。 [本文已经同步到《ASP.NET Core框架揭秘》之中]

目录
一、DirectoryBrowserMiddleware
二、DirectoryFormatter
三、具体请求处理逻辑
四、自定义DirectoryFormatter

一、DirectoryBrowserMiddleware

接下来我们来看看DirectoryBrowserMiddleware的定义。如下面的代码片段所示，DirectoryBrowserMiddleware的第二个构造函数具有四个参数，其中第二个参数是代表当前执行环境的HostingEnvironment。作为第三个参数的是一个HtmlEncoder对象，当目标目录被呈现为一个HTML文档的时候，它被用于实现针对HTML的编码，如果没有显式指定（调用第一个构造函数），默认的HtmlEncoder（HtmlEncoder.Default）会被使用。至于第四个类型为IOptions<DirectoryBrowserOptions>的参数，则承载了针对DirectoryBrowserMiddleware的配置选项，DirectoryBrowserOptions与前面介绍的StaticFileOptions一样，它们都是SharedOptionsBase的子类。

public class DirectoryBrowserMiddleware
{
    public DirectoryBrowserMiddleware(RequestDelegate next, IHostingEnvironment env, IOptions<DirectoryBrowserOptions> options)
    public DirectoryBrowserMiddleware(RequestDelegate next, IHostingEnvironment hostingEnv, HtmlEncoder encoder, IOptions<DirectoryBrowserOptions> options);
    public Task Invoke(HttpContext context);
}

public class DirectoryBrowserOptions : SharedOptionsBase
{
    public IDirectoryFormatter Formatter { get; set; }

    public DirectoryBrowserOptions();
    public DirectoryBrowserOptions(SharedOptions sharedOptions);
}

二、DirectoryFormatter

DirectoryBrowserMiddleware中间件的目的很明确，就是将目录下的内容（文件和子目录）格式化成一种可读的形式响应给客户端，针对目录内容的响应最终实现在一个DirectoryFormatter对象上。DirectoryFormatter是我们对所有实现了IDirectoryFormatter接口的类型与对应对象的统称，DirectoryBrowserOptions的Formatter属性设置和返回的就是这个一个对象。

如下面的代码片段所示，IDirectoryFormatter接口仅仅包含一个GenerateContentAsync方法。当实现这个方法的时候，我们可以利用第一个类型为HttpContext的参数获取当前请求上下文的信息。该方法的另一个参数返回一组FileInfo的集合，每个FileInfo代表目标下的某个以文件或者子目录。

public interface IDirectoryFormatter
{
    Task GenerateContentAsync(HttpContext context, IEnumerable<IFileInfo> contents);
}

我们知道默认情况下请求目录的内容在页面上是以一个表格的形式被呈现的，包含这个表格的HTML文档是默认使用的DirectoryFormatter生成的，它是一个类型为HtmlDirectoryFormatter的对象。如下面的代码片段所示，我们在构造一个HtmlDirectoryFormatter对象的时候需要指定一个HtmlEncoder对象，该对象最初来源于构造DirectoryBrowserMiddleware时指定的那个HtmlEncoder对象。

public class HtmlDirectoryFormatter : IDirectoryFormatter
{
    public HtmlDirectoryFormatter(HtmlEncoder encoder);
    public virtual Task GenerateContentAsync(HttpContext context, IEnumerable<IFileInfo> contents);
}

三、具体请求处理逻辑

既然最复杂的工作（呈现目录内容）都已经交给DirectoryFormatter来完成了，DirectoryBrowserMiddleware自身的工作其实就没有多少了。为了更好的说明这个中间件在处理请求是具体做了些什么，我们采用一种比较好理解的方式对DirectoryBrowserMiddleware类型进行了重新定义，具体的实现体现在如下所示的代码片段中。

public class DirectoryBrowserMiddleware
{
    private RequestDelegate _next;
    private DirectoryBrowserOptions _options;

    public DirectoryBrowserMiddleware(RequestDelegate next, IHostingEnvironment env, IOptions<DirectoryBrowserOptions> options) : this(next, env, HtmlEncoder.Default,options)
    { }

    public DirectoryBrowserMiddleware(RequestDelegate next, IHostingEnvironment env, HtmlEncoder encoder, IOptions<DirectoryBrowserOptions> options)
    {
        _next                      = next;
        _options                   = options.Value;
        _options.FileProvider      = _options.FileProvider ?? env.WebRootFileProvider;
        _options.Formatter         = _options.Formatter ?? new HtmlDirectoryFormatter(encoder);
    }

    public async Task Invoke(HttpContext context)
    {
        //只处理GET和HEAD请求
        if (!new string[] { "GET", "HEAD" }.Contains(context.Request.Method, StringComparer.OrdinalIgnoreCase))
        {
            await _next(context);
            return;
        }

       //检验当前路径是否与注册的请求路径相匹配
        PathString path = new PathString(context.Request.Path.Value.TrimEnd('/') + "/");
        PathString subpath;
        if (!path.StartsWithSegments(_options.RequestPath, out subpath))
        {
            await _next(context);
            return;
        }

        //检验目标目录是否存在
        IDirectoryContents directoryContents = _options.FileProvider.GetDirectoryContents(subpath);
        if (!directoryContents.Exists)
        {
            await _next(context);
            return;
        }

        //如果当前路径不以"/"作为后缀，会响应一个针对“标准”URL的重定向
        if (!context.Request.Path.Value.EndsWith("/"))
        {
            context.Response.StatusCode = 302;
            context.Response.GetTypedHeaders().Location = new Uri(path.Value + context.Request.QueryString);
            return;
        }

        //利用DirectoryFormatter响应目录内容
        await _options.Formatter.GenerateContentAsync(context, directoryContents);
    }
}

如上面的代码片段所示，当DirectoryBrowserMiddleware最终利用注册的DirectoryFormatter来响应目标目录的内容之前，它会做一系列的前期工作。比如它会验证当前请求是否是GET或者HEAD请求，以及当前的URL是否与注册的请求路径相匹配，在匹配的情况下还需要验证目标目录是否存在。除此之外，这个中间件要求访问目录的请求路劲必须以字符“/”作为后缀，否则会在目前的路径上添加这个后缀并针对最终的路径发送一个重定向。所以我们利用浏览器发送针对某个目录的请求的时候，URL明明没有指定“/”作为后缀，这个后缀会自动给我们加上，这就是重定向的作用。

四、自定义DirectoryFormatter

由于目录的内容在浏览器中的呈现方式完全由DirectoryFormatter完成，如果实现在HtmlDirectoryFormatter的默认呈现方式不能满足需求（比如我们需要这个页面与现有网站保持相同的风格），这可以通过注册一个自定义的DirectoryFormatter来完成。接下来我们通过一个简单的实例来演示如何定义这么一个DirectoryFormatter。我们将自定义的DirectoryFormatter命名为ListDirectoryFormatter，应为它仅仅将所有文件或者子目录显示为一个简单的列表。

public class ListDirectoryFormatter : IDirectoryFormatter
{
    public async Task GenerateContentAsync(HttpContext context, IEnumerable<IFileInfo> contents)
    {
        context.Response.ContentType = "text/html";
        await context.Response.WriteAsync("<html><head><title>Index</title><body><ul>");
        foreach (var file in contents)
        {
            string href = $"{context.Request.Path.Value.TrimEnd('/')}/{file.Name}";
            await context.Response.WriteAsync($"<li><a href='{href}'>{file.Name}</a></li>");
        }
        await context.Response.WriteAsync("</ul></body></html>");
    }
}

public class Program
{
    public static void Main()
    {
        new WebHostBuilder()
            .UseContentRoot(Directory.GetCurrentDirectory())
            .UseKestrel()
            .Configure(app => app.UseDirectoryBrowser(new DirectoryBrowserOptions {Formatter = new ListDirectoryFormatter()}))
            .Build()
            .Run();
    }
}

如上面的代码片段，ListDirectoryFormatter最终响应的是一个完整的HTML文档，它的主体部分只包含一个通过<ul>…</ul>表示的无序列表。列表元素（<li>）是一个针对文件或者子目录的链接。在调用扩展方法UseDirectoryBrowser注册DirectoryBrowserMiddleware中间件的时候，我们为将一个ListDirectoryFormatter对象设置为DirectoryBrowserOptions的Formatter属性。目录内容最终将会采用如图9所示的形式呈现在浏览器上。

 

---

ASP.NET Core应用针对静态文件请求的处理[1]: 以Web的形式发布静态文件
ASP.NET Core应用针对静态文件请求的处理[2]: 条件请求与区间请求
ASP.NET Core应用针对静态文件请求的处理[3]: StaticFileMiddleware中间件如何处理针对文件请求
ASP.NET Core应用针对静态文件请求的处理[4]: DirectoryBrowserMiddleware中间件如何呈现目录结构
ASP.NET Core应用针对静态文件请求的处理[5]: DefaultFilesMiddleware中间件如何显示默认页面