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

注意

此版本不是本文的最新版本。 对于当前版本,请参阅此文的 .NET 8 版本

警告

此版本的 ASP.NET Core 不再受支持。 有关详细信息,请参阅 .NET 和 .NET Core 支持策略。 对于当前版本,请参阅此文的 .NET 8 版本

重要

此信息与预发布产品相关,相应产品在商业发布之前可能会进行重大修改。 Microsoft 对此处提供的信息不提供任何明示或暗示的保证。

对于当前版本,请参阅此文的 .NET 8 版本

本文介绍如何使用 ASP.NET Core 中的 .NET 通用主机。

这些 ASP.NET Core 模板创建 WebApplicationBuilderWebApplication,这提供了一种简化的方式来配置和运行 Web 应用程序,而不需要 Startup 类。 有关 WebApplicationBuilderWebApplication 的详细信息,请参阅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 应用的设置部分介绍如何替代默认生成器设置。

框架提供的服务

自动注册以下服务:

有关从框架提供的服务的详细信息,请参阅 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

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 属性可以设置为任何值。 框架定义的值包括 DevelopmentStagingProduction。 值不区分大小写。

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

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

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

ShutdownTimeout

HostOptions.ShutdownTimeout 设置 StopAsync 的超时值。 默认值为 30 秒。 在超时时间段中,主机:

如果在所有托管服务停止之前就达到了超时时间,则会在应用关闭时会终止剩余的所有活动的服务。 即使没有完成处理工作,服务也会停止。 如果停止服务需要更多时间,请增加超时时间。

键:shutdownTimeoutSeconds
类型:int
默认值:30 秒
环境变量{PREFIX_}SHUTDOWNTIMEOUTSECONDS

若要设置此值,请使用环境变量或配置 HostOptions。 以下示例将超时设置为 20 秒:

Host.CreateDefaultBuilder(args)
    .ConfigureServices((hostContext, services) =>
    {
        services.Configure<HostOptions>(options =>
        {
            options.ShutdownTimeout = TimeSpan.FromSeconds(20);
        });
    });

禁用“在更改时重载应用配置”

默认情况下,appsettings.jsonappsettings.{Environment}.json 会在文件发生更改时进行重载。 若要在 ASP.NET Core 5.0 或更高版本中禁用此重载行为,请将 hostBuilder:reloadConfigOnChange 键设置为 false

键:hostBuilder:reloadConfigOnChange
类型:truefalse
默认:true
命令行参数:
环境变量{PREFIX_}hostBuilder:reloadConfigOnChange

警告

所有平台上的环境变量分层键都不支持冒号 (:) 分隔符。 有关详细信息,请参阅环境变量

适用于 Web 应用的设置

一些主机设置仅适用于 HTTP 工作负荷。 默认情况下,用于配置这些设置的环境变量可以有一个 DOTNET_ASPNETCORE_ 前缀,该前缀在以下设置列表中显示为 {PREFIX_} 占位符。

IWebHostBuilder 上的扩展方法适用于这些设置。 显示如何调用扩展方法的示例代码假定 webBuilderIWebHostBuilder 的实例,如以下示例所示:

Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        // ...
    });

CaptureStartupErrors

false 时,启动期间出错导致主机退出。 当 true 时,主机在启动期间捕获异常并尝试启动服务器。

键:captureStartupErrors
类型:true/1false/0
默认值:默认为 ,除非应用使用 Kestrel 在 IIS 后方运行,其中默认值是 true
环境变量{PREFIX_}CAPTURESTARTUPERRORS

要设置此值,使用配置或调用 CaptureStartupErrors

webBuilder.CaptureStartupErrors(true);

DetailedErrors

如果启用,或环境为 Development,应用会捕获详细错误。

键:detailedErrors
类型:true/1false/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/1false/0
默认false
环境变量{PREFIX_}PREFERHOSTINGURLS

若要设置此值,请使用环境变量或调用 PreferHostingUrls

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

阻止承载启动程序集自动加载,包括应用的程序集所配置的承载启动程序集。 有关详细信息,请参阅在 ASP.NET Core 中使用托管启动程序集

键:preventHostingStartup
类型:true/1false/0
默认false
环境变量{PREFIX_}PREVENTHOSTINGSTARTUP

若要设置此值,请使用环境变量或调用 UseSetting

webBuilder.UseSetting(WebHostDefaults.PreventHostingStartupKey, "true");

StartupAssembly

要搜索 Startup 类的程序集。

键:startupAssembly
类型:string
默认:应用的程序集
环境变量{PREFIX_}STARTUPASSEMBLY

若要设置此值,请使用环境变量或调用 UseStartupUseStartup 可以采用程序集名称 (string) 或类型 (TStartup)。 如果调用多个 UseStartup 方法,优先选择最后一个方法。

webBuilder.UseStartup("StartupAssemblyName");
webBuilder.UseStartup<Startup>();

SuppressStatusMessages

启用后,将取消承载启动状态消息。

键:suppressStatusMessages
类型:true/1false/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:5000https://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 方法以创建和配置生成器对象。
  • 对生成器对象调用 BuildRun 方法。

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 创建

默认生成器设置

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 应用的设置部分介绍如何替代默认生成器设置。

框架提供的服务

自动注册以下服务:

有关从框架提供的服务的详细信息,请参阅 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

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 属性可以设置为任何值。 框架定义的值包括 DevelopmentStagingProduction。 值不区分大小写。

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

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

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

ShutdownTimeout

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

如果在所有托管服务停止之前就达到了超时时间,则会在应用关闭时会终止剩余的所有活动的服务。 即使没有完成处理工作,服务也会停止。 如果停止服务需要更多时间,请增加超时时间。

键:shutdownTimeoutSeconds
类型:int
默认:5 秒
环境变量{PREFIX_}SHUTDOWNTIMEOUTSECONDS

若要设置此值,请使用环境变量或配置 HostOptions。 以下示例将超时设置为 20 秒:

Host.CreateDefaultBuilder(args)
    .ConfigureServices((hostContext, services) =>
    {
        services.Configure<HostOptions>(option =>
        {
            option.ShutdownTimeout = System.TimeSpan.FromSeconds(20);
        });
    });

禁用“在更改时重载应用配置”

默认情况下,appsettings.jsonappsettings.{Environment}.json 会在文件发生更改时进行重载。 若要在 ASP.NET Core 5.0 或更高版本中禁用此重载行为,请将 hostBuilder:reloadConfigOnChange 键设置为 false

键:hostBuilder:reloadConfigOnChange
类型:truefalse
默认:true
命令行参数:
环境变量{PREFIX_}hostBuilder:reloadConfigOnChange

警告

所有平台上的环境变量分层键都不支持冒号 (:) 分隔符。 有关详细信息,请参阅环境变量

适用于 Web 应用的设置

一些主机设置仅适用于 HTTP 工作负荷。 默认情况下,用于配置这些设置的环境变量可以有一个 DOTNET_ASPNETCORE_ 前缀,该前缀在以下设置列表中显示为 {PREFIX_} 占位符。

IWebHostBuilder 上的扩展方法适用于这些设置。 显示如何调用扩展方法的示例代码假定 webBuilderIWebHostBuilder 的实例,如以下示例所示:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.CaptureStartupErrors(true);
            webBuilder.UseStartup<Startup>();
        });

CaptureStartupErrors

false 时,启动期间出错导致主机退出。 当 true 时,主机在启动期间捕获异常并尝试启动服务器。

键:captureStartupErrors
类型:true/1false/0
默认值:默认为 ,除非应用使用 Kestrel 在 IIS 后方运行,其中默认值是 true
环境变量{PREFIX_}CAPTURESTARTUPERRORS

要设置此值,使用配置或调用 CaptureStartupErrors

webBuilder.CaptureStartupErrors(true);

DetailedErrors

如果启用,或环境为 Development,应用会捕获详细错误。

键:detailedErrors
类型:true/1false/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/1false/0
默认false
环境变量{PREFIX_}PREFERHOSTINGURLS

若要设置此值,请使用环境变量或调用 PreferHostingUrls

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

阻止承载启动程序集自动加载,包括应用的程序集所配置的承载启动程序集。 有关详细信息,请参阅在 ASP.NET Core 中使用托管启动程序集

键:preventHostingStartup
类型:true/1false/0
默认false
环境变量{PREFIX_}PREVENTHOSTINGSTARTUP

若要设置此值,请使用环境变量或调用 UseSetting

webBuilder.UseSetting(WebHostDefaults.PreventHostingStartupKey, "true");

StartupAssembly

要搜索 Startup 类的程序集。

键:startupAssembly
类型:string
默认:应用的程序集
环境变量{PREFIX_}STARTUPASSEMBLY

若要设置此值,请使用环境变量或调用 UseStartupUseStartup 可以采用程序集名称 (string) 或类型 (TStartup)。 如果调用多个 UseStartup 方法,优先选择最后一个方法。

webBuilder.UseStartup("StartupAssemblyName");
webBuilder.UseStartup<Startup>();

SuppressStatusMessages

启用后,将取消承载启动状态消息。

键:suppressStatusMessages
类型:true/1false/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:5000https://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 方法以创建和配置生成器对象。
  • 对生成器对象调用 BuildRun 方法。

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 创建

默认生成器设置

CreateDefaultBuilder 方法:

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

ConfigureWebHostDefaults 方法:

本文中后面的所有应用类型的设置 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

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 属性可以设置为任何值。 框架定义的值包括 DevelopmentStagingProduction。 值不区分大小写。

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

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

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

ShutdownTimeout

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

如果在所有托管服务停止之前就达到了超时时间,则会在应用关闭时会终止剩余的所有活动的服务。 即使没有完成处理工作,服务也会停止。 如果停止服务需要更多时间,请增加超时时间。

键: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 上的扩展方法适用于这些设置。 显示如何调用扩展方法的示例代码假定 webBuilderIWebHostBuilder 的实例,如以下示例所示:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.CaptureStartupErrors(true);
            webBuilder.UseStartup<Startup>();
        });

CaptureStartupErrors

false 时,启动期间出错导致主机退出。 当 true 时,主机在启动期间捕获异常并尝试启动服务器。

键:captureStartupErrors
类型:true/1false/0
默认值:默认为 ,除非应用使用 Kestrel 在 IIS 后方运行,其中默认值是 true
环境变量{PREFIX_}CAPTURESTARTUPERRORS

要设置此值,使用配置或调用 CaptureStartupErrors

webBuilder.CaptureStartupErrors(true);

DetailedErrors

如果启用,或环境为 Development,应用会捕获详细错误。

键:detailedErrors
类型:true/1false/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/1false/0
默认false
环境变量{PREFIX_}PREFERHOSTINGURLS

若要设置此值,请使用环境变量或调用 PreferHostingUrls

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

阻止承载启动程序集自动加载,包括应用的程序集所配置的承载启动程序集。 有关详细信息,请参阅在 ASP.NET Core 中使用托管启动程序集

键:preventHostingStartup
类型:true/1false/0
默认false
环境变量{PREFIX_}PREVENTHOSTINGSTARTUP

若要设置此值,请使用环境变量或调用 UseSetting

webBuilder.UseSetting(WebHostDefaults.PreventHostingStartupKey, "true");

StartupAssembly

要搜索 Startup 类的程序集。

键:startupAssembly
类型:string
默认:应用的程序集
环境变量{PREFIX_}STARTUPASSEMBLY

若要设置此值,请使用环境变量或调用 UseStartupUseStartup 可以采用程序集名称 (string) 或类型 (TStartup)。 如果调用多个 UseStartup 方法,优先选择最后一个方法。

webBuilder.UseStartup("StartupAssemblyName");
webBuilder.UseStartup<Startup>();

SuppressStatusMessages

启用后,将取消承载启动状态消息。

键:suppressStatusMessages
类型:true/1false/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:5000https://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));
        }
    }
}

其他资源