ASP.NET Core 中的 .NET 通用主机
注意
此版本不是本文的最新版本。 对于当前版本,请参阅此文的 .NET 8 版本。
警告
此版本的 ASP.NET Core 不再受支持。 有关详细信息,请参阅 .NET 和 .NET Core 支持策略。 对于当前版本,请参阅此文的 .NET 8 版本。
本文介绍如何使用 ASP.NET Core 中的 .NET 通用主机。
这些 ASP.NET Core 模板创建 WebApplicationBuilder 和 WebApplication,这提供了一种简化的方式来配置和运行 Web 应用程序,而不需要 Startup
类。 有关 WebApplicationBuilder
和 WebApplication
的详细信息,请参阅WebApplicationBuilder
。
若要了解如何使用控制台应用中的 .NET 通用主机,请参阅 .NET 通用主机。
主机定义
主机是封装应用资源的对象,例如:
- 依赖关系注入 (DI)
- Logging
- Configuration
IHostedService
实现
当主机启动时,它将对在托管服务的服务容器集合中注册的 IHostedService 的每个实现调用 IHostedService.StartAsync。 在 web 应用中,其中一个 IHostedService
实现是启动 IHostedService
的 web 服务。
将应用的所有相互依赖资源包括在一个对象中可控制应用启动和正常关闭。
设置主机
主机通常由 Program.cs
中的代码配置、生成和运行。 以下代码会使用添加到 DI 容器中的 IHostedService
实现创建一个主机:
await Host.CreateDefaultBuilder(args)
.ConfigureServices(services =>
{
services.AddHostedService<SampleHostedService>();
})
.Build()
.RunAsync();
对于 HTTP 工作负载,在 CreateDefaultBuilder 之后调用 ConfigureWebHostDefaults:
await Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
})
.Build()
.RunAsync();
默认生成器设置
- 将内容根目录设置为由 GetCurrentDirectory 返回的路径。
- 通过以下对象加载主机配置:
- 前缀为
DOTNET_
的环境变量。 - 命令行参数。
- 前缀为
- 通过以下对象加载应用配置:
appsettings.json
。appsettings.{Environment}.json
。- 应用在
Development
环境中运行时的用户机密。 - 环境变量。
- 命令行参数。
- 添加以下日志记录提供程序:
- 控制台
- 调试
- EventSource
- EventLog(仅当在 Windows 上运行时)
- 当环境为“开发”时,启用范围验证和依赖关系验证。
- 从前缀为
ASPNETCORE_
的环境变量加载主机配置。 - 使用应用的托管配置提供程序将 Kestrel 服务器设置为 web 服务器并对其进行配置。 有关 Kestrel 服务器的默认选项,请参阅Kestrel。
- 添加主机筛选中间件。
- 如果
ASPNETCORE_FORWARDEDHEADERS_ENABLED
等于true
,则添加转接头中间件。 - 支持 IIS 集成。 有关 IIS 默认选项,请参阅使用 IIS 在 Windows 上托管 ASP.NET Core。
本文中后面的所有应用类型的设置和 web 应用的设置部分介绍如何替代默认生成器设置。
框架提供的服务
自动注册以下服务:
有关从框架提供的服务的详细信息,请参阅 ASP.NET Core 中的依赖关系注入。
IHostApplicationLifetime
将 IHostApplicationLifetime(以前称为 IApplicationLifetime
)服务注入任何类以处理启动后和正常关闭任务。 接口上的三个属性是用于注册应用启动和应用停止事件处理程序方法的取消令牌。 接口还包括一个 StopApplication
方法,该方法允许应用请求正常关闭。
正在执行正常关闭时,主机:
- 触发 ApplicationStopping 事件处理程序,使应用可以在关闭过程开始之前运行逻辑。
- 停止服务器,这将禁用新连接。 只要关闭超时允许,服务器将等待现有连接上的请求完成。 服务器将发送连接关闭标头,以进一步请求现有连接。
- 触发 ApplicationStopped 事件处理程序,使应用可以在应用程序关闭后运行逻辑。
以下示例是注册 IHostApplicationLifetime
事件处理程序的 IHostedService
实现:
public class HostApplicationLifetimeEventsHostedService : IHostedService
{
private readonly IHostApplicationLifetime _hostApplicationLifetime;
public HostApplicationLifetimeEventsHostedService(
IHostApplicationLifetime hostApplicationLifetime)
=> _hostApplicationLifetime = hostApplicationLifetime;
public Task StartAsync(CancellationToken cancellationToken)
{
_hostApplicationLifetime.ApplicationStarted.Register(OnStarted);
_hostApplicationLifetime.ApplicationStopping.Register(OnStopping);
_hostApplicationLifetime.ApplicationStopped.Register(OnStopped);
return Task.CompletedTask;
}
public Task StopAsync(CancellationToken cancellationToken)
=> Task.CompletedTask;
private void OnStarted()
{
// ...
}
private void OnStopping()
{
// ...
}
private void OnStopped()
{
// ...
}
}
IHostLifetime
IHostLifetime 实现控制主机何时启动和何时停止。 使用了已注册的最后一个实现。
Microsoft.Extensions.Hosting.Internal.ConsoleLifetime
是默认的 IHostLifetime
实现。 ConsoleLifetime
:
- 侦听 Ctrl+C/SIGINT (Windows)、⌘+C (macOS) 或 SIGTERM 并调用 StopApplication 来启动关闭进程。
- 解除阻止 RunAsync 和 WaitForShutdownAsync 等扩展。
IHostEnvironment
将 IHostEnvironment 服务注册到一个类,获取关于以下设置的信息:
Web 应用实现 IWebHostEnvironment
接口,该接口继承 IHostEnvironment
并添加 IWebHostEnvironment
。
主机配置
主机配置用于 IHostEnvironment 实现的属性。
ConfigureAppConfiguration 中的 HostBuilderContext.Configuration 提供了主机配置。 在 ConfigureAppConfiguration
后,HostBuilderContext.Configuration
被替换为应用配置。
若要添加主机配置,请对 IHostBuilder
调用 ConfigureHostConfiguration。 可多次调用 ConfigureHostConfiguration
,并得到累计结果。 主机使用上一次在一个给定键上设置值的选项。
CreateDefaultBuilder
包含前缀为 DOTNET_
的环境变量提供程序和命令行参数。 对于 web 应用程序,添加前缀为 ASPNETCORE_
的环境变量提供程序。 当系统读取环境变量时,便会删除前缀。 例如,ASPNETCORE_ENVIRONMENT
的环境变量值就变成 environment
密钥的主机配置值。
以下示例创建主机配置:
Host.CreateDefaultBuilder(args)
.ConfigureHostConfiguration(hostConfig =>
{
hostConfig.SetBasePath(Directory.GetCurrentDirectory());
hostConfig.AddJsonFile("hostsettings.json", optional: true);
hostConfig.AddEnvironmentVariables(prefix: "PREFIX_");
hostConfig.AddCommandLine(args);
});
应用配置
通过对 IHostBuilder
调用 ConfigureAppConfiguration 创建应用配置。 可多次调用 ConfigureAppConfiguration
,并得到累计结果。 应用使用上一次在一个给定键上设置值的选项。
可以在 HostBuilderContext.Configuration 中获取由 ConfigureAppConfiguration
创建的配置以用于后续操作,并将其作为 DI 的服务。 主机配置也会添加到应用配置。
有关详细信息,请参阅 ASP.NET Core 中的配置。
适用于所有应用类型的设置
本部分列出了适用于 HTTP 和非 HTTP 工作负荷的主机设置。 默认情况下,用于配置这些设置的环境变量可以有一个 DOTNET_
或 ASPNETCORE_
前缀,该前缀在以下设置列表中显示为 {PREFIX_}
占位符。 有关详细信息,请参阅默认生成器设置部分和配置:环境变量。
ApplicationName
IHostEnvironment.ApplicationName 属性是在主机构造期间通过主机配置设定的。
键:applicationName
类型:string
默认:包含应用入口点的程序集的名称。
环境变量:{PREFIX_}APPLICATIONNAME
要设置此值,请使用环境变量。
ContentRoot
IHostEnvironment.ContentRootPath 属性确定主机从哪里开始搜索内容文件。 如果路径不存在,主机将无法启动。
键:contentRoot
类型:string
默认:应用程序集所在的文件夹。
环境变量:{PREFIX_}CONTENTROOT
若要设置此值,请使用环境变量或对 IHostBuilder
调用 UseContentRoot
:
Host.CreateDefaultBuilder(args)
.UseContentRoot("/path/to/content/root")
// ...
有关详细信息,请参见:
EnvironmentName
IHostEnvironment.EnvironmentName 属性可以设置为任何值。 框架定义的值包括 Development
Staging
和 Production
。 值不区分大小写。
键:environment
类型:string
默认:Production
环境变量:{PREFIX_}ENVIRONMENT
若要设置此值,请使用环境变量或对 IHostBuilder
调用 UseEnvironment
:
Host.CreateDefaultBuilder(args)
.UseEnvironment("Development")
// ...
ShutdownTimeout
HostOptions.ShutdownTimeout 设置 StopAsync 的超时值。 默认值为 30 秒。 在超时时间段中,主机:
- 触发 IHostApplicationLifetime.ApplicationStopping。
- 尝试停止托管服务,对服务停止失败的错误进行日志记录。
如果在所有托管服务停止之前就达到了超时时间,则会在应用关闭时会终止剩余的所有活动的服务。 即使没有完成处理工作,服务也会停止。 如果停止服务需要更多时间,请增加超时时间。
键:shutdownTimeoutSeconds
类型:int
默认值:30 秒
环境变量:{PREFIX_}SHUTDOWNTIMEOUTSECONDS
若要设置此值,请使用环境变量或配置 HostOptions
。 以下示例将超时设置为 20 秒:
Host.CreateDefaultBuilder(args)
.ConfigureServices((hostContext, services) =>
{
services.Configure<HostOptions>(options =>
{
options.ShutdownTimeout = TimeSpan.FromSeconds(20);
});
});
禁用“在更改时重载应用配置”
默认情况下,appsettings.json
和 appsettings.{Environment}.json
会在文件发生更改时进行重载。 若要在 ASP.NET Core 5.0 或更高版本中禁用此重载行为,请将 hostBuilder:reloadConfigOnChange
键设置为 false
。
键:hostBuilder:reloadConfigOnChange
类型:(true
或 false
)
默认:true
命令行参数:
环境变量:{PREFIX_}hostBuilder:reloadConfigOnChange
警告
所有平台上的环境变量分层键都不支持冒号 (:
) 分隔符。 有关详细信息,请参阅环境变量。
适用于 Web 应用的设置
一些主机设置仅适用于 HTTP 工作负荷。 默认情况下,用于配置这些设置的环境变量可以有一个 DOTNET_
或 ASPNETCORE_
前缀,该前缀在以下设置列表中显示为 {PREFIX_}
占位符。
IWebHostBuilder
上的扩展方法适用于这些设置。 显示如何调用扩展方法的示例代码假定 webBuilder
是 IWebHostBuilder
的实例,如以下示例所示:
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
// ...
});
CaptureStartupErrors
当 false
时,启动期间出错导致主机退出。 当 true
时,主机在启动期间捕获异常并尝试启动服务器。
键:captureStartupErrors
类型:(true
/1
或 false
/0
)
默认值:默认为 ,除非应用使用 Kestrel 在 IIS 后方运行,其中默认值是 true
。
环境变量:{PREFIX_}CAPTURESTARTUPERRORS
要设置此值,使用配置或调用 CaptureStartupErrors
:
webBuilder.CaptureStartupErrors(true);
DetailedErrors
如果启用,或环境为 Development
,应用会捕获详细错误。
键:detailedErrors
类型:(true
/1
或 false
/0
)
默认:false
环境变量:{PREFIX_}DETAILEDERRORS
要设置此值,使用配置或调用 UseSetting
:
webBuilder.UseSetting(WebHostDefaults.DetailedErrorsKey, "true");
HostingStartupAssemblies
承载启动程序集的以分号分隔的字符串在启动时加载。 虽然配置值默认为空字符串,但是承载启动程序集会始终包含应用的程序集。 提供承载启动程序集时,当应用在启动过程中生成其公用服务时将它们添加到应用的程序集加载。
键:hostingStartupAssemblies
类型:string
默认:空字符串
环境变量:{PREFIX_}HOSTINGSTARTUPASSEMBLIES
要设置此值,使用配置或调用 UseSetting
:
webBuilder.UseSetting(
WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2");
HostingStartupExcludeAssemblies
承载启动程序集的以分号分隔的字符串在启动时排除。
键:hostingStartupExcludeAssemblies
类型:string
默认:空字符串
环境变量:{PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES
要设置此值,使用配置或调用 UseSetting
:
webBuilder.UseSetting(
WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2");
HTTPS_Port
HTTPS 重定向端口。 用于强制实施 HTTPS。
键:https_port
类型:string
默认:未设置默认值。
环境变量:{PREFIX_}HTTPS_PORT
要设置此值,使用配置或调用 UseSetting
:
webBuilder.UseSetting("https_port", "8080");
PreferHostingUrls
指示主机是否应该侦听使用 IWebHostBuilder
配置的 URL,而不是使用 IServer
实现配置的 URL。
键:preferHostingUrls
类型:(true
/1
或 false
/0
)
默认:false
环境变量:{PREFIX_}PREFERHOSTINGURLS
若要设置此值,请使用环境变量或调用 PreferHostingUrls
:
webBuilder.PreferHostingUrls(true);
PreventHostingStartup
阻止承载启动程序集自动加载,包括应用的程序集所配置的承载启动程序集。 有关详细信息,请参阅在 ASP.NET Core 中使用托管启动程序集。
键:preventHostingStartup
类型:(true
/1
或 false
/0
)
默认:false
环境变量:{PREFIX_}PREVENTHOSTINGSTARTUP
若要设置此值,请使用环境变量或调用 UseSetting
:
webBuilder.UseSetting(WebHostDefaults.PreventHostingStartupKey, "true");
StartupAssembly
要搜索 Startup
类的程序集。
键:startupAssembly
类型:string
默认:应用的程序集
环境变量:{PREFIX_}STARTUPASSEMBLY
若要设置此值,请使用环境变量或调用 UseStartup
。 UseStartup
可以采用程序集名称 (string
) 或类型 (TStartup
)。 如果调用多个 UseStartup
方法,优先选择最后一个方法。
webBuilder.UseStartup("StartupAssemblyName");
webBuilder.UseStartup<Startup>();
SuppressStatusMessages
启用后,将取消承载启动状态消息。
键:suppressStatusMessages
类型:(true
/1
或 false
/0
)
默认:false
环境变量:{PREFIX_}SUPPRESSSTATUSMESSAGES
要设置此值,使用配置或调用 UseSetting
:
webBuilder.UseSetting(WebHostDefaults.SuppressStatusMessagesKey, "true");
URL
IP 地址或主机地址的分号分隔列表,其中包含服务器应针对请求侦听的端口和协议。 例如 http://localhost:123
。 使用“*”指示服务器应针对请求侦听的使用特定端口和协议(例如 http://*:5000
)的 IP 地址或主机名。 协议(http://
或 https://
)必须包含每个 URL。 不同的服务器支持的格式有所不同。
键:urls
类型:string
默认值:http://localhost:5000
和 https://localhost:5001
环境变量:{PREFIX_}URLS
若要设置此值,请使用环境变量或调用 UseUrls
:
webBuilder.UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002");
Kestrel 具有自己的终结点配置 API。 有关详细信息,请参阅为 ASP.NET Core Kestrel Web 服务器配置终结点。
WebRoot
IWebHostEnvironment.WebRootPath 属性可确定应用静态资产的相对路径。 如果该路径不存在,则使用无操作文件提供程序。
键:webroot
类型:string
默认:默认值为 wwwroot
。 {content root}/wwwroot 的路径必须存在。
环境变量:{PREFIX_}WEBROOT
若要设置此值,请使用环境变量或对 IWebHostBuilder
调用 UseWebRoot
:
webBuilder.UseWebRoot("public");
有关详细信息,请参见:
管理主机生存期
对生成的 IHost 实现调用方法,以启动和停止应用。 这些方法会影响所有在服务容器中注册的 IHostedService 实现。
Run*
和 Start*
方法之间的差异是 Run*
方法会在返回之前等待主机完成,而 Start*
方法会立即返回。 Run*
方法通常用于控制台应用,而 Start*
方法则通常用于长期运行的服务中。
运行
Run 运行应用并阻止调用线程,直到关闭主机。
RunAsync
RunAsync 运行应用并返回在触发取消令牌或关闭时完成的 Task。
RunConsoleAsync
RunConsoleAsync 启用控制台支持、生成和启动主机,以及等待 Ctrl+C/SIGINT (Windows)、⌘+C (macOS) 或 SIGTERM 关闭。
开始
Start 同步启动主机。
StartAsync
StartAsync 启动主机并返回在触发取消令牌或关闭时完成的 Task。
在 StartAsync
开始时调用 WaitForStartAsync,在继续之前,会一直等待该操作完成。 此方法可用于延迟启动,直到外部事件发出信号。
StopAsync
StopAsync 尝试在提供的超时时间内停止主机。
WaitForShutdown
WaitForShutdown 阻止调用线程,直到 IHostLifetime 触发关闭,例如通过 Ctrl+C/SIGINT (Windows)、⌘+C (macOS) 或 SIGTERM。
WaitForShutdownAsync
WaitForShutdownAsync 返回在通过给定的令牌和调用 StopAsync 来触发关闭时完成的 Task。
ASP.NET Core 模板会创建一个 .NET Core 泛型主机 (HostBuilder)。
本文介绍如何使用 ASP.NET Core 中的 .NET 通用主机。 若要了解如何使用控制台应用中的 .NET 通用主机,请参阅 .NET 通用主机。
主机定义
主机是封装应用资源的对象,例如:
- 依赖关系注入 (DI)
- Logging
- Configuration
IHostedService
实现
当主机启动时,它将对在托管服务的服务容器集合中注册的 IHostedService 的每个实现调用 IHostedService.StartAsync。 在 web 应用中,其中一个 IHostedService
实现是启动 IHostedService
的 web 服务。
一个对象中包含所有应用的相互依赖资源的主要原因是生存期管理:控制应用启动和正常关闭。
设置主机
主机通常由 Program
类中的代码配置、生成和运行。 Main
方法:
- 调用
CreateHostBuilder
方法以创建和配置生成器对象。 - 对生成器对象调用
Build
和Run
方法。
ASP.NET Core Web 模板会生成以下代码来创建一个主机:
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}
以下代码会使用添加到 DI 容器中的 IHostedService
实现创建一个非 HTTP 工作负载。
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureServices((hostContext, services) =>
{
services.AddHostedService<Worker>();
});
}
对于 HTTP 工作负荷,Main
方法相同,但 CreateHostBuilder
调用 ConfigureWebHostDefaults
:
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
如果应用使用 Entity Framework Core,不要更改 CreateHostBuilder
方法的名称或签名。 Entity Framework Core 工具应查找一个无需运行应用即可配置主机的 CreateHostBuilder
方法。 有关详细信息,请参阅设计时 DbContext 创建。
默认生成器设置
- 将内容根目录设置为由 GetCurrentDirectory 返回的路径。
- 通过以下对象加载主机配置:
- 前缀为
DOTNET_
的环境变量。 - 命令行参数。
- 前缀为
- 通过以下对象加载应用配置:
appsettings.json
。appsettings.{Environment}.json
。- 应用在
Development
环境中运行时的用户机密。 - 环境变量。
- 命令行参数。
- 添加以下日志记录提供程序:
- 控制台
- 调试
- EventSource
- EventLog(仅当在 Windows 上运行时)
- 当环境为“开发”时,启用范围验证和依赖关系验证。
- 从前缀为
ASPNETCORE_
的环境变量加载主机配置。 - 使用应用的托管配置提供程序将 Kestrel 服务器设置为 web 服务器并对其进行配置。 有关 Kestrel 服务器的默认选项,请参阅Kestrel。
- 添加主机筛选中间件。
- 如果
ASPNETCORE_FORWARDEDHEADERS_ENABLED
等于true
,则添加转接头中间件。 - 支持 IIS 集成。 有关 IIS 默认选项,请参阅使用 IIS 在 Windows 上托管 ASP.NET Core。
本文中后面的所有应用类型的设置和 web 应用的设置部分介绍如何替代默认生成器设置。
框架提供的服务
自动注册以下服务:
有关从框架提供的服务的详细信息,请参阅 ASP.NET Core 中的依赖关系注入。
IHostApplicationLifetime
将 IHostApplicationLifetime(以前称为 IApplicationLifetime
)服务注入任何类以处理启动后和正常关闭任务。 接口上的三个属性是用于注册应用启动和应用停止事件处理程序方法的取消令牌。 该接口还包括 StopApplication
方法。
以下示例是注册 IHostApplicationLifetime
事件的 IHostedService
实现:
internal class LifetimeEventsHostedService : IHostedService
{
private readonly ILogger _logger;
private readonly IHostApplicationLifetime _appLifetime;
public LifetimeEventsHostedService(
ILogger<LifetimeEventsHostedService> logger,
IHostApplicationLifetime appLifetime)
{
_logger = logger;
_appLifetime = appLifetime;
}
public Task StartAsync(CancellationToken cancellationToken)
{
_appLifetime.ApplicationStarted.Register(OnStarted);
_appLifetime.ApplicationStopping.Register(OnStopping);
_appLifetime.ApplicationStopped.Register(OnStopped);
return Task.CompletedTask;
}
public Task StopAsync(CancellationToken cancellationToken)
{
return Task.CompletedTask;
}
private void OnStarted()
{
_logger.LogInformation("OnStarted has been called.");
// Perform post-startup activities here
}
private void OnStopping()
{
_logger.LogInformation("OnStopping has been called.");
// Perform on-stopping activities here
}
private void OnStopped()
{
_logger.LogInformation("OnStopped has been called.");
// Perform post-stopped activities here
}
}
IHostLifetime
IHostLifetime 实现控制主机何时启动和何时停止。 使用了已注册的最后一个实现。
Microsoft.Extensions.Hosting.Internal.ConsoleLifetime
是默认的 IHostLifetime
实现。 ConsoleLifetime
:
- 侦听 Ctrl+C/SIGINT (Windows)、⌘+C (macOS) 或 SIGTERM 并调用 StopApplication 来启动关闭进程。
- 解除阻止 RunAsync 和 WaitForShutdownAsync 等扩展。
IHostEnvironment
将 IHostEnvironment 服务注册到一个类,获取关于以下设置的信息:
Web 应用实现 IWebHostEnvironment
接口,该接口继承 IHostEnvironment
并添加 IWebHostEnvironment
。
主机配置
主机配置用于 IHostEnvironment 实现的属性。
ConfigureAppConfiguration 中的 HostBuilderContext.Configuration 提供了主机配置。 在 ConfigureAppConfiguration
后,HostBuilderContext.Configuration
被替换为应用配置。
若要添加主机配置,请对 IHostBuilder
调用 ConfigureHostConfiguration。 可多次调用 ConfigureHostConfiguration
,并得到累计结果。 主机使用上一次在一个给定键上设置值的选项。
CreateDefaultBuilder
包含前缀为 DOTNET_
的环境变量提供程序和命令行参数。 对于 web 应用程序,添加前缀为 ASPNETCORE_
的环境变量提供程序。 当系统读取环境变量时,便会删除前缀。 例如,ASPNETCORE_ENVIRONMENT
的环境变量值就变成 environment
密钥的主机配置值。
以下示例创建主机配置:
// using Microsoft.Extensions.Configuration;
Host.CreateDefaultBuilder(args)
.ConfigureHostConfiguration(configHost =>
{
configHost.SetBasePath(Directory.GetCurrentDirectory());
configHost.AddJsonFile("hostsettings.json", optional: true);
configHost.AddEnvironmentVariables(prefix: "PREFIX_");
configHost.AddCommandLine(args);
});
应用配置
通过对 IHostBuilder
调用 ConfigureAppConfiguration 创建应用配置。 可多次调用 ConfigureAppConfiguration
,并得到累计结果。 应用使用上一次在一个给定键上设置值的选项。
可以在 HostBuilderContext.Configuration 中获取由 ConfigureAppConfiguration
创建的配置以用于后续操作,并将其作为 DI 的服务。 主机配置也会添加到应用配置。
有关详细信息,请参阅 ASP.NET Core 中的配置。
适用于所有应用类型的设置
本部分列出了适用于 HTTP 和非 HTTP 工作负荷的主机设置。 默认情况下,用于配置这些设置的环境变量可以有一个 DOTNET_
或 ASPNETCORE_
前缀,该前缀在以下设置列表中显示为 {PREFIX_}
占位符。 有关详细信息,请参阅默认生成器设置部分和配置:环境变量。
ApplicationName
IHostEnvironment.ApplicationName 属性是在主机构造期间通过主机配置设定的。
键:applicationName
类型:string
默认:包含应用入口点的程序集的名称。
环境变量:{PREFIX_}APPLICATIONNAME
要设置此值,请使用环境变量。
ContentRoot
IHostEnvironment.ContentRootPath 属性确定主机从哪里开始搜索内容文件。 如果路径不存在,主机将无法启动。
键:contentRoot
类型:string
默认:应用程序集所在的文件夹。
环境变量:{PREFIX_}CONTENTROOT
若要设置此值,请使用环境变量或对 IHostBuilder
调用 UseContentRoot
:
Host.CreateDefaultBuilder(args)
.UseContentRoot("c:\\content-root")
//...
有关详细信息,请参见:
EnvironmentName
IHostEnvironment.EnvironmentName 属性可以设置为任何值。 框架定义的值包括 Development
Staging
和 Production
。 值不区分大小写。
键:environment
类型:string
默认:Production
环境变量:{PREFIX_}ENVIRONMENT
若要设置此值,请使用环境变量或对 IHostBuilder
调用 UseEnvironment
:
Host.CreateDefaultBuilder(args)
.UseEnvironment("Development")
//...
ShutdownTimeout
HostOptions.ShutdownTimeout 设置 StopAsync 的超时值。 默认值为 5 秒。 在超时时间段中,主机:
- 触发 IHostApplicationLifetime.ApplicationStopping。
- 尝试停止托管服务,对服务停止失败的错误进行日志记录。
如果在所有托管服务停止之前就达到了超时时间,则会在应用关闭时会终止剩余的所有活动的服务。 即使没有完成处理工作,服务也会停止。 如果停止服务需要更多时间,请增加超时时间。
键:shutdownTimeoutSeconds
类型:int
默认:5 秒
环境变量:{PREFIX_}SHUTDOWNTIMEOUTSECONDS
若要设置此值,请使用环境变量或配置 HostOptions
。 以下示例将超时设置为 20 秒:
Host.CreateDefaultBuilder(args)
.ConfigureServices((hostContext, services) =>
{
services.Configure<HostOptions>(option =>
{
option.ShutdownTimeout = System.TimeSpan.FromSeconds(20);
});
});
禁用“在更改时重载应用配置”
默认情况下,appsettings.json
和 appsettings.{Environment}.json
会在文件发生更改时进行重载。 若要在 ASP.NET Core 5.0 或更高版本中禁用此重载行为,请将 hostBuilder:reloadConfigOnChange
键设置为 false
。
键:hostBuilder:reloadConfigOnChange
类型:(true
或 false
)
默认:true
命令行参数:
环境变量:{PREFIX_}hostBuilder:reloadConfigOnChange
警告
所有平台上的环境变量分层键都不支持冒号 (:
) 分隔符。 有关详细信息,请参阅环境变量。
适用于 Web 应用的设置
一些主机设置仅适用于 HTTP 工作负荷。 默认情况下,用于配置这些设置的环境变量可以有一个 DOTNET_
或 ASPNETCORE_
前缀,该前缀在以下设置列表中显示为 {PREFIX_}
占位符。
IWebHostBuilder
上的扩展方法适用于这些设置。 显示如何调用扩展方法的示例代码假定 webBuilder
是 IWebHostBuilder
的实例,如以下示例所示:
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.CaptureStartupErrors(true);
webBuilder.UseStartup<Startup>();
});
CaptureStartupErrors
当 false
时,启动期间出错导致主机退出。 当 true
时,主机在启动期间捕获异常并尝试启动服务器。
键:captureStartupErrors
类型:(true
/1
或 false
/0
)
默认值:默认为 ,除非应用使用 Kestrel 在 IIS 后方运行,其中默认值是 true
。
环境变量:{PREFIX_}CAPTURESTARTUPERRORS
要设置此值,使用配置或调用 CaptureStartupErrors
:
webBuilder.CaptureStartupErrors(true);
DetailedErrors
如果启用,或环境为 Development
,应用会捕获详细错误。
键:detailedErrors
类型:(true
/1
或 false
/0
)
默认:false
环境变量:{PREFIX_}DETAILEDERRORS
要设置此值,使用配置或调用 UseSetting
:
webBuilder.UseSetting(WebHostDefaults.DetailedErrorsKey, "true");
HostingStartupAssemblies
承载启动程序集的以分号分隔的字符串在启动时加载。 虽然配置值默认为空字符串,但是承载启动程序集会始终包含应用的程序集。 提供承载启动程序集时,当应用在启动过程中生成其公用服务时将它们添加到应用的程序集加载。
键:hostingStartupAssemblies
类型:string
默认:空字符串
环境变量:{PREFIX_}HOSTINGSTARTUPASSEMBLIES
要设置此值,使用配置或调用 UseSetting
:
webBuilder.UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2");
HostingStartupExcludeAssemblies
承载启动程序集的以分号分隔的字符串在启动时排除。
键:hostingStartupExcludeAssemblies
类型:string
默认:空字符串
环境变量:{PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES
要设置此值,使用配置或调用 UseSetting
:
webBuilder.UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2");
HTTPS_Port
HTTPS 重定向端口。 用于强制实施 HTTPS。
键:https_port
类型:string
默认:未设置默认值。
环境变量:{PREFIX_}HTTPS_PORT
要设置此值,使用配置或调用 UseSetting
:
webBuilder.UseSetting("https_port", "8080");
PreferHostingUrls
指示主机是否应该侦听使用 IWebHostBuilder
配置的 URL,而不是使用 IServer
实现配置的 URL。
键:preferHostingUrls
类型:(true
/1
或 false
/0
)
默认:false
环境变量:{PREFIX_}PREFERHOSTINGURLS
若要设置此值,请使用环境变量或调用 PreferHostingUrls
:
webBuilder.PreferHostingUrls(true);
PreventHostingStartup
阻止承载启动程序集自动加载,包括应用的程序集所配置的承载启动程序集。 有关详细信息,请参阅在 ASP.NET Core 中使用托管启动程序集。
键:preventHostingStartup
类型:(true
/1
或 false
/0
)
默认:false
环境变量:{PREFIX_}PREVENTHOSTINGSTARTUP
若要设置此值,请使用环境变量或调用 UseSetting
:
webBuilder.UseSetting(WebHostDefaults.PreventHostingStartupKey, "true");
StartupAssembly
要搜索 Startup
类的程序集。
键:startupAssembly
类型:string
默认:应用的程序集
环境变量:{PREFIX_}STARTUPASSEMBLY
若要设置此值,请使用环境变量或调用 UseStartup
。 UseStartup
可以采用程序集名称 (string
) 或类型 (TStartup
)。 如果调用多个 UseStartup
方法,优先选择最后一个方法。
webBuilder.UseStartup("StartupAssemblyName");
webBuilder.UseStartup<Startup>();
SuppressStatusMessages
启用后,将取消承载启动状态消息。
键:suppressStatusMessages
类型:(true
/1
或 false
/0
)
默认:false
环境变量:{PREFIX_}SUPPRESSSTATUSMESSAGES
要设置此值,使用配置或调用 UseSetting
:
webBuilder.UseSetting(WebHostDefaults.SuppressStatusMessagesKey, "true");
URL
IP 地址或主机地址的分号分隔列表,其中包含服务器应针对请求侦听的端口和协议。 例如 http://localhost:123
。 使用“*”指示服务器应针对请求侦听的使用特定端口和协议(例如 http://*:5000
)的 IP 地址或主机名。 协议(http://
或 https://
)必须包含每个 URL。 不同的服务器支持的格式有所不同。
键:urls
类型:string
默认值:http://localhost:5000
和 https://localhost:5001
环境变量:{PREFIX_}URLS
若要设置此值,请使用环境变量或调用 UseUrls
:
webBuilder.UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002");
Kestrel 具有自己的终结点配置 API。 有关详细信息,请参阅为 ASP.NET Core Kestrel Web 服务器配置终结点。
WebRoot
IWebHostEnvironment.WebRootPath 属性可确定应用静态资产的相对路径。 如果该路径不存在,则使用无操作文件提供程序。
键:webroot
类型:string
默认:默认值为 wwwroot
。 {content root}/wwwroot 的路径必须存在。
环境变量:{PREFIX_}WEBROOT
若要设置此值,请使用环境变量或对 IWebHostBuilder
调用 UseWebRoot
:
webBuilder.UseWebRoot("public");
有关详细信息,请参见:
管理主机生存期
对生成的 IHost 实现调用方法,以启动和停止应用。 这些方法会影响所有在服务容器中注册的 IHostedService 实现。
Run*
和 Start*
方法之间的差异是 Run*
方法会在返回之前等待主机完成,而 Start*
方法会立即返回。 Run*
方法通常用于控制台应用,而 Start*
方法则通常用于长期运行的服务中。
运行
Run 运行应用并阻止调用线程,直到关闭主机。
RunAsync
RunAsync 运行应用并返回在触发取消令牌或关闭时完成的 Task。
RunConsoleAsync
RunConsoleAsync 启用控制台支持、生成和启动主机,以及等待 Ctrl+C/SIGINT (Windows)、⌘+C (macOS) 或 SIGTERM 关闭。
开始
Start 同步启动主机。
StartAsync
StartAsync 启动主机并返回在触发取消令牌或关闭时完成的 Task。
在 StartAsync
开始时调用 WaitForStartAsync,在继续之前,会一直等待该操作完成。 此方法可用于延迟启动,直到外部事件发出信号。
StopAsync
StopAsync 尝试在提供的超时时间内停止主机。
WaitForShutdown
WaitForShutdown 阻止调用线程,直到 IHostLifetime 触发关闭,例如通过 Ctrl+C/SIGINT (Windows)、⌘+C (macOS) 或 SIGTERM。
WaitForShutdownAsync
WaitForShutdownAsync 返回在通过给定的令牌和调用 StopAsync 来触发关闭时完成的 Task。
外部控件
使用可从外部调用的方法,能够实现对主机生存期的直接控制:
public class Program
{
private IHost _host;
public Program()
{
_host = new HostBuilder()
.Build();
}
public async Task StartAsync()
{
_host.StartAsync();
}
public async Task StopAsync()
{
using (_host)
{
await _host.StopAsync(TimeSpan.FromSeconds(5));
}
}
}
ASP.NET Core 模板会创建一个 .NET Core 泛型主机 (HostBuilder)。
本文介绍如何使用 ASP.NET Core 中的 .NET 通用主机。 若要了解如何使用控制台应用中的 .NET 通用主机,请参阅 .NET 通用主机。
主机定义
主机是封装应用资源的对象,例如:
- 依赖关系注入 (DI)
- Logging
- Configuration
IHostedService
实现
当主机启动时,它将对在托管服务的服务容器集合中注册的 IHostedService 的每个实现调用 IHostedService.StartAsync。 在 web 应用中,其中一个 IHostedService
实现是启动 IHostedService
的 web 服务。
一个对象中包含所有应用的相互依赖资源的主要原因是生存期管理:控制应用启动和正常关闭。
设置主机
主机通常由 Program
类中的代码配置、生成和运行。 Main
方法:
- 调用
CreateHostBuilder
方法以创建和配置生成器对象。 - 对生成器对象调用
Build
和Run
方法。
ASP.NET Core Web 模板会生成以下代码来创建泛型主机:
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}
以下代码会使用非 HTTP 工作负载创建一个泛型主机。 IHostedService
实现会添加到 DI 容器中:
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureServices((hostContext, services) =>
{
services.AddHostedService<Worker>();
});
}
对于 HTTP 工作负荷,Main
方法相同,但 CreateHostBuilder
调用 ConfigureWebHostDefaults
:
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
上述代码是由 ASP.NET Core 模板生成的。
如果应用使用 Entity Framework Core,不要更改 CreateHostBuilder
方法的名称或签名。 Entity Framework Core 工具应查找一个无需运行应用即可配置主机的 CreateHostBuilder
方法。 有关详细信息,请参阅设计时 DbContext 创建。
默认生成器设置
- 将内容根目录设置为由 GetCurrentDirectory 返回的路径。
- 通过以下对象加载主机配置:
- 前缀为
DOTNET_
的环境变量。 - 命令行参数。
- 前缀为
- 通过以下对象加载应用配置:
appsettings.json
。appsettings.{Environment}.json
。- 应用在
Development
环境中运行时的用户机密。 - 环境变量。
- 命令行参数。
- 添加以下日志记录提供程序:
- 控制台
- 调试
- EventSource
- EventLog(仅当在 Windows 上运行时)
- 当环境为“开发”时,启用范围验证和依赖关系验证。
ConfigureWebHostDefaults
方法:
- 从前缀为
ASPNETCORE_
的环境变量加载主机配置。 - 使用应用的托管配置提供程序将 Kestrel 服务器设置为 web 服务器并对其进行配置。 有关 Kestrel 服务器的默认选项,请参阅 ASP.NET Core 中的 Kestrel Web 服务器。
- 添加主机筛选中间件。
- 如果
ASPNETCORE_FORWARDEDHEADERS_ENABLED
等于true
,则添加转接头中间件。 - 支持 IIS 集成。 有关 IIS 默认选项,请参阅使用 IIS 在 Windows 上托管 ASP.NET Core。
本文中后面的所有应用类型的设置和 web 应用的设置部分介绍如何替代默认生成器设置。
框架提供的服务
自动注册以下服务:
有关从框架提供的服务的详细信息,请参阅 ASP.NET Core 中的依赖关系注入。
IHostApplicationLifetime
将 IHostApplicationLifetime(以前称为 IApplicationLifetime
)服务注入任何类以处理启动后和正常关闭任务。 接口上的三个属性是用于注册应用启动和应用停止事件处理程序方法的取消令牌。 该接口还包括 StopApplication
方法。
以下示例是注册 IHostApplicationLifetime
事件的 IHostedService
实现:
internal class LifetimeEventsHostedService : IHostedService
{
private readonly ILogger _logger;
private readonly IHostApplicationLifetime _appLifetime;
public LifetimeEventsHostedService(
ILogger<LifetimeEventsHostedService> logger,
IHostApplicationLifetime appLifetime)
{
_logger = logger;
_appLifetime = appLifetime;
}
public Task StartAsync(CancellationToken cancellationToken)
{
_appLifetime.ApplicationStarted.Register(OnStarted);
_appLifetime.ApplicationStopping.Register(OnStopping);
_appLifetime.ApplicationStopped.Register(OnStopped);
return Task.CompletedTask;
}
public Task StopAsync(CancellationToken cancellationToken)
{
return Task.CompletedTask;
}
private void OnStarted()
{
_logger.LogInformation("OnStarted has been called.");
// Perform post-startup activities here
}
private void OnStopping()
{
_logger.LogInformation("OnStopping has been called.");
// Perform on-stopping activities here
}
private void OnStopped()
{
_logger.LogInformation("OnStopped has been called.");
// Perform post-stopped activities here
}
}
IHostLifetime
IHostLifetime 实现控制主机何时启动和何时停止。 使用了已注册的最后一个实现。
Microsoft.Extensions.Hosting.Internal.ConsoleLifetime
是默认的 IHostLifetime
实现。 ConsoleLifetime
:
- 侦听 Ctrl+C/SIGINT (Windows)、⌘+C (macOS) 或 SIGTERM 并调用 StopApplication 来启动关闭进程。
- 解除阻止 RunAsync 和 WaitForShutdownAsync 等扩展。
IHostEnvironment
将 IHostEnvironment 服务注册到一个类,获取关于以下设置的信息:
Web 应用实现 IWebHostEnvironment
接口,该接口继承 IHostEnvironment
并添加 IWebHostEnvironment
。
主机配置
主机配置用于 IHostEnvironment 实现的属性。
ConfigureAppConfiguration 中的 HostBuilderContext.Configuration 提供了主机配置。 在 ConfigureAppConfiguration
后,HostBuilderContext.Configuration
被替换为应用配置。
若要添加主机配置,请对 IHostBuilder
调用 ConfigureHostConfiguration。 可多次调用 ConfigureHostConfiguration
,并得到累计结果。 主机使用上一次在一个给定键上设置值的选项。
CreateDefaultBuilder
包含前缀为 DOTNET_
的环境变量提供程序和命令行参数。 对于 web 应用程序,添加前缀为 ASPNETCORE_
的环境变量提供程序。 当系统读取环境变量时,便会删除前缀。 例如,ASPNETCORE_ENVIRONMENT
的环境变量值就变成 environment
密钥的主机配置值。
以下示例创建主机配置:
// using Microsoft.Extensions.Configuration;
Host.CreateDefaultBuilder(args)
.ConfigureHostConfiguration(configHost =>
{
configHost.SetBasePath(Directory.GetCurrentDirectory());
configHost.AddJsonFile("hostsettings.json", optional: true);
configHost.AddEnvironmentVariables(prefix: "PREFIX_");
configHost.AddCommandLine(args);
});
应用配置
通过对 IHostBuilder
调用 ConfigureAppConfiguration 创建应用配置。 可多次调用 ConfigureAppConfiguration
,并得到累计结果。 应用使用上一次在一个给定键上设置值的选项。
可以在 HostBuilderContext.Configuration 中获取由 ConfigureAppConfiguration
创建的配置以用于后续操作,并将其作为 DI 的服务。 主机配置也会添加到应用配置。
有关详细信息,请参阅 ASP.NET Core 中的配置。
适用于所有应用类型的设置
本部分列出了适用于 HTTP 和非 HTTP 工作负荷的主机设置。 默认情况下,用于配置这些设置的环境变量可以有一个 DOTNET_
或 ASPNETCORE_
前缀,该前缀在以下配置中显示为 {PREFIX_}
占位符。
ApplicationName
IHostEnvironment.ApplicationName 属性是在主机构造期间通过主机配置设定的。
键:applicationName
类型:string
默认:包含应用入口点的程序集的名称。
环境变量:{PREFIX_}APPLICATIONNAME
要设置此值,请使用环境变量。
ContentRoot
IHostEnvironment.ContentRootPath 属性确定主机从哪里开始搜索内容文件。 如果路径不存在,主机将无法启动。
键:contentRoot
类型:string
默认:应用程序集所在的文件夹。
环境变量:{PREFIX_}CONTENTROOT
若要设置此值,请使用环境变量或对 IHostBuilder
调用 UseContentRoot
:
Host.CreateDefaultBuilder(args)
.UseContentRoot("c:\\content-root")
//...
有关详细信息,请参见:
EnvironmentName
IHostEnvironment.EnvironmentName 属性可以设置为任何值。 框架定义的值包括 Development
Staging
和 Production
。 值不区分大小写。
键:environment
类型:string
默认:Production
环境变量:{PREFIX_}ENVIRONMENT
若要设置此值,请使用环境变量或对 IHostBuilder
调用 UseEnvironment
:
Host.CreateDefaultBuilder(args)
.UseEnvironment("Development")
//...
ShutdownTimeout
HostOptions.ShutdownTimeout 设置 StopAsync 的超时值。 默认值为 5 秒。 在超时时间段中,主机:
- 触发 IHostApplicationLifetime.ApplicationStopping。
- 尝试停止托管服务,对服务停止失败的错误进行日志记录。
如果在所有托管服务停止之前就达到了超时时间,则会在应用关闭时会终止剩余的所有活动的服务。 即使没有完成处理工作,服务也会停止。 如果停止服务需要更多时间,请增加超时时间。
键:shutdownTimeoutSeconds
类型:int
默认:5 秒
环境变量:{PREFIX_}SHUTDOWNTIMEOUTSECONDS
若要设置此值,请使用环境变量或配置 HostOptions
。 以下示例将超时设置为 20 秒:
Host.CreateDefaultBuilder(args)
.ConfigureServices((hostContext, services) =>
{
services.Configure<HostOptions>(option =>
{
option.ShutdownTimeout = System.TimeSpan.FromSeconds(20);
});
});
适用于 Web 应用的设置
一些主机设置仅适用于 HTTP 工作负荷。 默认情况下,用来配置这些设置的环境变量可以具有 DOTNET_
或 ASPNETCORE_
前缀。
IWebHostBuilder
上的扩展方法适用于这些设置。 显示如何调用扩展方法的示例代码假定 webBuilder
是 IWebHostBuilder
的实例,如以下示例所示:
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.CaptureStartupErrors(true);
webBuilder.UseStartup<Startup>();
});
CaptureStartupErrors
当 false
时,启动期间出错导致主机退出。 当 true
时,主机在启动期间捕获异常并尝试启动服务器。
键:captureStartupErrors
类型:(true
/1
或 false
/0
)
默认值:默认为 ,除非应用使用 Kestrel 在 IIS 后方运行,其中默认值是 true
。
环境变量:{PREFIX_}CAPTURESTARTUPERRORS
要设置此值,使用配置或调用 CaptureStartupErrors
:
webBuilder.CaptureStartupErrors(true);
DetailedErrors
如果启用,或环境为 Development
,应用会捕获详细错误。
键:detailedErrors
类型:(true
/1
或 false
/0
)
默认:false
环境变量:{PREFIX_}DETAILEDERRORS
要设置此值,使用配置或调用 UseSetting
:
webBuilder.UseSetting(WebHostDefaults.DetailedErrorsKey, "true");
HostingStartupAssemblies
承载启动程序集的以分号分隔的字符串在启动时加载。 虽然配置值默认为空字符串,但是承载启动程序集会始终包含应用的程序集。 提供承载启动程序集时,当应用在启动过程中生成其公用服务时将它们添加到应用的程序集加载。
键:hostingStartupAssemblies
类型:string
默认:空字符串
环境变量:{PREFIX_}HOSTINGSTARTUPASSEMBLIES
要设置此值,使用配置或调用 UseSetting
:
webBuilder.UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2");
HostingStartupExcludeAssemblies
承载启动程序集的以分号分隔的字符串在启动时排除。
键:hostingStartupExcludeAssemblies
类型:string
默认:空字符串
环境变量:{PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES
要设置此值,使用配置或调用 UseSetting
:
webBuilder.UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2");
HTTPS_Port
HTTPS 重定向端口。 用于强制实施 HTTPS。
键:https_port
类型:string
默认:未设置默认值。
环境变量:{PREFIX_}HTTPS_PORT
要设置此值,使用配置或调用 UseSetting
:
webBuilder.UseSetting("https_port", "8080");
PreferHostingUrls
指示主机是否应该侦听使用 IWebHostBuilder
配置的 URL,而不是使用 IServer
实现配置的 URL。
键:preferHostingUrls
类型:(true
/1
或 false
/0
)
默认:false
环境变量:{PREFIX_}PREFERHOSTINGURLS
若要设置此值,请使用环境变量或调用 PreferHostingUrls
:
webBuilder.PreferHostingUrls(true);
PreventHostingStartup
阻止承载启动程序集自动加载,包括应用的程序集所配置的承载启动程序集。 有关详细信息,请参阅在 ASP.NET Core 中使用托管启动程序集。
键:preventHostingStartup
类型:(true
/1
或 false
/0
)
默认:false
环境变量:{PREFIX_}PREVENTHOSTINGSTARTUP
若要设置此值,请使用环境变量或调用 UseSetting
:
webBuilder.UseSetting(WebHostDefaults.PreventHostingStartupKey, "true");
StartupAssembly
要搜索 Startup
类的程序集。
键:startupAssembly
类型:string
默认:应用的程序集
环境变量:{PREFIX_}STARTUPASSEMBLY
若要设置此值,请使用环境变量或调用 UseStartup
。 UseStartup
可以采用程序集名称 (string
) 或类型 (TStartup
)。 如果调用多个 UseStartup
方法,优先选择最后一个方法。
webBuilder.UseStartup("StartupAssemblyName");
webBuilder.UseStartup<Startup>();
SuppressStatusMessages
启用后,将取消承载启动状态消息。
键:suppressStatusMessages
类型:(true
/1
或 false
/0
)
默认:false
环境变量:{PREFIX_}SUPPRESSSTATUSMESSAGES
要设置此值,使用配置或调用 UseSetting
:
webBuilder.UseSetting(WebHostDefaults.SuppressStatusMessagesKey, "true");
URL
IP 地址或主机地址的分号分隔列表,其中包含服务器应针对请求侦听的端口和协议。 例如 http://localhost:123
。 使用“*”指示服务器应针对请求侦听的使用特定端口和协议(例如 http://*:5000
)的 IP 地址或主机名。 协议(http://
或 https://
)必须包含每个 URL。 不同的服务器支持的格式有所不同。
键:urls
类型:string
默认值:http://localhost:5000
和 https://localhost:5001
环境变量:{PREFIX_}URLS
若要设置此值,请使用环境变量或调用 UseUrls
:
webBuilder.UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002");
Kestrel 具有自己的终结点配置 API。 有关详细信息,请参阅 ASP.NET Core 中的 Kestrel Web 服务器。
WebRoot
IWebHostEnvironment.WebRootPath 属性可确定应用静态资产的相对路径。 如果该路径不存在,则使用无操作文件提供程序。
键:webroot
类型:string
默认:默认值为 wwwroot
。 {content root}/wwwroot 的路径必须存在。
环境变量:{PREFIX_}WEBROOT
若要设置此值,请使用环境变量或对 IWebHostBuilder
调用 UseWebRoot
:
webBuilder.UseWebRoot("public");
有关详细信息,请参见:
管理主机生存期
对生成的 IHost 实现调用方法,以启动和停止应用。 这些方法会影响所有在服务容器中注册的 IHostedService 实现。
Run*
和 Start*
方法之间的差异是 Run*
方法会在返回之前等待主机完成,而 Start*
方法会立即返回。 Run*
方法通常用于控制台应用,而 Start*
方法则通常用于长期运行的服务中。
运行
Run 运行应用并阻止调用线程,直到关闭主机。
RunAsync
RunAsync 运行应用并返回在触发取消令牌或关闭时完成的 Task。
RunConsoleAsync
RunConsoleAsync 启用控制台支持、生成和启动主机,以及等待 Ctrl+C/SIGINT (Windows)、⌘+C (macOS) 或 SIGTERM 关闭。
开始
Start 同步启动主机。
StartAsync
StartAsync 启动主机并返回在触发取消令牌或关闭时完成的 Task。
在 StartAsync
开始时调用 WaitForStartAsync,在继续之前,会一直等待该操作完成。 此方法可用于延迟启动,直到外部事件发出信号。
StopAsync
StopAsync 尝试在提供的超时时间内停止主机。
WaitForShutdown
WaitForShutdown 阻止调用线程,直到 IHostLifetime 触发关闭,例如通过 Ctrl+C/SIGINT (Windows)、⌘+C (macOS) 或 SIGTERM。
WaitForShutdownAsync
WaitForShutdownAsync 返回在通过给定的令牌和调用 StopAsync 来触发关闭时完成的 Task。
外部控件
使用可从外部调用的方法,能够实现对主机生存期的直接控制:
public class Program
{
private IHost _host;
public Program()
{
_host = new HostBuilder()
.Build();
}
public async Task StartAsync()
{
_host.StartAsync();
}
public async Task StopAsync()
{
using (_host)
{
await _host.StopAsync(TimeSpan.FromSeconds(5));
}
}
}
其他资源
- 在 ASP.NET Core 中使用托管服务实现后台任务
- GitHub 链接到通用主机源
注意
指向 .NET 参考源的文档链接通常会加载存储库的默认分支,该分支表示针对下一个 .NET 版本的当前开发。 若要为特定版本选择标记,请使用“切换分支或标记”下拉列表。 有关详细信息,请参阅如何选择 ASP.NET Core 源代码的版本标记 (dotnet/AspNetCore.Docs #26205)。