ASP.NET Core 模板会创建一个 .NET Core 泛型主机 (HostBuilder)。

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

主机定义

主机是封装应用资源的对象，例如：

依赖关系注入 (DI)
Logging
Configuration
IHostedService 实现

当主机启动时，它将对在托管服务的服务容器集合中注册的 IHostedService 的每个实现调用 IHostedService.StartAsync。在 web 应用中，其中一个 IHostedService 实现是启动 HTTP 服务器实现的 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 创建。

默认生成器设置

CreateDefaultBuilder 方法：

将内容根目录设置为由 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 应用的设置部分介绍如何替代默认生成器设置。

框架提供的服务

自动注册以下服务：

IHostApplicationLifetime
IHostLifetime
IHostEnvironment / IWebHostEnvironment

有关框架提供的服务的详细信息，请参阅 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 或 SIGTERM 并调用 StopApplication 来启动关闭进程。
解除阻止 RunAsync 和 WaitForShutdownAsync 等扩展。

IHostEnvironment

将 IHostEnvironment 服务注册到一个类，获取关于以下设置的信息：

ApplicationName
EnvironmentName
ContentRootPath

Web 应用实现 IWebHostEnvironment 接口，该接口继承 IHostEnvironment 并添加 WebRootPath。

主机配置

主机配置用于 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，并得到累计结果。应用使用上一次在一个给定键上设置值的选项。

由 ConfigureAppConfiguration 创建的配置可以通过 HostBuilderContext.Configuration 获取以用于后续操作，也可以通过 DI 作为服务获取。主机配置也会添加到应用配置。

有关详细信息，请参阅 ASP.NET Core 中的配置。

适用于所有应用类型的设置

本部分列出了适用于 HTTP 和非 HTTP 工作负荷的主机设置。默认情况下，用来配置这些设置的环境变量可以具有 DOTNET_ 或 ASPNETCORE_ 前缀。有关详细信息，请参阅默认生成器设置部分。

ApplicationName

IHostEnvironment.ApplicationName 属性是在主机构造期间通过主机配置设定的。

键：applicationName
类型：string
默认：包含应用入口点的程序集的名称。
环境变量：<PREFIX_>APPLICATIONNAME

要设置此值，请使用环境变量。

ContentRoot

IHostEnvironment.ContentRootPath 属性决定主机从什么位置开始搜索内容文件。如果路径不存在，主机将无法启动。

键：contentRoot
类型：string
默认：应用程序集所在的文件夹。
环境变量：<PREFIX_>CONTENTROOT

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

Host.CreateDefaultBuilder(args)
    .UseContentRoot("c:\content-root")
    //...

有关详情，请参阅：

基础知识：内容根目录
WebRoot

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
类型：bool（true 或 1）
默认：true
命令行参数：hostBuilder:reloadConfigOnChange
环境变量：<PREFIX_>hostBuilder:reloadConfigOnChange

警告

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

适用于 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
类型：bool（true 或 1）
默认：默认为 false，除非应用使用 Kestrel 在 IIS 后方运行，其中默认值是 true。
环境变量：<PREFIX_>CAPTURESTARTUPERRORS

若要设置此值，使用配置或调用 CaptureStartupErrors：

webBuilder.CaptureStartupErrors(true);

DetailedErrors

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

键：detailedErrors
类型：bool（true 或 1）
默认：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
类型：bool（true 或 1）
默认：true
环境变量：<PREFIX_>_PREFERHOSTINGURLS

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

webBuilder.PreferHostingUrls(false);

PreventHostingStartup

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

键：preventHostingStartup
类型：bool（true 或 1）
默认：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>();

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 运行应用并阻止调用线程，直到关闭主机。

RunAsync

RunAsync 运行应用并返回在触发取消令牌或关闭时完成的 Task。

RunConsoleAsync

RunConsoleAsync 启用控制台支持、生成和启动主机，以及等待 Ctrl+C/SIGINT 或 SIGTERM 关闭。

Start

Start 同步启动主机。

StartAsync

StartAsync 启动主机并返回在触发取消令牌或关闭时完成的 Task。

在 StartAsync 开始时调用 WaitForStartAsync，在继续之前，会一直等待该操作完成。它可用于延迟启动，直到外部事件发出信号。

StopAsync

StopAsync 尝试在提供的超时时间内停止主机。

WaitForShutdown

WaitForShutdown 阻止调用线程，直到 IHostLifetime 触发关闭，例如通过 Ctrl+C/SIGINT 或 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.netcorewebapi的简单实例，主机屋不支持asp

主机定义

设置主机

默认生成器设置

框架提供的服务

IHostApplicationLifetime

IHostLifetime

IHostEnvironment

主机配置

应用配置

适用于所有应用类型的设置

ApplicationName

ContentRoot

EnvironmentName

ShutdownTimeout

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

适用于 Web 应用的设置

CaptureStartupErrors

DetailedErrors

HostingStartupAssemblies

HostingStartupExcludeAssemblies

HTTPS_Port

PreferHostingUrls

PreventHostingStartup

StartupAssembly

URL

WebRoot

管理主机生存期

运行

RunAsync

RunConsoleAsync

Start

StartAsync

StopAsync

WaitForShutdown

WaitForShutdownAsync

外部控件

相关推荐

热门推荐

分类目录