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 = 20000000;
   　　 });

二.主机配置值

　　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", "8080")

　　2.7 服务器 (Kestrel) URL

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

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

三.重写(覆盖)配置

         配置可用于配置 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主机