asp.net core 系列 16 Web主机 IWebHostBuilder

一.概述

在asp.net core中,Host主机负责应用程序启动和生存期管理。host主机包括Web 主机(IWebHostBuilder)和通用主机(IHostBuilder)。Web 主机是适用于托管 Web 应用;通用主机(ASP.NET Core 2.1 或更高版本)是适用于托管非 Web 应用;在未来的版本中,通用主机将适用于托管任何类型的应用,包括 Web 应用。 通用主机最终将取代 Web 主机。本篇先来了解ASP.NET Core Web主机。

  

  1.1 设置Web主机以及执行的任务

    创建使用 IWebHostBuilder 实例的主机。 通常在应用的入口点 Main 方法中执行。 在项目模板中,Main 位于 Program.cs。

         public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>();

    下面详细说下CreateDefaultBuilder 执行的下列任务:

    (1) 将内置的 Kestrel 服务器配置为 Web 服务器。

    (2) 设置content root 内容根路径,并由 Directory.GetCurrentDirectory 返回的路径。

    (3) 通过以下加载主机配置:

      前缀为 ASPNETCORE_ 的环境变量(例如,ASPNETCORE_ENVIRONMENT)。

      命令行参数。

    (4) 按以下顺序加载应用配置

      appsettings.json。

appsettings.{Environment}.json。

应用在使用入口程序集的 Development 环境中运行时的机密管理器。

环境变量。

命令行参数。

    (5) 设置console and debug 输出的日志记录。在 appsettings.json 或 appsettings.{Environment}.json 文件的日志记录配置部分(Logging)中指定的日志筛选规则。

    (6)  ASP.NET Core 模块使用IIS托管运行时,CreateDefaultBuilder 会启用 IIS 集成,这会配置应用的基址和端口。 IIS 集成还配置应用以捕获启动错误。

    (7) 如果应用环境为“开发”,请将 ServiceProviderOptions.ValidateScopes 设为 true。

 

  1.2 Web主机的扩展配置

     IWebHostBuilder下的ConfigureAppConfiguration、ConfigureLogging 以及其他方法可重写(第三大点讲)和增强 CreateDefaultBuilder 定义的配置。 下面是一些示例:

    (1) ConfigureAppConfiguration

      ConfigureAppConfiguratio用于指定应用的 IConfiguration。下面的 ConfigureAppConfiguration 调用添加委托,以在 appsettings.xml 文件中添加应用配置。 可多次调用 ConfigureAppConfiguration。具体参照 ”asp.net core 系列 10 配置configuration“ 。

      WebHost.CreateDefaultBuilder(args)
   .ConfigureAppConfiguration((hostingContext, config) =>
   {
   config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
  })

    (2) ConfigureLogging

      ConfigureLogging调用添加委托,以将最小日志记录级别 (SetMinimumLevel) 配置为 LogLevel.Warning。 此设置重写 CreateDefaultBuilder 在 appsettings.Development.json 和 appsettings.Production.json 中配置的设置,分别为 LogLevel.Debug 和 LogLevel.Error。 可多次调用 ConfigureLogging。具体参照 “asp.net core 系列 13 日志”。

      WebHost.CreateDefaultBuilder(args)
   .ConfigureLogging(logging =>
   {
   logging.SetMinimumLevel(LogLevel.Warning);
   })

    (3) ConfigureKestrel

      下面调用 ConfigureKestrel 来重写 CreateDefaultBuilder 在配置 Kestrel 时默认的 30,000,000 字节,大约为28.6MB。MaxRequestBodySize是获取或设置任何请求主体的最大允许大小(以字节为单位)。设置为null时,最大请求正文大小不受限制。

      WebHost.CreateDefaultBuilder(args)
  .ConfigureKestrel((context, options) =>
   {
   options.Limits.MaxRequestBodySize = ;
   });

二.主机配置值

  WebHostBuilder 依赖于以下的方法设置主机配置值:

     (1)主机生成器配置,其中包括格式 ASPNETCORE_{configurationKey} 的环境变量。 例如 ASPNETCORE_ENVIRONMENT。

    (2)UseContentRoot 和 UseConfiguration 等扩展。

    (3)UseSetting 和关联键。 使用 UseSetting 设置值时,该值设置为无论何种类型的字符串。

  2.1  Application Key (Name)

    在主机构造期间调用 UseStartup 或 Configure 时,会自动设置 IHostingEnvironment.ApplicationName 属性。 该默认值设置为应用入口点的程序集的名称。 要显式设置值,请使用 WebHostDefaults.ApplicationKey。环境变量:ASPNETCORE_APPLICATIONNAME

      public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
//应用程序默认名称为:MyNetCoreStudy (也就是项目名称)
string s = env.ApplicationName;
//..
     //显示设置
     WebHost.CreateDefaultBuilder(args)
  .UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")

  2.2捕获启动错误

    启动错误的捕获。 默认为 false, 启动期间出错,主机退出。当 true 时,主机在启动期间捕获异常并尝试启动服务器。当程序使用 Kestrel 在 IIS 后方运行,默认值是 true。环境变量:ASPNETCORE_CAPTURESTARTUPERRORS

      WebHost.CreateDefaultBuilder(args)
  .CaptureStartupErrors(true)

  2.3 内容根

    设置确定web根目录的基路径。用于搜索的内容文件,比如mvc的视图。默认为应用程序集所在的文件夹。环境变量:ASPNETCORE_CONTENTROOT。

        WebHost.CreateDefaultBuilder(args)
.UseContentRoot("c:\\<content-root>")

  2.4 详细错误  

    确定是否应捕获详细错误。默认值:false。启用为true时,会捕获详细的异常。或当环境设置为 Development时也会捕获详细的异常。 环境变量 ASPNETCORE_DETAILEDERRORS

    WebHost.CreateDefaultBuilder(args)
.UseSetting(WebHostDefaults.DetailedErrorsKey, "true")

  2.5 环境  

    设置应用的环境。默认值:Production。 使用 Visual Studio 时,可能会在 launchSettings.json 文件中设置环境变量。环境变量:ASPNETCORE_ENVIRONMENT

        WebHost.CreateDefaultBuilder(args)
.UseEnvironment(EnvironmentName.Development)

  2.6 HTTPS 端口

    设置 HTTPS 重定向端口。 用于强制实施 HTTPS。 环境变量:ASPNETCORE_HTTPS_PORT。

      WebHost.CreateDefaultBuilder(args)
.UseSetting("https_port", "")

  2.7 服务器 (Kestrel) URL

    指示 IP 地址或主机地址,host启动时侦听。默认: http://localhost:5000。设置为服务器响应的以分号分隔 (;) 的 URL 前缀列表。环境变量:ASPNETCORE_URLS

    WebHost.CreateDefaultBuilder(args)
   .UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002")

asp.net core 系列 16 Web主机 IWebHostBuilder

三.重写(覆盖)配置

配置可用于配置 Web 主机。 在下面的示例中,主机配置是根据需要在 hostsettings.json 文件中指定。 命令行参数可能会重写从 hostsettings.json 文件加载的任何配置。 生成的配置(在 config 中)用于通过 UseConfiguration 配置主机。 IWebHostBuilder 配置会添加到应用配置中。

   hostsettings.json  { urls: "http://*:5005" }
        public static IWebHostBuilder CreateWebHostBuilder(string[] args)
{
//IConfiguration的配置主机
var config = new ConfigurationBuilder()
.SetBasePath(Directory.GetCurrentDirectory())
//主机配置在hostsettings.json 文件中指定
.AddJsonFile("hostsettings.json", optional: true)
// 命令行参数可能会重写从 hostsettings.json 文件加载的任何配置
.AddCommandLine(args)
.Build(); return WebHost.CreateDefaultBuilder(args)
.UseUrls("http://*:5000")
//config重写UseUrls
.UseConfiguration(config)
.Configure(Handle1);
} private static void Handle1(IApplicationBuilder app)
{
app.Run(async context =>
{
await context.Response.WriteAsync("Handle1 Test 1");
});
}

  如果在执行 dotnet 运行时从命令提示符传入。 命令行参数,将重写 hostsettings.json 文件中的 urls 值,且服务器侦听端口 8080。

  dotnet run --urls "http://*:8080"

    启动时,url参数重写的的关系是:UseUrls被hostsettings.json重写, hostsettings.json又被命令行参数重写。

四 .管理主机

对于启动主机有二种方式:run和start。使用Run 方法启动 Web 应用是阻止调用线程,直到显示关闭主机。使用start方法是非阻止方式运行主机。具体用法请查看官网。

    // Runs a web application and block the calling thread until host shutdown.
CreateWebHostBuilder(args).Build().Run();
     CreateWebHostBuilder(args).Build().Start();
//非阻止方式,所有必须加上ReadLine,
Console.ReadLine();

五. IHostingEnvironment 接口

  IHostingEnvironment 接口提供有关应用的 Web 承载环境的信息,默认是将 IHostingEnvironment 注入到 Startup构造函数,在Configure方法中引用。下面使用构造函数注入获取 IHostingEnvironment 以使用其属性和扩展方法:

public class CustomFileReader
{
private readonly IHostingEnvironment _env; public CustomFileReader(IHostingEnvironment env)
{
_env = env;
} public string ReadFile(string filePath)
{
//返回IFileProvider,指向 WebRootPath
var fileProvider = _env.WebRootFileProvider;
// Process the file here
}
}

  创建自定义中间件时可以将 IHostingEnvironment 注入 Invoke 方法(参考asp.net core 系列 15 中间件):

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;
}

六.IApplicationLifetime 接口

IApplicationLifetime 用于应用程序在启动和关闭时的活动。 接口上的三个属性是用于注册 Action 方法。用于定义启动和关闭事件标记。

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
}
}

七. 作用域验证

  如果应用环境为“开发”,则 CreateDefaultBuilder 将 ServiceProviderOptions.ValidateScopes 设为 true。若将 ValidateScopes 设为 true,默认服务提供程序会执行检查来验证以下内容:

  作用域服务不能直接或间接地从根服务提供者解析。

   作用域服务不会直接或间接地注入到单例中(服务的生存期)。

  WebHost.CreateDefaultBuilder(args)
  .UseDefaultServiceProvider((context, options) => {
   options.ValidateScopes = true;
  })

  当true将执行检查,验证作用域服务,永远不会从根提供程序解析(不从*容器中获取scoped生命周期服务,所有服务都是注入到容器中IServiceCollection)。 mark:没有完全理解,以后再说。

 参考文献:

    官方文档:ASP.NET Core Web主机

   

上一篇:MAC下安装automake autoconf工具


下一篇:FABRIC单机开发者模式启动