原文:Working with Static Files

作者:Rick Anderson

翻译:刘怡(AlexLEWIS)

校对:谢炀(kiler398)许登洋(Seay)孟帅洋(书缘)

静态文件(static files),诸如 HTML、CSS、图片和 JavaScript 之类的资源会被 ASP.NET Core 应用直接提供给客户端。

查看或下载样式代码

章节:

静态文件服务

静态文件通常位于 web root<content-root>/wwwroot)文件夹下。更多有关 Content root 或 Web root 的信息请访问 intro 。你通常会把项目的当前目录设置为 Content root,这样项目的 web root 就可以在开发阶段被明确。

public static void Main(string[] args)
{
var host = new WebHostBuilder()
.UseKestrel()
.UseContentRoot(Directory.GetCurrentDirectory()) //手工高亮
.UseIISIntegration()
.UseStartup<Startup>()
.Build(); host.Run();
}

静态文件能够被保存在网站根目录下的任意文件夹内,并通过相对根的路径来访问。比方说,当你通过 Visual Studio 创建一个默认的 Web 应用程序项目,在 wwwroot 目录下会多出几个文件夹:cssimages 以及 js 文件夹。形如下例的 URL 能够直接访问 images 目录下的图片:

  • http://<app>/images/<imageFileName>
  • http://localhost:9189/images/banner3.svg

为了能够启用静态文件服务,你必须配置中间件(middleware),把静态文件中间件加入到管道内。静态文件中间件能够通过下述方法来配置:在你的项目中增加 Microsoft.AspNetCore.StaticFiles 包依赖,然后从 Startup.Configure 调用 UseStaticFiles 扩展方法:

public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
app.UseStaticFiles(); //手工高亮
}

app.UseStaticFiles(); 使得 web root(默认为 wwwroot)下的文件可以被访问。随后我将展示如何通过使用 UseStaticFiles 将其他目录下的内容也向外提供服务。

你必须在 project.json 文件中包含 “Microsoft.AspNetCore.StaticFiles”。

注意

web root 的默认目录是 wwwroot,但你可以通过 UseWebRoot 来设置 web root 。具体可参考 intro

假设你有一个有层次结构的项目,你希望其中静态文件的位于 web root 的外部,比如:

  • wwwroot

    • css
    • images
    • ...
  • MyStaticFiles

    • test.png

对于访问 test.png 的请求,可以如此配置静态文件中间件:

public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
app.UseStaticFiles(); app.UseStaticFiles(new StaticFileOptions() //手工高亮
{ //手工高亮
FileProvider = new PhysicalFileProvider( //手工高亮
Path.Combine(Directory.GetCurrentDirectory(), @"MyStaticFiles")), //手工高亮
RequestPath = new PathString("/StaticFiles") //手工高亮
}); //手工高亮
}

在请求 http://<app>/StaticFiles/test.png 时,就能访问到 test.png 文件。

静态文件授权

静态文件模块并 提供授权检查。任何通过该模块提供访问的文件,包括位于 wwwroot 下的文件都是公开的。为了给文件提供授权:

  • 将文件保存在 wwwroot 之外并将目录设置为可被静态文件中间件访问到,同时——
  • 通过一个控制器的 Action 来访问它们,通过授权后返回 FileResult

允许直接浏览目录

目录浏览允许网站用户看到指定目录下的目录和文件列表。基于安全考虑,默认情况下是禁用目录访问功能的(参考 注意事项 )。在 Startup.Configure 中调用 UseDirectoryBrowser 扩展方法可以开启网络应用目录浏览:

public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
app.UseStaticFiles(); // For the wwwroot folder app.UseStaticFiles(new StaticFileOptions()
{
FileProvider = new PhysicalFileProvider(
Path.Combine(Directory.GetCurrentDirectory(), @"wwwroot\images")),
RequestPath = new PathString("/MyImages")
}); app.UseDirectoryBrowser(new DirectoryBrowserOptions()
{
FileProvider = new PhysicalFileProvider(
Path.Combine(Directory.GetCurrentDirectory(), @"wwwroot\images")),
RequestPath = new PathString("/MyImages")
});
}

并且通过从 Startup.ConfigureServices 调用 AddDirectoryBrowser 扩展方法来增加所需服务。

public void ConfigureServices(IServiceCollection services)
{
services.AddDirectoryBrowser();
}

这段代码允许在访问 http://<app>/MyImages 时可浏览 wwwroot/images 文件夹的目录,其中包括该文件夹下的每一个文件与文件夹:

查看关于开放访问目录时的安全隐患 注意事项 一节。

注意两个 app.UseStaticFiles 调用。第一个调用请求 wwwroot 文件夹下的 CSS、图片和 JavaScript,第二个调用通过 http://<app>/MyImages 请求浏览 wwwroot/images 文件夹的目录

public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
app.UseStaticFiles(); // For the wwwroot folder //手工高亮 app.UseStaticFiles(new StaticFileOptions() //手工高亮
{
FileProvider = new PhysicalFileProvider(
Path.Combine(Directory.GetCurrentDirectory(), @"wwwroot\images")),
RequestPath = new PathString("/MyImages")
}); app.UseDirectoryBrowser(new DirectoryBrowserOptions()
{
FileProvider = new PhysicalFileProvider(
Path.Combine(Directory.GetCurrentDirectory(), @"wwwroot\images")),
RequestPath = new PathString("/MyImages")
});
}

默认文档服务

设置默认首页能给你的站点的每个访问者提供一个起始页。为使站点能提供默认页,避免用户输入完整 URI,须在 Startup.Configure 中调用 UseDefaultFiles 扩展方法:

public void Configure(IApplicationBuilder app)
{
app.UseDefaultFiles(); //手工高亮
app.UseStaticFiles();
}

注意

UseDefaultFiles 必须在 UseStaticFiles 之前调用。UseDefaultFiles 只是重写了 URL,而不是真的提供了这样一个文件。你必须开启静态文件中间件(UseStaticFiles)来提供这个文件。

通过 UseDefaultFiles,请求文件夹的时候将检索以下文件:

  • default.htm
  • default.html
  • index.htm
  • index.html

上述列表中第一个被找到的文件将返回给用户(作为该完整 URI 的请求的应答,而此时浏览器 URL 将继续显示用户输入的 URI)。

下述代码展示如何将默认文件名改为 mydefault.html

public void Configure(IApplicationBuilder app)
{
// Serve my app-specific default file, if present.
DefaultFilesOptions options = new DefaultFilesOptions();
options.DefaultFileNames.Clear();
options.DefaultFileNames.Add("mydefault.html");
app.UseDefaultFiles(options);
app.UseStaticFiles();
}

UseFileServer

UseFileServer 包含了 UseStaticFilesUseDefaultFilesUseDirectoryBrowser 的功能。

下面的代码启用了静态文件和默认文件,但不允许直接访问目录:

app.UseFileServer();

下面的代码启用了静态文件、默认文件和目录浏览功能:

app.UseFileServer(enableDirectoryBrowsing: true);

查看直接提供目录访问时的安全风险注意事项。作为一个集合了 UseStaticFilesUseDefaultFilesUseDirectoryBrowser 方法于一体的方法,如果你希望提供 web root 之外存在的文件,你要实例化并配置一个 FileServerOptions 对象传递给 UseFileServer 的参数。比方说在你的应用中有如下层次的目录:

  • wwwroot

    • css
    • images
    • ...
  • MyStaticFiles

    • test.png
    • default.html

使用上面这个层次结构的示例,你可能希望启用静态文件、默认文件以及浏览 MyStaticFiles 目录。下面的代码片段演示了调用一次 FileServerOptions 来完整实现这些功能:

public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
app.UseStaticFiles(); app.UseFileServer(new FileServerOptions() //手工高亮
{ //手工高亮
FileProvider = new PhysicalFileProvider( //手工高亮
Path.Combine(Directory.GetCurrentDirectory(), @"MyStaticFiles")), //手工高亮
RequestPath = new PathString("/StaticFiles"), //手工高亮
EnableDirectoryBrowsing = true //手工高亮
}); //手工高亮
}

如果在你从 Startup.ConfigureServices 请求调用 AddDirectoryBrowser 扩展方法时将 enableDirectoryBrowsing 置为 true,那么:

public void ConfigureServices(IServiceCollection services)
{
services.AddDirectoryBrowser();
}

使用的文件层次结构:

URI Response
http://<app>/StaticFiles/test.png StaticFiles/test.png
http://<app>/StaticFiles MyStaticFiles/default.html

如果在 MyStaticFiles 目录下没有默认命名的文件,则 http://<app>/StaticFiles 将返回目录列表,其中包含可供点击的链接:

注意

UseDefaultFilesUseDirectoryBrowser 将会把末尾不带斜杠的 URL http://<app>/StaticFiles 重新定向到 http://<app>/StaticFiles/ (末尾增加了一个斜杠)。如果末尾不带斜杠,文档内相对 URL 会出错。

FileExtensionContentTypeProvider

FileExtensionContentTypeProvider 类内包含一个将文件扩展名映射到 MIME 内容类型的集合。在下面的例子中,多个文件扩展名注册为已知的 MIME 类型,“.rtf”被替换,“.mp4”被移除。

public void Configure(IApplicationBuilder app)
{
// Set up custom content types -associating file extension to MIME type //手工高亮
var provider = new FileExtensionContentTypeProvider(); //手工高亮
// Add new mappings //手工高亮
provider.Mappings[".myapp"] = "application/x-msdownload"; //手工高亮
provider.Mappings[".htm3"] = "text/html"; //手工高亮
provider.Mappings[".image"] = "image/png"; //手工高亮
// Replace an existing mapping //手工高亮
provider.Mappings[".rtf"] = "application/x-msdownload"; //手工高亮
// Remove MP4 videos. //手工高亮
provider.Mappings.Remove(".mp4"); //手工高亮 app.UseStaticFiles(new StaticFileOptions()
{
FileProvider = new PhysicalFileProvider(
Path.Combine(Directory.GetCurrentDirectory(), @"wwwroot\images")),
RequestPath = new PathString("/MyImages"),
ContentTypeProvider = provider //手工高亮
}); app.UseDirectoryBrowser(new DirectoryBrowserOptions()
{
FileProvider = new PhysicalFileProvider(
Path.Combine(Directory.GetCurrentDirectory(), @"wwwroot\images")),
RequestPath = new PathString("/MyImages")
});
}

查看 MIME 内容类型

非标准的内容类型

ASP.NET 静态文件中间件能够支持超过 400 种已知文件内容类型。如果用户请求一个未知的文件类型,静态文件中间件将返回 HTTP 404(未找到)响应。如果启用目录浏览,该文件的链接将会被显示,但 URI 会返回一个 HTTP 404 错误。

下方代码把不能识别的类型和文件作为图片处理。

public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
app.UseStaticFiles(new StaticFileOptions
{
ServeUnknownFileTypes = true,
DefaultContentType = "image/png"
});
}

根据上面的代码,未知内容类型的文件请求将返回一张图片。

警告

开启 ServeUnknownFileTypes 存在安全风险,请打消这个念头。 FileExtensionContentTypeProvider (下文将解释)提供了更安全的非标准扩展替代。

注意事项

警告

UseDirectoryBrowserUseStaticFiles 可能会泄密。我们推荐你 不要 在生产环境开启目录浏览。要小心哪些被你开启了 UseStaticFilesUseDirectoryBrowser 的目录(使得其子目录都可被访问)。我们建议将公开内容放在诸如 <content root>/wwwroot 这样的目录中,远离应用程序视图、配置文件等。

  • 使用 UseDirectoryBrowserUseStaticFiles 暴露的文件的 URL 是否区分大小写以及字符限制受制于底层文件系统。比方说 Windows 是不区分大小写的,但 macOS 和 Linux 则区分大小写。

  • 托管于 IIS 的 ASP.NET Core 应用程序使用 ASP.NET Core 模块向应用程序转发所有请求,包括静态文件。IIS 静态文件处理程序(IIS Static File Handler)不会被使用,因为在 ASP.NET Core 模块处理之前它没有任何机会来处理请求。

  • 以下步骤可移除 IIS 静态文件处理程序(在服务器层级或网站层级上):

    • 导航到 模块 功能
    • 从列表中选中 StaticFileModule
    • 操作 侧边栏中点击 删除

警告

如果 IIS 静态文件处理程序开启 并且 ASP.NET Core 模块(ANCM)没有被正确配置(比方说 web.config 没有部署),(也能)将会提供静态文件。

  • 代码文件(包括 C# 和 Razor)应该放在应用程序项目的 web root (默认为 wwwroot)之外的地方。这将确保您创建的应用程序能明确隔离客户端侧和服务器侧源代码,此举能防止服务器侧的代码被泄露。

扩展资源

返回目录

ASP.NET Core 中文文档 第三章 原理(3)静态文件处理的更多相关文章

  1. ASP.NET Core 中文文档 第三章 原理(6)全球化与本地化

    原文:Globalization and localization 作者:Rick Anderson.Damien Bowden.Bart Calixto.Nadeem Afana 翻译:谢炀(Kil ...

  2. ASP.NET Core 中文文档 第三章 原理(1)应用程序启动

    原文:Application Startup 作者:Steve Smith 翻译:刘怡(AlexLEWIS) 校对:谢炀(kiler398).许登洋(Seay) ASP.NET Core 为你的应用程 ...

  3. ASP.NET Core 中文文档 第三章 原理(13)管理应用程序状态

    原文:Managing Application State 作者:Steve Smith 翻译:姚阿勇(Dr.Yao) 校对:高嵩 在 ASP.NET Core 中,有多种途径可以对应用程序的状态进行 ...

  4. ASP.NET Core 中文文档 第三章 原理(2)中间件

    原文:Middleware 作者:Steve Smith.Rick Anderson 翻译:刘怡(AlexLEWIS) 校对:许登洋(Seay) 章节: 什么是中间件 用 IApplicationBu ...

  5. ASP.NET Core 中文文档 第三章 原理(10)依赖注入

    原文:Dependency Injection 作者:Steve Smith 翻译:刘浩杨 校对:许登洋(Seay).高嵩 ASP.NET Core 的底层设计支持和使用依赖注入.ASP.NET Co ...

  6. ASP.NET Core 中文文档 第三章 原理(11)在多个环境中工作

    原文: Working with Multiple Environments 作者: Steve Smith 翻译: 刘浩杨 校对: 孟帅洋(书缘) ASP.NET Core 介绍了支持在多个环境中管 ...

  7. ASP.NET Core 中文文档 第三章 原理(17)为你的服务器选择合适版本的.NET框架

    原文:Choosing the Right .NET For You on the Server 作者:Daniel Roth 翻译:王健 校对:谢炀(Kiler).何镇汐.许登洋(Seay).孟帅洋 ...

  8. ASP.NET Core 中文文档 第三章 原理(7)配置

    原文:Configuration 作者:Steve Smith.Daniel Roth 翻译:刘怡(AlexLEWIS) 校对:孟帅洋(书缘) ASP.NET Core 支持多种配置选项.应用程序配置 ...

  9. ASP.NET Core 中文文档 第三章 原理(8)日志

    原文:Logging 作者:Steve Smith 翻译:刘怡(AlexLEWIS) 校对:何镇汐.许登洋(Seay) ASP.NET Core 内建支持日志,也允许开发人员轻松切换为他们想用的其他日 ...

随机推荐

  1. JS核心系列:浅谈原型对象和原型链

    在Javascript中,万物皆对象,但对象也有区别,大致可以分为两类,即:普通对象(Object)和函数对象(Function). 一般而言,通过new Function产生的对象是函数对象,其他对 ...

  2. MVVM模式解析和在WPF中的实现(六) 用依赖注入的方式配置ViewModel并注册消息

    MVVM模式解析和在WPF中的实现(六) 用依赖注入的方式配置ViewModel并注册消息 系列目录: MVVM模式解析和在WPF中的实现(一)MVVM模式简介 MVVM模式解析和在WPF中的实现(二 ...

  3. nw.js桌面软件开发系列 第0.1节 HTML5和桌面软件开发的碰撞

    第0.1节 HTML5和桌面软件开发的碰撞 当我们谈论桌面软件开发技术的时候,你会想到什么?如果不对技术本身进行更为深入的探讨,在我的世界里,有这么多技术概念可以被罗列出来(请原谅我本质上是一个Win ...

  4. C++11特性——变量部分(using类型别名、constexpr常量表达式、auto类型推断、nullptr空指针等)

    #include <iostream> using namespace std; int main() { using cullptr = const unsigned long long ...

  5. zookeeper源码分析之一服务端启动过程

    zookeeper简介 zookeeper是为分布式应用提供分布式协作服务的开源软件.它提供了一组简单的原子操作,分布式应用可以基于这些原子操作来实现更高层次的同步服务,配置维护,组管理和命名.zoo ...

  6. Go web开发初探

    2017年的第一篇博客,也是第一次写博客,写的不好,请各位见谅. 本人之前一直学习java.java web,最近开始学习Go语言,所以也想了解一下Go语言中web的开发方式以及运行机制. 在< ...

  7. canvas与html5实现视频截图功能

    这段时间一直在研究canvas,突发奇想想做一个可以截屏视频的功能,然后把图片拉去做表情包,哈哈哈哈哈哈~~ 制作方法: 1.在页面中加载视频 在使用canvas制作这个截图功能时,首先必须保证页面上 ...

  8. 不懂CSS的后端难道就不是好程序猿?

    由于H5在移动端的发展如日中天,现在大部分公司对高级前端需求也是到处挖墙角,前端薪资也随之水涨船高,那公司没有配备专用的前端怎么办呢? 作为老板眼中的“程序猿” 前端都不会是非常无能的表现,那作为后端 ...

  9. [原][Docker]特性与原理解析

    Docker特性与原理解析 文章假设你已经熟悉了Docker的基本命令和基本知识 首先看看Docker提供了哪些特性: 交互式Shell:Docker可以分配一个虚拟终端并关联到任何容器的标准输入上, ...

  10. "NHibernate.Exceptions.GenericADOException: could not load an entity" 解决方案

     今天,测试一个项目的时候,抛出了这个莫名其妙的异常,然后就开始了一天的调试之旅... 花了很长时间,没有从代码找出任何问题... 那么到底哪里出问题呢? 根据下面那段长长的错误日志: -- ::, ...