第二章 基础知识（6） - 静态文件

以下内容主要以Blazor App （server）项目为例子

Web根目录

.Net8 及以下版本的Blazor App (Server)的静态文件跟MVC的差不多，也是通过静态文件中间件提供的。（官方文档中有提及.Net8以后的Blazor不再使用静态文件中间件，这个以后再看）

打开项目中的Program.cs文件，可以看到，里面通过调用UseStaticFiles()方法，将静态文件中间件配置为允许向客户端提供静态资产。

• 注意，这里说的是向客户端提供静态资源，即使不调用UseStaticFiles()方法，我们项目代码中还是可以访问到wwwroot下的资源的，只是客户端（浏览器）上访问不了。

默认情况下，提供静态资源的目录为项目的 Web 根目录。 即项目中的wwwroot目录下。

静态资源的访问路径

wwwroot目录在项目中是实际存在的，其中的静态文件也是直接存放在磁盘上的。但是实际访问时，在 URL 上是隐藏wwwroot文件夹的，直接访问的是wwwroot下的第一层子文件夹。例如我们在wwwroot下添加了wwwroot/images/MyImage.jpg 文件，当我们想在浏览器中访问资源时，URI应该为https://localhost:5001/images/MyImage.jpg。

• 项目中访问时，可以简化为/images/MyImage.jpg或images/MyImage.jpg，指向Web根目录。
• 注意，在MVC等项目时，可以使用~/来指向Web根目录，但是Blazor组件中是不支持~/的。

静态资源的相对路径
在Program.cs中，通过app.Environment.WebRootPath属性可以从环境变量中获取静态文件的相对路径。

示例

//获取Web根目录
var webRoot = app.Environment.WebRootPath;
......

配置静态文件夹

一、配置访问路径

默认情况下，放在wwwroot文件夹下的子文件夹或文件是可以直接通过URL访问的，比如在wwwroot文件夹下添加imgs文件夹，再在其中添加test.png，访问时URL为https://localhost:7249/imgs/test.png。

此时，如果希望给静态文件夹指定访问路径，可以在Program.cs中使用UseStaticFiles()方法进行设置。

UseStaticFiles(string requestPath)：IApplicationBuilder对象的扩展方法，设置静态访问路径的固定路径。（默认是可以直接访问的）

• 仅仅是改变了访问规则，访问的真实路径依然是wwwroot目录下的资源
• 注意修改之后，项目中原先引用了静态资源的访问路径全部都要跟着修改，否则是访问不到的。

Program.cs

......
app.UseStaticFiles("/static");
......

上述代码设置后，访问路径则变为https://localhost:7249/static/imgs/test.png

二、添加静态文件夹

默认情况下，项目的静态文件夹为wwwroot，如果希望添加其他文件夹作为静态资源文件夹，可以在Program.cs中使用UseStaticFiles()方法进行设置。

• UseStaticFiles(StaticFileOptions options)：IApplicationBuilder对象的扩展方法，配置项目的静态文件夹。

• 设置的文件夹必须已存在，且位于项目根目录下。

Program.cs

......
app.UseStaticFiles(); //无参的是提供默认wwwroot静态目录
app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(Path.Combine(app.Environment.ContentRootPath, "MyStaticfiles")),
    RequestPath = "/files"
});
......

上述代码设置完成后，可以通过https://localhost:7249/files/…访问项目根目录下，MyStaticfiles文件夹中的静态文件。
需要注意的是，可以使用多个UseStaticFiles()配置提供静态文件的文件夹，与当前设置的 Web 根目录并列存在。如果添加的静态文件夹的访问路径与Web根目录的访问路径一致，会优先访问到Web根目录中的静态资源。

三、设置Web根目录

如果是希望改变Web根目录，而不是添加静态文件夹，可以在Program类中，创建WebApplicationBuilder对象时，通过传入WebApplicationOptions对象参数进行设置。

Program.cs

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    Args = args,
    WebRootPath = "contentfiles"  //设置Web根目录
});

......
//app.UseStaticFiles();
app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(Path.Combine(app.Environment.ContentRootPath, "contentfiles")),
    RequestPath = "/file"
});
......

设置 HTTP 响应标头

对于 Web 应用程序来说，HTTP 请求和 HTTP 响应是离不开的两个重要的对象。用户从浏览器发起 HTTP 请求，Web 服务器接收到 HTTP 请求并处理后会返回给 HTTP 响应给浏览器。不管是 HTTP 请求的消息，还是 HTTP 响应的消息，都属于 HTTP 消息。

HTTP 消息由如下部分组成：

• 一个起始行。
• 一个或者多个头域。
• 一个头域结束的空行。
• 可选的消息体组成。

其中，HTTP 的头域包括通用头、请求头、响应头和实体头四个部分。每个头域由一个域名、冒号:和域值三部分组成。例如：Cache-Control:public,max-age=900，就是一个头域。

可以在Program类中，使用UseStaticFiles()方法中配置静态文件时，设置 HTTP 响应头。HTTP响应头是服务器向客户端返回的消息体中包括的头，由Response Headers表示。

一、查看 HTTP 响应头

在设置 HTTP 响应头之前，我们首先要知道在哪查看 HTTP 响应头。运行 Web 应用程序，访问首页：
从上图中可以看到，Headers由3个部分组成：

• General：通用头。
• Response Headers：响应头。
• Request Headers：请求头。

二、设置 HTTP 响应头

在UseStaticFiles()中，可以使用StaticFileOptions对象设置 HTTP 响应标头。

Program.cs

设置静态文件可在 800 秒内公开缓存。

......
app.UseStaticFiles(new StaticFileOptions
{
    OnPrepareResponse = ctx =>
    {
        ctx.Context.Response.Headers.Append("Cache-Control", "public, max-age=800");
    }
});
......

启用目录浏览

静态文件实际上是存放在磁盘上的，所以静态文件所在的文件夹也是实际存在的。只要是磁盘上存在的目录，都是可以被浏览的。默认情况下，出于安全考虑，目录浏览默认处于禁用状态。

如果要启用 Web 应用程序的目录浏览功能，需要完成如下两步：

• 注册AddDirectoryBrowser服务。
• 启用UseDirectoryBrowser()中间件。

一、启用 Web 根目录浏览

默认情况下，只能存在一个 Web 根目录，所以我们使用不带参数的 UseDirectoryBrowser()就可以启用当前的 Web根目录的目录浏览功能。

Program.cs

var builder = WebApplication.CreateBuilder();
//注册目录浏览服务
builder.Services.AddDirectoryBrowser();

......
//使用目录浏览中间件，位置必须放在UseRouting()之前
app.UseDirectoryBrowser();
//app.UseDirectoryBrowser("/browser"); 可以指定浏览目录的URL路径
......

二、启用指定目录浏览

对于 Web 根目录之外的存放静态文件的文件夹，也是可以启用目录浏览的，只是需要指定这个目录名称。
在项目根目录中添加contentfiles文件夹，然后添加一些子文件夹和文件，如下：

由于不是使用默认的Web根目录，所以需要先使用UseStaticFiles()添加静态文件夹，并且在UseDirectoryBrowser()启用中间件时，指定目录浏览路径。

Program.cs

......
app.UseStaticFiles();
//添加静态访问文件夹
app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(Path.Combine(app.Environment.ContentRootPath, "contentfiles")),
    RequestPath = "/files"
});
app.UseDirectoryBrowser(new DirectoryBrowserOptions
{
    FileProvider = new PhysicalFileProvider(Path.Combine(app.Environment.ContentRootPath, "contentfiles")),
    RequestPath = "/files"
});
......

建议在开发阶段启用目录浏览，而在生产机上运行时，要禁用目录浏览，这是为了安全起见。

非Development环境中的静态文件

Blazor Web （server）项目在本地运行应用时，静态 Web 资产仅在 Development 环境中默认启用。 若要在本地开发和测试期间为 Development 以外的环境启用静态文件（例如 Staging），需要 Program 文件中调用WebApplicationBuilder对象的UseStaticWebAssets方法。

• 注意要根据环境来调用UseStaticWebAssets 以防止在生产环境中激活该功能，如果在生产环境中调用，该功能会从磁盘上的不同位置提供文件（而不是从项目提供）。

Program.cs

......
if (builder.Environment.IsStaging())
{
    builder.WebHost.UseStaticWebAssets();
}
......