31. 虚拟文件系统
📝 模块更新日志
以下内容仅限 Furion 2.5.0 +
版本使用。
31.1 关于文件系统
本章所谓的 文件系统
有点名不副实,其实根本算不上一个系统,它仅仅是利用一个抽象化的 IFileProvider
以统一的方式提供所需的文件而已。通过该 文件系统
可以读取物理文件和嵌入资源文件,包括目录结果读取,文件内容读取,文件内容监听等等。
31.1.1 文件系统类型
Furion
提供了两种文件系统类型:
Physical
:物理文件系统类型,也就是物理机中实际存在的文件Embedded
:嵌入资源文件系统类型,也就是资源文件嵌入到了程序集中,常用于模块化开发
31.2 注册虚拟文件系统服务
services.AddVirtualFileServer();
31.3 获取文件系统 IFileProvider
实例
31.3.1 Func<FileProviderTypes, object, IFileProvider>
方式
Furion
框架提供了 Func<FileProviderTypes, object, IFileProvider>
委托供构造函数注入或解析服务,如:
public class PersonServices
{
private readonly IFileProvider _physicalFileProvider;
private readonly IFileProvider _embeddedFileProvider;
public PersonServices(Func<FileProviderTypes, object, IFileProvider> fileProviderResolve)
{
// 解析物理文件系统
_physicalFileProvider = fileProviderResolve(FileProviderTypes.Physical, @"c:/test");
// 解析嵌入资源文件系统
_embeddedFileProvider = fileProviderResolve(FileProviderTypes.Embedded, Assembly.GetEntryAssembly());
}
}
31.3.2 FS
静态类方式
Furion
框架也提供了 FS
静态类方式创建,如:
// 解析物理文件系统
var physicalFileProvider = FS.GetPhysicalFileProvider(@"c:/test");
// 解析嵌入资源文件系统
var embeddedFileProvider = FS.GetEmbeddedFileProvider(Assembly.GetEntryAssembly());
31.4 IFileProvider
常见操作
31.4.1 读取文件内容
byte[] buffer;
using (Stream readStream = _fileProvider.GetFileInfo("你的文件路径").CreateReadStream())
{
buffer = new byte[readStream.Length];
await readStream.ReadAsync(buffer.AsMemory(0, buffer.Length));
}
// 读取文件内容
var content = Encoding.UTF8.GetString(buffer);
31.4.2 获取文件目录内容(需递归查找)
var rootPath = "当前目录路径";
var fileinfos = _fileProvider.GetDirectoryContents(rootPath);
foreach (var fileinfo in fileinfos)
{
if(fileinfo.IsDirectory)
{
// 这里递归。。。
}
}
31.4.4 监听文件变化
ChangeToken.OnChange(() => _fileProvider.Watch("监听的文件"), () =>
{
// 这里写你的逻辑
});
31.5 模块化静态资源配置
通常我们采用模块化开发,静态资源都是嵌入进程序集中,这时候我们需要通过配置 UseFileServer
指定模块静态资源路径,如:
// 默认静态资源调用,wwwroot
app.UseStaticFiles();
// 配置模块化静态资源
app.UseFileServer(new FileServerOptions
{
FileProvider = new EmbeddedFileProvider(模块程序集),
RequestPath = "/模块名称", // 后续所有资源都是通过 /模块名称/xxx.css 调用
EnableDirectoryBrowsing = true
});
31.6 文件上传下载
在应用开发中,文件上传下载属于非常常用的功能,这里贴出常见的文件上传下载示例。
31.6.1 文件下载
- 文件路径的方式
[HttpGet, NonUnify]
public IActionResult FileDownload()
{
string filePath = "这里获取完整的文件下载路径";
return new FileStreamResult(new FileStream(filePath, FileMode.Open), "application/octet-stream")
{
FileDownloadName = fileName // 配置文件下载显示名
};
}
byte[]
方式
[HttpGet, NonUnify]
public IActionResult FileDownload()
{
return new FileContentResult(byte数组, "application/octet-stream")
{
FileDownloadName = fileName // 配置文件下载显示名
};
}
如果前端获取不到文件,可添加以下配置:
_httpContextAccessor.HttpContext.Response.Headers.Add("Content-Disposition", $"attachment; filename={文件名}");
_httpContextAccessor.HttpContext.Response.Headers.Add("Access-Control-Expose-Headers", "Content-Disposition");
如果依然不能解决问题可尝试添加以下配置:
{
"CorsAccessorSettings": {
"WithExposedHeaders": [
"Content-Disposition",
"Access-Control-Expose-Headersx-access-token"
]
}
}
31.6.2 文件上传
IFormFile
类型对应前端的 Content-Type
为: multipart/form-data
- 单文件
IFormFile
类型参数(存储到硬盘)
[HttpPost]
public async Task<string> UploadFileAsync(IFormFile file)
{
// 如:保存到网站根目录下的 uploads 目录
var savePath = Path.Combine(App.HostEnvironment.ContentRootPath, "uploads");
if (!Directory.Exists(savePath)) Directory.CreateDirectory(savePath);
//// 这里还可以获取文件的信息
// var size = file.Length / 1024.0; // 文件大小 KB
// var clientFileName = file.FileName; // 客户端上传的文件名
// var contentType = file.ContentType; // 获取文件 ContentType 或解析 MIME 类型
// 避免文件名重复,采用 GUID 生成
var fileName = Guid.NewGuid().ToString("N") + Path.GetExtension(file.FileName);
var filePath = Path.Combine(savePath, fileName);
// 保存到指定路径
using (var stream = System.IO.File.Create(filePath))
{
await file.CopyToAsync(stream);
}
// 返回文件名(这里可以自由返回更多信息)
return filename;
}
- 单文件
Base64
类型参数(存储到硬盘)
[HttpPost]
public async Task<string> UploadFileAsync([FromBody] string fileBase64, string clientFileName)
{
// 如:保存到网站根目录下的 uploads 目录
var savePath = Path.Combine(App.HostEnvironment.ContentRootPath, "uploads");
if (!Directory.Exists(savePath)) Directory.CreateDirectory(savePath);
// 将 base64 字符串转 byte[]
var bytes = Convert.FromBase64String(fileBase64);
// 这里还可以获取文件的信息
// var size = bytes.Length / 1024.0; // 文件大小 KB
// 避免文件名重复,采用 GUID 生成
var fileName = Guid.NewGuid().ToString("N") + Path.GetExtension(clientFileName);
var filePath = Path.Combine(savePath, fileName);
// 保存到指定路径
using (var fs = new FileStream(filePath, FileMode.Create))
{
await fs.WriteAsync(bytes);
}
// 返回文件名(这里可以自由返回更多信息)
return filename;
}
文件 Base64
字符串如果带 data:text/plain;base64,
开头则,需要手动去掉 ,
之前(含逗号)的字符串。
- 多文件
List<IFormFile>
类型参数(存储到硬盘)
代码和 单文件处理一致
,只需 foreach
即可。
[HttpPost]
public async Task<object> UploadFileAsync(List<IFormFile> files)
{
// 保存到网站根目录下的 uploads 目录
var savePath = Path.Combine(App.HostEnvironment.ContentRootPath, "uploads");
if(!Directory.Exists(savePath)) Directory.CreateDirectory(savePath);
// 总上传大小
long size = files.Sum(f => f.Length);
// 遍历所有文件逐一上传
foreach (var formFile in files)
{
if (formFile.Length > 0)
{
// 避免文件名重复,采用 GUID 生成
var fileName = Guid.NewGuid().ToString("N") + Path.GetExtension(clientFileName);
var filePath = Path.Combine(savePath, fileName);
// 保存到指定路径
using (var stream = System.IO.File.Create(filePath))
{
await formFile.CopyToAsync(stream);
}
}
}
// 这里可自行返回更多信息
return new { count = files.Count, size };
}
- 多文件
List<string>
Base64
类型参数(存储到硬盘)
代码和 单文件处理一致
,只需 foreach
即可(参上)。
31.6.3 将 IFormFile
转 byte[]
有时候我们需要将文件转换成 byte[]
存储到数据库,而不是存储到硬盘中。
[HttpPost]
public async Task<IActionResult> UploadFileAsync(IFormFile file)
{
var fileLength = file.Length;
using var stream = file.OpenReadStream();
var bytes = new byte[fileLength];
stream.Read(bytes, 0, (int)fileLength);
// 这里将 bytes 存储到你想要的介质中即可
}
在 Furion v3.2.0
新增了 IFormFile
的 ToByteArray
拓展,如:
[HttpPost]
public async Task<IActionResult> UploadFileAsync(IFormFile file)
{
var bytes = file.ToByteArray();
// 这里将 bytes 存储到你想要的介质中即可
}
31.6.4 将 byte[]
输出为 Url
地址
由于一些项目直接将文件二进制存储在数据库中,读取到内存的时候都是 byte[]
数组,比如我们将图片文件存储在数据库中,然后前端通过 Url
链接进行访问,这个时候就需要将 byte[]
转换为有效的资源路径格式,如:
[NonUnify, HttpGet, AllowAnonymous]
public async Task<IActionResult> attachment(string resourceId)
{
// 根据 resourceId 查询 byte[] 字节数组和 content-type
// 返回 FileContentResult 类型
return new FileContentResult(字节数组,content-type);
}
之后我们就可以通过 https://localhost/attachment/资源id
访问文件或图片了。
31.7 请求大小控制(上传文件大小控制)
在 Web
项目中,Kestrel
和 HttpSys
都强制实施 30M (~28.6MiB)
的最大请求正文大小限制,如果请求正文大小超过配置的最大请求正文大小限制,则引发 Request body too large. The max request body size is xxxxx
异常,状态码为 413
或 500
。
31.7.1 对特定的接口进行控制
可通过 [RequestSizeLimit]
特性进行特定限制
[HttpPost]
[RequestSizeLimit(100_000_000)]
public IActionResult MyAction([FromBody] MyViewModel data)
{
}
31.7.2 对特定接口取消限制
如果不需要对请求大小进行限制,也就是支持提交无限大小,则贴 [DisableRequestSizeLimit]
特性即可。
31.7.3 通用中间件进行控制
我们也可以通过中间件的方式在 Startup.cs
中进行配置:
app.Run(async context =>
{
context.Features.Get<IHttpMaxRequestBodySizeFeature>().MaxRequestBodySize = 100_000_000; // 设置 null 就是不限制,具体值就是限制最大多少 M
}
如果设置 MaxRequestBodySize
为 null
,则等同于取消限制,也就是 [DisableRequestSizeLimit]
的效果。
有时候配置了中间件效果发现没起作用,很有可能和中间件顺序有关,可以通过 .IsReadOnly
属性判断,如果为 true
,说明你的配置无效,只有 false
才有效。
31.7.4 全局配置
IIS
方式:
- 开发环境(IISExpress)
在 Web
启动层(通常是 XXX.Web.Entry
)根目录下创建 web.config
文件,内容如下:
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<system.webServer>
<security>
<requestFiltering>
<requestLimits maxAllowedContentLength="1073741824" />
</requestFiltering>
</security>
</system.webServer>
</configuration>
- 生产环境
通常生产环境 IIS
自动项目添加了 web.config
文件,这时候只需要在 <configuration>
节点下添加下面内容即可:
<system.webServer>
<security>
<requestFiltering>
<requestLimits maxAllowedContentLength="1073741824" />
</requestFiltering>
</security>
</system.webServer>
Kestrel
方式:
未使用 IIS
托管时,ASP.NET Core
默认使用 Kestrel
方式。
// .NET5 方式,在 .ConfigureWebHostDefaults 里面配置
.UseStartup<Startup>()
.UseKestrel(options =>
{
options.Limits.MaxRequestBodySize = null; // 设置 null 就是不限制,具体值就是限制最大多少 M
}
// .NET6 方式,在 progame.cs 文件 var app = builder.Build(); 之后配置
app.Configuration.Get<WebHostBuilder>().ConfigureKestrel(options =>
{
options.Limits.MaxRequestBodySize = null; // 设置 null 就是不限制,具体值就是限制最大多少 M
});
HttpSys
方式:
HTTP.sys
是仅在 Windows
上运行的适用于 ASP.NET Core
的 Web
服务器。 HTTP.sys
是 Kestrel
服务器的替代选择,提供了一些 Kestrel
不提供的功能。
// .NET5 方式同上
.UseHttpSys(options =>
{
options.MaxRequestBodySize = 100_000_000; // 设置 null 就是不限制,具体值就是限制最大多少 M
}
// .NET6 方式同上
31.8 特定文件类型(文件后缀)处理
有时我们在服务器静态资源目录下存放如 .apk
,.m3u8
等文件时,通过 URL
请求返回 404 Not Found
,那是因为默认情况下框架未配置此类文件类型 MIME
类型。
Furion
框架提供了 400
多个常见的文件类型 MIME
,只需要在 Startup.cs
或 Progame.cs
中注册即可,如:
// 为 UseStaticFiles 添加 StaticFileOptions 参数并指定 ContentTypeProvider 属性
app.UseStaticFiles(new StaticFileOptions {
ContentTypeProvider = FS.GetFileExtensionContentTypeProvider()
});
如果配置了还是出现 404
,那么可能访问的文件类型的 MIME
在 Furion
框架中未被包含,这时可自行添加,如:
var contentTypeProvider = FS.GetFileExtensionContentTypeProvider();
contentTypeProvider.Mappings[".文件后缀"] = "MIME 类型"; // 注意文件后缀以 . 开头
// 可多个....
app.UseStaticFiles(new StaticFileOptions {
ContentTypeProvider = contentTypeProvider;
});
31.9 反馈与建议
给 Furion 提 Issue。