ASP.NET Core 中的 .NET 通用主机

本文介绍如何使用 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();

默认生成器设置

CreateDefaultBuilder 方法：

• 将内容根目录设置为由 GetCurrentDirectory 返回的路径。
• 通过以下对象加载主机配置：
  • 前缀为 DOTNET_ 的环境变量。
  • 命令行参数。
• 通过以下对象加载应用配置：
  • appsettings.json。
  • appsettings.{Environment}.json。
  • 应用在 Development 环境中运行时的用户机密。
  • 环境变量。
  • 命令行参数。
• 添加以下日志记录提供程序：
  • 控制台
  • 调试
  • EventSource
  • EventLog（仅当在 Windows 上运行时）
• 当环境为“开发”时，启用范围验证和依赖关系验证。

ConfigureWebHostDefaults 方法：

• 从前缀为 ASPNETCORE_ 的环境变量加载主机配置。
• 使用应用的托管配置提供程序将 Kestrel 服务器设置为 web 服务器并对其进行配置。 有关 Kestrel 服务器的默认选项，请参阅Kestrel。
• 添加主机筛选中间件。
• 如果 ASPNETCORE_FORWARDEDHEADERS_ENABLED 等于 true，则添加转接头中间件。
• 支持 IIS 集成。 有关 IIS 默认选项，请参阅使用 IIS 在 Windows 上托管 ASP.NET Core。

本文中后面的所有应用类型的设置和 web 应用的设置部分介绍如何替代默认生成器设置。

框架提供的服务

自动注册以下服务：

• IHostApplicationLifetime
• IHostLifetime
• IHostEnvironment / IWebHostEnvironment

有关从框架提供的服务的详细信息，请参阅 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 服务注册到一个类，获取关于以下设置的信息：

• ApplicationName
• EnvironmentName
• ContentRootPath

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")
    // ...

有关详细信息，请参见:

• 基础知识：内容根目录
• WebRoot

EnvironmentName

IHostEnvironment.EnvironmentName 属性可以设置为任何值。 框架定义的值包括 DevelopmentStaging 和 Production。 值不区分大小写。

键：environment
类型：string
默认：Production
环境变量：{PREFIX_}ENVIRONMENT

若要设置此值，请使用环境变量或对 IHostBuilder 调用 UseEnvironment：

Host.CreateDefaultBuilder(args)
    .UseEnvironment("Development")
    // ...

ShutdownTimeout

HostOptions.ShutdownTimeout 设置 StopAsync 的超时值。 默认值为 5 秒。 在超时时间段中，主机：

• 触发 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");

有关详细信息，请参见:

• 基础知识：Web 根目录
• ContentRoot

管理主机生存期

对生成的 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 中使用托管服务实现后台任务
• GitHub 链接到通用主机源

  注意

  指向 .NET 参考源的文档链接通常会加载存储库的默认分支，该分支表示针对下一个 .NET 版本的当前开发。 若要为特定版本选择标记，请使用“切换分支或标记”下拉列表。 有关详细信息，请参阅如何选择 ASP.NET Core 源代码的版本标记 (dotnet/AspNetCore.Docs #26205)。