.NET 通用主机和Web主机

辅助角色服务模板会创建一个 .NET 通用主机 HostBuilder。 通用主机可用于其他类型的 .NET 应用程序，如控制台应用。

主机是封装应用资源和生存期功能的对象，例如：

• 依赖关系注入 (DI)
• Logging
• Configuration
• 应用关闭
• IHostedService 实现

当主机启动时，它将对在托管服务的服务容器集合中注册的 IHostedService 的每个实现调用 IHostedService.StartAsync。 在辅助角色服务应用中，包含 BackgroundService 实例的所有 IHostedService 实现都调用其 BackgroundService.ExecuteAsync 方法。

一个主机对象中包含所有应用的相互依赖资源的主要原因是生存期管理：控制应用启动和正常关闭。 这是通过 Microsoft.Extensions.Hosting NuGet 包实现的。

设置主机

主机通常由 Program 类中的代码配置、生成和运行。 Main 方法：

• 调用 CreateDefaultBuilder() 方法以创建和配置生成器对象。
• 调用 Build() 以创建 IHost 实例。
• 对主机对象调用 Run 或 RunAsync 方法。

.NET 辅助角色服务模板会生成以下代码来创建通用主机：

IHost host = Host.CreateDefaultBuilder(args)
    .ConfigureServices((hostContext, services) =>
    {
        //装配主机
         services.AddHostedService<Worker>();
    })
    .Build();

host.Run();

默认生成器设置

CreateDefaultBuilder 方法：

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

ConfigureServices 方法公开了向 Microsoft.Extensions.DependencyInjection.IServiceCollection 实例添加服务的功能。 以后，可以通过依赖关系注入获取这些服务。

框架提供的服务

自动注册以下服务：

• IHostApplicationLifetime
• IHostLifetime
• IHostEnvironment

IHostApplicationLifetime

将 IHostApplicationLifetime 服务注入任何类以处理启动后和正常关闭任务。 接口上的三个属性是用于注册应用启动和应用停止事件处理程序方法的取消令牌。 该接口还包括 StopApplication() 方法。

以下示例是注册 IHostApplicationLifetime 事件的 IHostedService 实现：

using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

namespace AppLifetime.Example;

public sealed class ExampleHostedService : IHostedService
{
    private readonly ILogger _logger;

    public ExampleHostedService(
        ILogger<ExampleHostedService> logger,
        IHostApplicationLifetime appLifetime)
    {
        _logger = logger;

        appLifetime.ApplicationStarted.Register(OnStarted);
        appLifetime.ApplicationStopping.Register(OnStopping);
        appLifetime.ApplicationStopped.Register(OnStopped);
    }

    public Task StartAsync(CancellationToken cancellationToken)
    {
        _logger.LogInformation("1. StartAsync has been called.");

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
    {
        _logger.LogInformation("4. StopAsync has been called.");

        return Task.CompletedTask;
    }

    private void OnStarted()
    {
        _logger.LogInformation("2. OnStarted has been called.");
    }

    private void OnStopping()
    {
        _logger.LogInformation("3. OnStopping has been called.");
    }

    private void OnStopped()
    {
        _logger.LogInformation("5. OnStopped has been called.");
    }
}

可以修改辅助角色服务模板以添加 ExampleHostedService （会随着主机的启动而启动）实现：

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using AppLifetime.Example;

using IHost host = Host.CreateDefaultBuilder(args)
    .ConfigureServices((_, services) =>
        services.AddHostedService<ExampleHostedService>())
    .Build();

await host.RunAsync();

IHostLifetime

IHostLifetime 实现控制主机何时启动和何时停止。 使用了已注册的最后一个实现。 Microsoft.Extensions.Hosting.Internal.ConsoleLifetime 是默认的 IHostLifetime 实现。 有关关闭的生存期机制的详细信息，请参阅主机关闭。

IHostEnvironment

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

• IHostEnvironment.ApplicationName
• IHostEnvironment.ContentRootFileProvider
• IHostEnvironment.ContentRootPath
• IHostEnvironment.EnvironmentName

主机配置

主机配置用于配置 IHostEnvironment 实现的属性。

主机配置在 ConfigureAppConfiguration 方法的 HostBuilderContext.Configuration 中可用。

在调用 ConfigureAppConfiguration 后，HostBuilderContext.Configuration 被替换为应用配置。

若要添加主机配置，请对 IHostBuilder 调用 ConfigureHostConfiguration。 可多次调用 ConfigureHostConfiguration，并得到累计结果。 主机使用上一次在一个给定键上设置值的选项。

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;

using IHost host = Host.CreateDefaultBuilder(args)
    .ConfigureHostConfiguration(configHost =>
    {
        configHost.SetBasePath(Directory.GetCurrentDirectory());
        configHost.AddJsonFile("hostsettings.json", optional: true);
        configHost.AddEnvironmentVariables(prefix: "PREFIX_");
        configHost.AddCommandLine(args);
    })
    .Build();

// Application code should start here.

await host.RunAsync();

通过对 IHostBuilder 调用 ConfigureAppConfiguration 创建应用配置。 可多次调用 ConfigureAppConfiguration，并得到累计结果。 应用使用上一次在一个给定键上设置值的选项。

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

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

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

创建 WebApplicationBuilder 和 WebApplication，这提供了一种简化的方式来配置和运行 Web 应用程序，而不需要 Startup 类。 有关 WebApplicationBuilder 和 WebApplication 的详细信息，请参阅WebApplicationBuilder。

 主机定义

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

• 依赖关系注入 (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();

ConfigureWebHostDefaults 方法：

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

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

框架提供的服务

自动注册以下服务：

• IHostApplicationLifetime
• IHostLifetime
• IHostEnvironment / IWebHostEnvironment

有关从框架提供的服务的详细信息，请参阅 ASP.NET Core 中的依赖关系注入。

IHostLifetime

IHostLifetime 实现控制主机何时启动和何时停止。 使用了已注册的最后一个实现。

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime 是默认的 IHostLifetime 实现。 ConsoleLifetime:

• 侦听 CtrlC/SIGINT (Windows)、⌘C (macOS) 或 SIGTERM 并调用 来启动关闭进程。
• 解除阻止 RunAsync 和 WaitForShutdownAsync 等扩展。

IHostEnvironment

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

• ApplicationName
• EnvironmentName
• ContentRootPath

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

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

本部分列出了适用于 HTTP 和非 HTTP 工作负荷的主机设置。 默认情况下，用于配置这些设置的环境变量可以有一个 DOTNET_ 或 ASPNETCORE_ 前缀，该前缀在以下设置列表中显示为 {PREFIX_} 占位符。 有关详细信息，请参阅默认生成器设置部分和配置：环境变量。

应用程序和主机配置

ASP.NET Core 应用配置和启动“主机”。 主机负责应用程序启动和生存期管理。 ASP.NET Core 模板创建的 WebApplicationBuilder 包含主机。 虽然可以在主机和应用程序配置提供程序中完成一些配置，但通常，只有主机必需的配置才应在主机配置中完成。

应用程序配置具有最高优先级，下一部分对此进行了详细介绍。 主机配置遵循应用程序配置，本文对此进行了介绍

默认应用程序配置源

var builder = WebApplication.CreateBuilder(args);

WebApplication.CreateBuilder 使用预配置的默认值初始化 类的新实例。 经过初始化的 WebApplicationBuilder (builder) 按照以下顺序为应用提供默认配置（从最高优先级到最低优先级）：

1. 使用命令行配置提供程序通过命令行参数提供。
2. 使用非前缀环境变量配置提供程序通过非前缀环境变量提供。
3. 应用在 环境中运行时的用户机密。
4. 使用 JSON 配置提供程序通过 appsettings.{Environment}.json 提供。 例如，appsettings.Production.json 和 appsettings.Development.json。
5. 使用 JSON 配置提供程序通过 appsettings.json 提供。
6. 回退到下一部分所述的主机配置。

默认主机配置源

以下列表包含从最高优先级到最低优先级的默认主机配置源：

1. 使用环境变量配置提供程序通过以 ASPNETCORE_ 为前缀的环境变量提供。
2. 使用命令行配置提供程序通过命令行参数提供
3. 使用环境变量配置提供程序通过以 DOTNET_ 为前缀的环境变量提供。

在主机和应用程序配置中设置配置值时，将使用应用程序配置。

主机变量

初始化主机生成器时，会提前锁定以下变量，并且它们不受应用程序配置的影响：

• 应用程序名称
• 环境名称，例如 Development、Production 和 Staging
• 内容根目录
• Web 根目录
• 是否要扫描托管启动程序集以及要扫描哪些程序集。
• 应用和库代码从 IHostBuilder.ConfigureAppConfiguration 回调中的 HostBuilderContext.Configuration 读取的变量。

从应用程序配置而不是主机配置读取所有其他主机设置。

URLS 是许多不是启动设置的常见主机设置之一。 与不在前一个列表中的所有其他主机设置一样，稍后会从应用程序配置中读取 URLS。主机配置是应用程序配置的后备，因此主机配置可用于设置 URLS，但它将被应用程序配置中的任何配置源（如 appsettings.json）覆盖。

安全性和用户机密

配置数据指南：

• 请勿在配置提供程序代码或纯文本配置文件中存储密码或其他敏感数据。 机密管理器工具可用于存储开发环境中的机密。
• 不要在开发或测试环境中使用生产机密。
• 请在项目外部指定机密，避免将其意外提交到源代码存储库。

默认情况下，将在 JSON 配置源后注册用户机密配置源。 因此，用户机密密钥优先于 appsettings.json 和 appsettings.{Environment}.json 中的密钥。

有关存储密码或其他敏感数据的详细信息：

• 在 ASP.NET Core 中使用多个环境
• 在 ASP.NET Core 开发环境中安全存储应用机密：包括有关使用环境变量存储敏感数据的建议。 机密管理器工具使用文件配置提供程序将用户机密存储在本地系统上的 JSON 文件中。