本文介绍ASP.NETCore泛型主机(HostBuilder),该主机用于无法处理HTTP请求的应用。
泛型主机的用途是将HTTP管道从Web主机API中分离出来,从而启用更多的主机方案。基于泛型主机的消息、后台任务和其他非HTTP工作负载可从横切功能(如配置、依赖关系注入[DI]和日志记录)中受益。
泛型主机是ASP.NETCore2.1中的新增功能,不适用于Web承载方案。对于Web承载方案,请使用Web主机。泛型主机将在未来版本中替换Web主机,并在HTTP和非HTTP方案中充当主要的主机API。
在VisualStudioCode中运行示例应用时,请使用外部或集成终端。请勿在internalConsole中运行示例。
通用主机库位于Microsoft.Extensions.Hosting命名空间中,由Microsoft.Extensions.Hosting包提供。Microsoft.AspNetCore.App元包(ASP.NETCore2.1或更高版本)中包括Microsoft.Extensions.Hosting包。
IHostedService是执行代码的入口点。每个IHostedService实现都按照ConfigureServices中服务注册的顺序执行。主机启动时,每个IHostedService上都会调用StartAsync,主机正常关闭时,以反向注册顺序调用Async。
IHostingEnvironment.ApplicationName属性是在主机构造期间通过主机配置设定的。要显式设置值,请使用HostDefaults.ApplicationKey:
密钥:applicationName类型:string默认值:包含应用入口点的程序集的名称。设置使用:HostBuilderContext.HostingEnvironment.ApplicationName环境变量:APPLICATIONNAME(是用户定义的可选前缀)
键:contentRoot类型:string默认值:默认为应用程序集所在的文件夹。设置使用:UseContentRoot环境变量:CONTENTROOT(是用户定义的可选前缀)
键:环境类型:string默认值:生产设置使用:UseEnvironment环境变量:ENVIRONMENT(是用户定义的可选前缀)
环境可以设置为任何值。框架定义的值包括Development``Staging和Production。值不区分大小写。
ConfigureHostConfiguration使用IConfigurationBuilder来为主机创建IConfiguration。主机配置用于初始化IHostingEnvironment,以供在应用的构建过程中使用。
可多次调用ConfigureHostConfiguration,并得到累计结果。主机使用上一次在一个给定键上设置值的选项。
主机配置自动流向应用配置(ConfigureAppConfiguration和应用的其余部分)。
默认情况下不包括提供程序。必须在ConfigureHostConfiguration中显式指定应用所需的任何配置提供程序,包括:
通过使用SetBasePath指定应用的基本路径,然后调用其中一个文件配置提供程序,可以启用主机的文件配置。示例应用使用JSON文件hostsettings.json,并调用AddJsonFile来使用文件的主机配置设置。
要添加主机的环境变量配置,请在主机生成器上调用AddEnvironmentVariables。AddEnvironmentVariables接受用户定义的前缀(可选)。示例应用使用前缀PREFIX_。当系统读取环境变量时,便会删除前缀。配置示例应用的主机后,PREFIX_ENVIRONMENT的环境变量值就变成environment密钥的主机配置值。
在开发过程中,如果使用VisualStudio或通过run运行应用,可能会在Properties/launchSettings.json文件中设置环境变量。若在开发过程中使用VisualStudioCode,可能会在.vscode/launch.json文件中设置环境变量。有关更多信息,请参见在ASP.NETCore中使用多个环境。
通过调用AddCommandLine可添加命令行配置。最后添加命令行配置以允许命令行参数替代之前配置提供程序提供的配置。
示例HostBuilder配置使用ConfigureHostConfiguration:
通过在IHostBuilder实现上调用ConfigureAppConfiguration创建应用配置。ConfigureAppConfiguration使用IConfigurationBuilder来为应用创建IConfiguration。可多次调用ConfigureAppConfiguration,并得到累计结果。应用使用上一次在一个给定键上设置值的选项。HostBuilderContext.Configuration中提供ConfigureAppConfiguration创建的配置,以供进行后续操作和在Services中使用。
要将设置文件移动到输出目录,请在项目文件中将设置文件指定为MSBuild项目项。示例应用移动具有以下项的JSON应用设置文件和hostsettings.json:
ConfigureServices将服务添加到应用的依赖关系注入容器。可多次调用ConfigureServices,并得到累计结果。
托管服务是一个类,具有实现IHostedService接口的后台任务逻辑。有关更多信息,请参见在ASP.NETCore中使用托管服务实现后台任务。
示例应用使用AddHostedService扩展方法向应用添加生存期事件LifetimeEventsHostedService和定时后台任务TimedHostedService服务:
ConfigureLogging添加了一个委托来配置提供的ILoggingBuilder。可以利用相加结果多次调用ConfigureLogging。
UseConsoleLifetime侦听Ctrl C/SIGINT或SIGTERM并调用Application来启动关闭进程。UseConsoleLifetime解除阻止RunAsync和WaitForShutdownAsync等扩展。ConsoleLifetime预注册为默认生存期实现。使用注册的最后一个生存期。
为支持插入其他容器中,主机可以接受IServiceProviderFactory。提供工厂不属于DI容器注册,而是用于创建具体DI容器的主机内部函数。UseServiceProviderFactory(IServiceProviderFactory)重写用于创建应用的服务提供程序的默认工厂。
ConfigureContainer方法托管自定义容器配置。ConfigureContainer提供在基础主机API的基础之上配置容器的强类型体验。可以利用相加结果多次调用ConfigureContainer。
在IHostBuilder上使用扩展方法实现主机扩展性。以下示例介绍扩展方法如何使用在ASP.NETCore中使用托管服务实现后台任务中所示的TimedHostedService示例来扩展IHostBuilder实现。
RunConsoleAsync启用控制台支持、生成和启动主机,以及等待Ctrl C/SIGINT或SIGTERM关闭。
WaitForShutdown通过IHostLifetime触发,例如ConsoleLifetime(侦听Ctrl C/SIGINT或SIGTERM)。WaitForShutdown调用Async。
WaitForShutdownAsync返回在通过给定的令牌和调用Async来触发关闭时完成的Task。
在StartAsync开始时调用WaitForStartAsync,在继续之前,会一直等待该操作完成。它可用于延迟启动,直到外部事件发出信号。
IHostingEnvironment提供有关应用托管环境的信息。使用构造函数注入获取IHostingEnvironment以使用其属性和扩展方法:
IApplicationLifetime允许启动后和关闭活动,包括正常关闭请求。接口上的三个属性是用于注册Action方法(用于定义启动和关闭事件)的取消标记。
构造函数将IApplicationLifetime服务注入到任何类中。示例应用将构造函数注入到LifetimeEventsHostedService类(一个IHostedService实现)中,用于注册事件。
Application请求终止应用。以下类在调用类的Shutdown方法时使用Application正常关闭应用: