.NET Web 宿主（Web Host）【上】

此为系列文章，对MSDN ASP.NET Core 的官方文档进行系统学习与翻译。其中或许会添加本人对 ASP.NET Core 的浅显理解。

ASP.NET Core应用程序配置并启动了一个宿主。这个宿主负责app的启动以及生命周期管理。在最小的情况下，这个宿主配置了一个服务以及一个请求处理管道。除此之外，这个宿主也可以建立日志，依赖注入，配置。

这篇文章包含了Web宿主，其仍旧是可用的，不过仅作为向后兼容使用。对于所有的app类型，我们推荐使用Generic Host。

建立一个宿主

使用IWebHostBuilder的一个实例来建立web 宿主。典型的，其会在app的入口点Main函数执行以建立web宿主。

在项目模板中，Main函数包含在Program.cs中，一个典型的app会调用CreateDefaultBuilder 来开始建立一个web 宿主：

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

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

调用CreateDefaultBuilder方法的代码是名为CreateWebHostBuilder的方法中，它将其与Main函数中的代码分离开，而在Main函数中，我们调用了建造者对象上的Run方法。如果你使用Entity Framework Core tools这个工具的话，这种分离是必须的，这个工具期望找到一个CreateWebHostBuilder方法，从而它们可以在设计时候进行调用来配置宿主，而不用运行app。另一个替代的方法是使用IDesignTimeDbContextFactory。更多信息，请参考Design-time DbContext Creation。

CreateDefaultBuilder执行了以下任务：

使用app的宿主配置提供程序将Kestrel服务器配置为web服务器。关于Kestrel服务器的默认选项，请参考Kestrel web server implementation in ASP.NET Core。
将内容根设置为Directory.GetCurrentDirectory返回的路径。
从以下位置加载宿主配置：带有“ASPNETCORE_”前缀的环境变量（比如ASPNETCORE_ENVIRONMENT），命令行参数。
按顺序从以下位置加载app配置：appsettings.json，appsettings.{Environment}.json，Secret Manager（当app使用入口点程序集运行在开发环境中时），环境变量，命令行参数。
为控制台和调试输出配置日志。日志包含了在appsettings.json 或appsettings.{Environment}.json文件的日志配置部分指定的日志过滤规则。
当使用ASP.NET Core模块运行在IIS上时，CreateDefaultBuilder便启用了IIS集成。其配置了app的基地址以及端口。IIS集成同样配置app以捕获startup时的错误。关于IIS的默认选项，请参考Host ASP.NET Core on Windows with IIS。
如果app的环境是开发环境时，将ServiceProviderOptions.ValidateScopes设置为true。更多信息，请参考Scope validation。

被CreateDefaultBuilder定义的配置可以被ConfigureAppConfiguration，ConfigureLogging，以及IWebHostBuilder的其他方法和扩展方法所重载和参数化。如下几个示例所示：

ConfigureAppConfiguration被用来为app指定额外的IConfiguration。以下对于ConfigureAppConfiguration的调用添加了一个委托来包含在appsettings.xml文件中的app配置。ConfigureAppConfiguration 可以被多次调用。请注意这个配置不会应用给宿主（比如，服务URLs或者环境）。更多信息，请参考Host configuration values章节。

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

如下对于ConfigureLogging的调用添加了一个委托以配置最小的日志级别为LogLevel.Warning。这个设置重写了由CreateDefaultBuilder在appsettings.Development.json (LogLevel.Debug) 和 appsettings.Production.json 文件中所做的配置。ConfigureLogging 也可以被调用多次。
```
WebHost.CreateDefaultBuilder(args)
    .ConfigureLogging(logging => 
    {
        logging.SetMinimumLevel(LogLevel.Warning);
    })
    ...
```
以下对于ConfigureKestrel的调用重写了默认的Limits.MaxRequestBodySize 值30,000,000，其在CreateDefaultBuilder配置Kestrel时被建立。

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

内容根决定了宿主从哪里开始搜索内容文件，比如MVC试图文件。当app从项目的根文件夹开始运行时，项目的根文件夹便被用做内容根。这是在Visual Studio 和dotnet new templates 的默认用法。

关于app配置的更多信息，请参考Configuration in ASP.NET Core。

注意：作为对于使用静态CreateDefaultBuilder方法的一个替代选项，从WebHostBuilder创建宿主是ASP.NET Core 2.x支持的方法。

当建立一个宿主时，可以提供Configure 和 ConfigureServices 方法。如果指定了一个Startup类，那么它必须定义Configure方法。获取更多信息，请参考App startup in ASP.NET Core。对于ConfigureServices的多个调用会追加在另外一个调用之上。而在WebHostBuilder上，对Configure或者UseStartup的多次调用会替换掉之前的设置。

宿主配置值

WebHostBuilder 依赖于以下方式来设置宿主配置值：

宿主构造器配置，其包含带有如下格式的环境变量，ASPNETCORE_{configurationKey}。比如 ASPNETCORE_ENVIRONMENT。
像是UseContentRoot 以及 UseConfiguration 这样的扩展（请参考Override configuration 章节）。
UseSetting 以及相关联的键值。当使用UseSetting设置一个值，这个值会以字符串的形式被设置，而不管其实际的类型。

最终宿主都会使用任何一个选项了来设置一个值。更多信息，请参考下一章节的Override configuration。

Application Key（Name）

在构建宿主时，当调用UseStartup或者Configure时，这个属性IWebHostEnvironment.ApplicationName会被自动设置。这个值会被设置为包含程序入口点的程序集的名称。为了显示设置此值，请使用WebHostDefaults.ApplicationKey。

键：applicationName

类型：string

默认值：包含程序入口点的程序集的名称

环境变量：ASPNETCORE_APPLICATIONNAME

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")

Capture Startup Errors

这个设置控制着对startup 错误的捕获。

键：captureStartupErrors

类型：bool

默认值：默认值为false，除非app运行在IIS后的Kestrel服务上，此时默认值为true

设置方式：CaptureStartupErrors

环境变量：ASPNETCORE_CAPTURESTARTUPERRORS

当为false时，startup中的错误会导致宿主依然存在，当设置为true时，宿主会捕获startup的异常并试图启动服务。

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

Content Root

这个设置决定了从哪儿ASP.NET Core开始搜索内容文件。

键：contentRoot

类型：string

默认值：默认值为app程序集所在的文件夹

设置方式：UseContentRoot

环境变量：ASPNETCORE_CONTENTROOT

内容根也被用作web root 的基地址。如果内容根地址不存在，那么宿主便不会启动。

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

更多信息，请参考：

Detailed Errors

决定着详细错误信息是否应该被捕获。

键：detailedErrors

类型：bool

默认值：false

设置方式：UseSetting

环境变量：ASPNETCORE_DETAILEDERRORS

当启用时（或者当环境被设置为开发环境时），app会捕获到详细的异常信息。

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

Environment

设置app的环境变量。

键：environment

类型：string

默认值：Production

设置方式：UseEnvironment

环境变量：ASPNETCORE_ENVIRONMENT

Host Startup Assemblies

设置app的宿主启动程序集（hosting startup assemblies）。

键：hostingStartupAssemblies

类型：string

默认值：空字符串

设置方式：UseSetting

环境变量：ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

会在启动时候加载以分号形式隔开程序集。它们作为宿主启动程序集。

虽然配置值默认为空字符串，然而宿主启动程序集往往包含了app的程序集。当我们提供了宿主启动程序集，它们便会被添加到app的程序集中，当app在启动时构建它的通用服务时，这些程序集便会被加载。

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2")

HTTPS Port

设置HTTPS重定向端口。用在enforcing HTTPS中。

键：https_port

类型：string

默认值：没有设置默认值

设置方式：UseSetting

环境变量：ASPNETCORE_HTTPS_PORT

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

Hosting Startup Exclude Assemblies

启动时需要排除的以分号形式隔开的宿主启动程序集字符串。

键：hostingStartupExcludeAssemblies

类型：string

默认值：空字符串

设置方式：UseSetting

环境变量：ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;aszhishisembly2")

Prefer Hosting URLs

指示宿主是否需要监听使用WebHostBuilder配置的URRs，而不是那些使用IServer实现配置的URs。

键：preferHostingUrls

类型：bool

默认值：true

设置方式：PreferHostingUrls

环境变量：ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(false)

Prevent Hosting Startup

阻止宿主启动程序的自动加载，包含那些app配置的宿主启动程序集。更多信息，请参考Use hosting startup assemblies in ASP.NET Core。

键：preventHostingStartup

类型：bool

默认值：false

设置方式：UseSetting

环境变量：ASPNETCORE_PREVENTHOSTINGSTARTUP

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

Server URLs

指示了一个服务应该监听请求的IP地址或者是带有端口号和协议的主机地址。

键：urls

类型：string

默认值：http://localhost:5000

设置方式：UseUrls

环境变量：ASPNETCORE_URLS

设置为分割的URL前缀列表，服务器应该对此做出响应。举个例子，http://localhost:123。使用“*”指示服务应该监听来自任何IP 地址或者使用特定端口和协议的主机名称的请求（比如http://*:5000）。每一个URL都必须包含协议（http:// or https://）。支持的协议在服务中会有所不同。

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

Kestrel具有它自己终结点配置API。更多信息，请参考Kestrel web server implementation in ASP.NET Core。

Shutdown Timeout

指定了等待Web 宿主关闭的时间。

键：shutdownTimeoutSeconds

类型：int

默认值：5

设置方式：UseShutdownTimeout

环境变量：ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

虽然这个键值使用UseSetting接受一个int（举个例子，UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")），然而扩展方法UseShutdownTimeout 需要一个TimeSpan。

在超时期间，宿主：

触发了IApplicationLifetime.ApplicationStopping事件。
尝试停止寄宿的服务。如果一个服务没有正常停止，则为它们记录日志。

Startup Assembly

指定了用于查询Startup类的程序集。

键：startupAssembly

类型：string

默认值：默认为app的程序集

设置方式：UseStartup

环境变量：ASPNETCORE_STARTUPASSEMBLY

可以通过名称或者类型来引用一个程序集。如果多个UseStartup被调用，那么最后一个会优先考虑。

WebHost.CreateDefaultBuilder(args)
    .UseStartup("StartupAssemblyName")

WebHost.CreateDefaultBuilder(args)
    .UseStartup<TStartup>()

Web root

设置app静态资产的相对路径。

键：webroot

类型：string

默认值：默认为wwwroot，这个路径{content root}/wwwroot 必须存在，如果此路径不存在，一个无操作文件提供器会被使用。

设置方式：UseWebRoot

环境变量：ASPNETCORE_WEBROOT

WebHost.CreateDefaultBuilder(args)
    .UseWebRoot("public")

更多信息，请参考：

注：下篇我们将整理配置的重载，宿主的管理，两个重要的接口：IWebHostEnvironment，IHostApplicationLifetime，以及域验证等相关内容。