(15)ASP.NET Core Web主机(IWebHostBuilder)
1.前言
asp.net core应用程序可以配置和启动主机(host)。主机负责应用程序启动和生存期管理,配置服务器和请求处理管道。主机还可以设置日志记录、依赖关系注入和配置。而host主机又包括web主机(iwebhostbuilder)和通用主机(ihostbuilder)。该章节主要介绍了用于托管web应用的web主机。对于其他类型的应用,请使用通用主机。
2.设置主机
创建使用iwebhostbuilder实例的主机。通常在应用程序的入口点来执行main方法。在项目模板中,main位于program.cs。典型应用默认调用createdefaultbuilder来开始创建主机:
public class program { public static void main(string[] args) { createwebhostbuilder(args).build().run(); } public static iwebhostbuilder createwebhostbuilder(string[] args) => webhost.createdefaultbuilder(args) .usestartup<startup>(); }
2.1执行下列任务
调用createdefaultbuilder的代码位于名为createwebhostbuilder的方法中,这让它区分于 main中对生成器对象调用run的代码。createdefaultbuilder执行下列任务:
●使用应用程序的托管配置提供应用程序将kestrel服务器配置为web服务器。
●将内容根设置为由 directory.getcurrentdirectory返回的路径。
●通过以下对象加载主机配置:
○前缀为aspnetcore_的环境变量(例如,aspnetcore_environment)。
○命令行参数。
●按以下顺序加载应用程序配置:
○appsettings.json。
○appsettings.{environment}.json。
○应用在使用入口程序集的development环境中运行时的机密管理器。
○环境变量。
○命令行参数。
●配置控制台和调试输出的日志记录。日志记录包含appsettings.json或appsettings.{environment}.json文件的日志记录配置部分中指定的日志筛选规则。
●使用asp.net core模块在iis后面运行时,createdefaultbuilder会启用iis集成,这会配置应用程序的基址和端口。iis集成还配置应用程序以捕获启动错误。
●如果应用环境为“开发(development)”,请将serviceprovideroptions.validatescopes设为true。
2.2重写和增强定义的配置
configureappconfiguration、configurelogging以及iwebhostbuilder的其他方法和扩展方法可重写和增强createdefaultbuilder定义的配置。下面是一些示例:
●configureappconfiguration:用于指定应用的其他iconfiguration。下面的configureappconfiguration调用添加委托,以在appsettings.xml文件中添加应用配置,该示例在core系列第11章节有演示。可多次调用configureappconfiguration。请注意,此配置不适用于主机(例如,服务器url或环境)。
public static iwebhostbuilder createwebhostbuilder(string[] args) => webhost.createdefaultbuilder(args) .configureappconfiguration((hostingcontext, config) => { config.addxmlfile("appsettings.xml", optional: true, reloadonchange: true); });
●configurelogging:configurelogging调用添加委托,将最小日志记录级别 (setminimumlevel)配置为loglevel.warning。此设置重写createdefaultbuilder在appsettings.development.json和appsettings.production.json中配置,分别为loglevel.debug和loglevel.error。可多次调用 configurelogging。
public static iwebhostbuilder createwebhostbuilder(string[] args) => webhost.createdefaultbuilder(args) .configurelogging(logging => { logging.setminimumlevel(loglevel.warning); });
●configurekestrel:调用configurekestrel来重写createdefaultbuilder在配置kestrel时建立的30,000,000字节默认limits.maxrequestbodysize:
public static iwebhostbuilder createwebhostbuilder(string[] args) => webhost.createdefaultbuilder(args) .configurekestrel((context, options) => { options.limits.maxrequestbodysize = 20000000; });
设置主机时,可以提供配置和configureservices方法。如果指定startup类,必须定义configure方法。
3.主机配置值
webhostbuilder依赖于以下的方法设置主机配置值:
●主机生成器配置,其中包括格式aspnetcore_{configurationkey}的环境变量。例如 aspnetcore_environment。
●usecontentroot和useconfiguration等扩展。
●usesetting和关联键。使用usesetting设置值时,该值设置为无论何种类型的字符串。
3.1应用程序键(名称)
在主机构造期间调用usestartup或configure时,会自动设置 ihostingenvironment.applicationname属性。该值设置为包含应用入口点的程序集的名称。要显式设置值,请使用webhostdefaults.applicationkey(环境变量:aspnetcore_applicationname):
public void configure(iapplicationbuilder app, ihostingenvironment env) { //应用程序默认名称为:coreweb (也就是项目名称) string an = env.applicationname; ...
} public static iwebhostbuilder createwebhostbuilder(string[] args) => webhost.createdefaultbuilder(args).usestartup<startup>() .usesetting(webhostdefaults.applicationkey, "coreweb");
3.2捕获启动错误
此设置控制启动错误的捕获。当false时,启动期间出错导致主机退出。当true时,主机在启动期间捕获异常并尝试启动服务器(环境变量:aspnetcore_capturestartuperrors)。
webhost.createdefaultbuilder(args) .capturestartuperrors(true)
3.3内容根
此设置确定asp.net core开始搜索内容文件,如mvc视图等。内容根也用作web根设置的基路径。如果路径不存在,主机将无法启动(环境变量:aspnetcore_contentroot)。
webhost.createdefaultbuilder(args) .usecontentroot("c:\\<content-root>")
3.4详细错误
确定是否应捕获详细错误。启用(或当环境设置为development)时,应用捕获详细的异常(环境变量:aspnetcore_detailederrors)。
webhost.createdefaultbuilder(args) .usesetting(webhostdefaults.detailederrorskey, "true")
3.5环境
设置应用程序的环境。环境可以设置为任何值。框架定义的值包括development、staging和production。值不区分大小写。默认情况下,从aspnetcore_environment环境变量读取环境。使用visual studio时,可能会在launchsettings.json文件中设置环境变量。有关于环境详情信息,可以移步到core系列第10章节有参阅(环境变量:aspnetcore_environment)。
webhost.createdefaultbuilder(args) .useenvironment(environmentname.development)
3.6https端口
设置https重定向端口。用于强制实施https(环境变量:aspnetcore_https_port)。
webhost.createdefaultbuilder(args) .usesetting("https_port", "8080")
3.7服务器(kestrel) url
指示ip地址或主机地址,其中包含服务器应针对请求侦听的端口和协议。设置为服务器应响应的以分号分隔 (;) 的url前缀列表。例如 http://localhost:123。使用“*”指示服务器应针对请求侦听的使用特定端口和协议(例如 http://*:5000)的ip地址或主机名。协议(http://或https://)必须包含每个url。不同的服务器支持的格式有所不同(环境变量:aspnetcore_urls)。
webhost.createdefaultbuilder(args) .useurls("https://*:5000;https://localhost:5001;https://hostname:5002")
4.重写配置
使用配置可以配置web主机。在下面的示例中,主机配置是根据需要在hostsettings.json文件中指定。命令行参数可能会重写从hostsettings.json文件加载的任何配置。生成的配置(在config中)用于通过useconfiguration配置主机。
新建一个hostsettings.json文件,内容如下:
{ "urls": "https://*:5005" }
public static iwebhostbuilder createwebhostbuilder(string[] args) { //iconfigurationbuilder的配置主机 var config = new configurationbuilder() .setbasepath(directory.getcurrentdirectory()) //主机配置在hostsettings.json文件中指定 .addjsonfile("hostsettings.json", optional: true) //输入的命令行参数可能会重写从hostsettings.json文件加载的任何配置 .addcommandline(args) .build(); return webhost.createdefaultbuilder(args) .useurls("https://*:5001") .useconfiguration(config) .configure(app => { //生成的配置委托函数 app.run(context => context.response.writeasync("hello, world!")); }); }
上述代码描述意思是若要指定在特定的url上运行的主机,所需的值可以在执行dotnet运行时从命令提示符传入。命令行参数重写hostsettings.json文件中的urls值,且服务器侦听端口8080:
dotnet run --urls "http://*:8080"
主机启动时,先用hostsettings.json config重写useurls提供的urls参数配置,然后再用命令行参数config重写hostsettings.json config的urls参数配置。
5.管理主机
管理主题启动方式有run和start两种。run方法启动web应用程序并阻止调用线程,直到关闭主机。start方法通过调用自身以非阻止方式运行主机。
//run createwebhostbuilder(args).build().run();
//start:非阻止方式,所有必须加上readline createwebhostbuilder(args).build().start(); console.readline();
6.ihostingenvironment接口
ihostingenvironment接口提供有关应用的web承载环境的信息。使用构造函数注入获取 ihostingenvironment以使用其属性和扩展方法:
//示例1: public class customfilereader { private readonly ihostingenvironment _env; public customfilereader(ihostingenvironment env) { _env = env; } public string readfile(string filepath) { var fileprovider = _env.webrootfileprovider; // process the file here } }
可以用于在启动时基于环境配置应用程序或者将ihostingenvironment注入到startup构造函数,用于configureservices:
//示例2: public class startup { public startup(ihostingenvironment env) { hostingenvironment = env; } public ihostingenvironment hostingenvironment { get; } public void configureservices(iservicecollection services) { if (hostingenvironment.isdevelopment()) { // development configuration } else { // staging/production configuration } var contentrootpath = hostingenvironment.contentrootpath; } }
ihostingenvironment服务还可以直接注入到configure方法以设置处理管道:
//示例3: public void configure(iapplicationbuilder app, ihostingenvironment env) { if (env.isdevelopment()) { // in development, use the developer exception page app.usedeveloperexceptionpage(); } else { // in staging/production, route exceptions to /error app.useexceptionhandler("/error"); } var contentrootpath = env.contentrootpath; }
创建自定义中间件(要了解中间件的同学们,可以移步到第四章节学习)时可以将ihostingenvironment 注入invoke方法:
public async task invoke(httpcontext context, ihostingenvironment env) { if (env.isdevelopment()) { // configure middleware for development } else { // configure middleware for staging/production } var contentrootpath = env.contentrootpath; }
7.iapplicationlifetime接口
iapplicationlifetime允许后启动和关闭活动。接口上的三个属性是用于注册action方法(用于定义启动和关闭事件)的取消标记。
取消标记 |
触发条件 |
applicationstarted |
主机已完全启动。 |
applicationstopped |
主机正在完成正常关闭。应处理所有请求。 关闭受到阻止,直到完成此事件。 |
applicationstopping |
主机正在执行正常关闭。仍在处理请求。关闭受到阻止,直到完成此事件。 |
public class startup { public void configure(iapplicationbuilder app, iapplicationlifetime applifetime) { applifetime.applicationstarted.register(onstarted); applifetime.applicationstopping.register(onstopping); applifetime.applicationstopped.register(onstopped); console.cancelkeypress += (sender, eventargs) => { applifetime.stopapplication(); // don't terminate the process immediately, wait for the main thread to exit gracefully. eventargs.cancel = true; }; } private void onstarted() { // perform post-startup activities here } private void onstopping() { // perform on-stopping activities here } private void onstopped() { // perform post-stopped activities here } }
stopapplication是请求应用终止的意思。以下类在调用类的shutdown方法时使用stopapplication正常关闭应用:
public class myclass { private readonly iapplicationlifetime _applifetime; public myclass(iapplicationlifetime applifetime) { _applifetime = applifetime; } public void shutdown() { _applifetime.stopapplication(); } }
8.作用域验证
如果应用环境为“开发(development)”,则createdefaultbuilder将serviceprovideroptions.validatescopes设为true。若将validatescopes设为true,默认服务提供应用程序会执行检查来验证以下内容:
●作用域服务不能直接或间接地从根服务提供者解析。
●作用域服务不会直接或间接地注入到单例中(服务的生命周期)。
若要始终验证作用域(包括在生命周期环境中验证),请使用主机生成器上的 usedefaultserviceprovider配置serviceprovideroptions:
webhost.createdefaultbuilder(args) .usedefaultserviceprovider((context, options) => { options.validatescopes = true; })
参考文献:
asp.net core web主机
上一篇: 如何把相片拍得好看?拍摄食物的小技巧介绍
下一篇: ZooKeeper API实战创建客户端
推荐阅读
-
(二)快速搭建 ASP.net core Web 应用
-
ASP.NET Core Web API 最佳实践指南
-
ASP.NET Core Web 应用程序开发期间部署到IIS自定义主机域名并附加到进程调试
-
Asp.Net Core 学习教程1、初始.Net Core与VS Code 第一个web程序
-
或许是你应该了解的一些 ASP.NET Core Web API 使用小技巧
-
ASP.NET Core2基于RabbitMQ对Web前端实现推送功能
-
【ASP.NET Core】从向 Web API 提交纯文本内容谈起
-
循序渐进学.Net Core Web Api开发系列【15】:应用安全
-
asp.net core web api 生成 swagger 文档
-
VS2017怎么创建创建空的ASP.NET Core Web项目?