Хост .NET Generic в ASP.NET Core

В этой статье приведены сведения об использовании универсального узла .NET в ASP.NET Core. Сведения об использовании универсального узла .NET в консольных приложениях см. в статье Универсальный узел .NET.

Понимание роли хоста

Хост — это объект, инкапсулирующий ресурсы приложения, например:

• Внедрение зависимостей
• Logging
• Configuration
• Реализации IHostedService

При запуске хоста вызывается метод StartAsync для каждого экземпляра IHostedService, зарегистрированного в коллекции размещенных служб контейнера служб. В веб-приложении одна из реализаций IHostedService является веб-службой, которая запускает реализацию сервера HTTP.

Включив все межзависимые ресурсы приложения в одном объекте, узел обеспечивает контроль запуска приложения и корректного завершения работы.

Настройка хоста

Хост обычно настраивается, создаётся и выполняется с помощью кода в файле Program.cs.

await Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        services.AddHostedService<SampleHostedService>();
    })
    .Build()
    .RunAsync();

await Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseStartup<Startup>();
    })
    .Build()
    .RunAsync();

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>();
            });
}

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>();
            });
}

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

Настройка параметров построителя по умолчанию

Метод CreateDefaultBuilder выполняет следующие задачи:

• Устанавливает корневой каталог содержимого на путь, возвращенный методом GetCurrentDirectory.

• Загружает конфигурацию узла из следующих источников:

  • Переменные среды, префиксированные с префиксом DOTNET_
  • Аргументы командной строки

• Загружает конфигурацию приложения в следующем порядке:

  • файл appsettings.json
  • appsettings.{Environment}.json
  • Секреты пользователей (загружаются с помощью входной сборки при запуске приложения в Development среде.)
  • Переменные среды
  • Аргументы командной строки

• Добавляет следующие поставщики ведения журнала :

  • Console
  • Debug
  • EventSource
  • Журнал событий (только при запуске в Windows)

• Включает проверку области и проверку зависимостей при использовании Developmentсреды.

Метод ConfigureWebHostDefaults выполняет следующие задачи:

• Загружает конфигурацию узла из переменных среды с префиксом ASPNETCORE_.

• Задает Kestrel сервер в качестве веб-сервера и настраивает его с помощью поставщиков конфигурации хостинга приложения. Параметры сервера Kestrel по умолчанию см. в статье Настройка параметров веб-сервера Kestrel для ASP.NET Core.

• Добавляет промежуточное ПО для фильтрации хостов.

• Добавляет промежуточное ПО для переадресации заголовков, если свойству задано значение ASPNETCORE_FORWARDEDHEADERS_ENABLED.

• Включает интеграцию IIS. Параметры служб IIS по умолчанию см. в статье Размещение ASP.NET Core в Windows со службами IIS.

Дополнительные сведения о переопределении параметров построителя по умолчанию см. в разделе "Настройка параметров для всех типов приложений " и "Настройка параметров для веб-приложений " далее в этой статье.

Сервисы, предоставляемые фреймворком

Универсальный хост .NET автоматически регистрирует следующие службы:

• IHostApplicationLifetime
• IHostLifetime
• IHostEnvironment / IWebHostEnvironment

Дополнительные сведения о службах, предоставляемых платформой, см. в разделе Внедрение зависимостей в ASP.NET Core.

IHostApplicationLifetime

Внедрите службу IHostApplicationLifetime (ранее IApplicationLifetime) в любой класс для выполнения задач после запуска и корректного завершения работы. Три свойства интерфейса — это маркеры отмены, которые используются для регистрации методов обработчика событий запуска приложения и остановки приложения. Кроме того, интерфейс включает метод StopApplication, который позволяет приложениям запрашивать корректное завершение работы.

При корректном завершении работы хост выполняет следующие задачи:

• Запускает обработчики событий ApplicationStopping, которые позволяют приложению запускать логику до начала процесса завершения работы.

• Останавливает работу сервера, который отключает новые подключения. Сервер ожидает завершения запросов к существующим подключениям, пока позволяет время ожидания завершения работы. Сервер отправляет заголовок закрытия соединения для последующих запросов по существующим подключениям.

• Запускает обработчики событий ApplicationStopped, которые позволяют приложению запускать логику после завершения его работы.

Ниже приведен пример реализации IHostedService, которая регистрирует обработчики событий IHostApplicationLifetime:

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()
    {
        // ...
    }
}

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), CTRL+C (macOS) или SIGTERM и вызовы StopApplication, которые запускают процесс завершения работы.

• Разблокирует расширения, такие как запуск методов RunAsync и WaitForShutdownAsync .

IHostEnvironment (IWebHostEnvironment)

Внедряет службу IHostEnvironment в класс, чтобы получить сведения о следующих параметрах.

• ApplicationName
• EnvironmentName
• ContentRootPath

Веб-приложения реализуют интерфейс IWebHostEnvironment, который наследует IHostEnvironment и добавляет WebRootPath.

Настройка конфигурации узла

Конфигурация хоста используется для свойств реализации IHostEnvironment.

Конфигурация узла доступна из Configuration свойства внутри ConfigureAppConfiguration метода. После ConfigureAppConfigurationHostBuilderContext.Configuration заменяется конфигурацией приложения.

Чтобы добавить конфигурацию узла, вызовите ConfigureHostConfiguration метод в экземпляре IHostBuilder . Метод ConfigureHostConfiguration может вызываться несколько раз с накоплением результатов. Хост использует тот вариант, который устанавливает значение последним для данного ключа.

CreateDefaultBuilder включает поставщик переменной среды с префиксом DOTNET_ и аргументами командной строки. Для веб-приложений добавляется поставщик переменных среды с префиксом 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);
    });

// 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);
    });

Создание конфигурации приложения

Конфигурация приложения создается путем вызова ConfigureAppConfiguration метода в экземпляре IHostBuilder . Метод ConfigureAppConfiguration может вызываться несколько раз с накоплением результатов. Приложение использует тот вариант, который последним присвоил значение для данного ключа.

Конфигурация, созданная ConfigureAppConfiguration, доступна в свойстве Configuration для последующих операций и в качестве службы, доступной через DI. Конфигурация хоста также добавляется к конфигурации приложения.

Дополнительные сведения см. в разделе Конфигурация в ASP.NET Core.

Настройка параметров для всех типов приложений

В этом разделе перечислены параметры узла, которые применяются к рабочим нагрузкам HTTP и остальным.

По умолчанию переменные среды, используемые для настройки этих параметров, могут иметь префикс DOTNET_ или ASPNETCORE_, который отображается в следующем списке параметров в качестве заполнителя {PREFIX_}.

Дополнительные сведения см. в разделе "Настройка параметров построителя по умолчанию " и "Конфигурация: переменные среды".

Имя приложения

Определяет имя сборки, содержащей точку входа для приложения.

Ключ: applicationName
Тип: строка
По умолчанию: имя сборки с точкой входа приложения.
Настройка с помощью: переменная окружения
переменная среды: {PREFIX_}APPLICATIONNAME

Свойство ApplicationName задается из конфигурации узла во время построения узла.

Корень содержимого

Определяет, где хост начинает поиск файлов содержимого.

Ключ: contentRoot
Тип: строка
По умолчанию: папка, в которой находится сборка приложения.
Настройка с помощью: переменная среды или UseContentRoot в IHostBuilder
переменная среды: {PREFIX_}CONTENTROOT

Свойство ContentRootPath определяет, где хост начинает поиск. Если путь не существует, узел не запускается.

Host.CreateDefaultBuilder(args)
    .UseContentRoot("/path/to/content/root")
    // ...

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

Дополнительные сведения см. в разделе:

• Основы: корень содержимого
• Корневой каталог

Имя операционной среды

Задает имя для среды.

Ключ: environment
Тип: строка
По умолчанию:Production
Настройка использования: переменная среды или вызов UseEnvironmentIHostBuilder
переменная среды: {PREFIX_}ENVIRONMENT

Свойство EnvironmentName может иметь любое значение. В платформе определены значения Development, Staging и Production. Регистр символов в значениях не учитывается.

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

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

Время ожидания завершения работы

Указывает время ожидания завершения работы хоста.

Ключ: shutdownTimeoutSeconds
Тип: int
По умолчанию: 30 секунд (в .NET 5.0 и более ранних версиях значение по умолчанию составляет 5 секунд.)
Настройка с помощью: переменная среды или HostOptions
переменная среды: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

Свойство ShutdownTimeout задает время ожидания для StopAsync. Значение по умолчанию — 30 секунд.

В течение тайм-аута хост:

• Активирует ApplicationStopping.
• Пытается остановить размещенные службы, записывая в журнал ошибки для служб, которые не удалось остановить.

Если срок ожидания истекает до остановки всех размещенных служб, все оставшиеся активные службы останавливаются при завершении работы приложения. Службы останавливаются, даже если они по-прежнему обрабатываются. Если службе требуется больше времени для остановки, увеличьте время ожидания.

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

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

Настройка параметров для веб-приложений

Некоторые параметры узла применяются только к рабочим нагрузкам HTTP. По умолчанию переменные среды, используемые для настройки этих параметров, могут иметь префикс DOTNET_ или ASPNETCORE_, который отображается в следующем списке параметров в качестве заполнителя {PREFIX_}.

Методы расширения в IWebHostBuilder доступны для этих параметров. В примерах кода, которые показывают, как вызывать методы расширения, предполагается, что webBuilder является экземпляром IWebHostBuilder, как показано в следующем примере:

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

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

Запись ошибок запуска

Управляет записью ошибок запуска.

Ключ: captureStartupErrors
Тип: bool (true/1 или false/0)
по умолчанию: false. Если приложение выполняется за IIS, значение по умолчанию — Kestrel.
Настройка с помощью: конфигурация или CaptureStartupErrors
переменная среды: {PREFIX_}CAPTURESTARTUPERRORS

Если задано значение false, ошибки во время запуска приводят к завершению работы узла. Если true, хост перехватывает исключения во время запуска и пытается запустить сервер.

webBuilder.CaptureStartupErrors(true);

webBuilder.CaptureStartupErrors(true);

Подробные ошибки

Определяет, следует ли записывать подробные ошибки.

Ключ: detailedErrors
Тип: bool (true/1 или false/0)
По умолчанию:false
Настройка с помощью: конфигурация или UseSetting
переменная среды: {PREFIX_}DETAILEDERRORS

При включении или при установке среды Development, приложение фиксирует подробные ошибки.

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

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

Проведение встреч для стартапов

Предоставляет строку с запятой для размещения сборок запуска для загрузки при запуске.

Ключ: hostingStartupAssemblies
Тип: строка
Значение по умолчанию: пустая строка
Задается с помощью: UseSetting
переменная среды: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

Значение этого параметра конфигурации по умолчанию — пустая строка, однако начальные сборки хостинга всегда включают в себя сборку приложения. Если сборки для размещения при запуске предоставлены, они добавляются к сборке приложения, чтобы загружаться при построении общих служб приложения во время запуска.

webBuilder.UseSetting(
    WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2");

webBuilder.UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2");

Размещение стартапа исключает сборки

Предоставляет строку с запятой для размещения сборок запуска, которые следует исключить при запуске.

Ключ: hostingStartupExcludeAssemblies
Тип: строка
Значение по умолчанию: пустая строка
Настройка с помощью: конфигурация или UseSetting
переменная среды: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

webBuilder.UseSetting(
    WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2");

webBuilder.UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2");

Порт HTTPS

Задает порт HTTPS для перенаправления при получении подключения, отличного от HTTPS.

Ключ: https_port
Тип: строка
Значение по умолчанию: нет по умолчанию.
Настройка с помощью: конфигурация или UseSetting
переменная среды: {PREFIX_}HTTPS_PORT

Этот параметр используется при принудительном применении ПРОТОКОЛА HTTPS. Этот параметр не приводит к тому, что сервер будет прослушивать указанный порт. То есть можно случайно перенаправить запросы на неиспользуемый порт.

webBuilder.UseSetting("https_port", "8080");

webBuilder.UseSetting("https_port", "8080");

webBuilder.UseSetting("https_ports", "8080");

Предпочитать URL-адреса размещения

Указывает, должен ли хост прослушивать URL-адреса, настроенные с помощью IWebHostBuilder, вместо URL-адресов, настроенных с помощью реализации IServer.

Ключ: preferHostingUrls
Тип: bool (true/1 или false/0)
По умолчанию:false
Настройка с помощью: переменная среды или PreferHostingUrls
переменная среды: {PREFIX_}PREFERHOSTINGURLS

webBuilder.PreferHostingUrls(true);

webBuilder.PreferHostingUrls(true);

Предотвратить запуск хостинга

Запрещает автоматическую загрузку начальных сборок размещения, включая начальные сборки размещения, настроенные сборкой приложения. Дополнительные сведения см. в разделе Начальные сборки хостинга в ASP.NET Core.

Ключ: preventHostingStartup
Тип: bool (true/1 или false/0)
По умолчанию:false
Настройка с помощью: переменная среды или UseSetting
переменная среды: {PREFIX_}PREVENTHOSTINGSTARTUP

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

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

Запуск сборки

Указывает сборку для поиска класса Startup.

Ключ: startupAssembly
Тип: строка
По умолчанию: сборка приложения.
Настройка с помощью: переменная среды или UseStartup
переменная среды: {PREFIX_}STARTUPASSEMBLY

Можно ссылаться на сборку по имени (string) или типу (TStartup). Если вызывается несколько UseStartup методов, последний вызов имеет приоритет.

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

Подавление сообщений о состоянии

Указывает, следует ли подавлять сообщения о состоянии запуска хостинга.

Ключ: suppressStatusMessages
Тип: bool (true/1 или false/0)
По умолчанию:false
Настройка с помощью: конфигурация или UseSetting
переменная среды: {PREFIX_}SUPPRESSSTATUSMESSAGES

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

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

URL-адреса сервера

Задает IP-адреса или адреса узлов с портами и протоколами, по которым сервер должен ожидать получения запросов.

Ключ: urls
Тип: строка
Значения по умолчанию: http://localhost:5000 и https://localhost:5001
Настройка с помощью: переменная среды или UseUrls
переменная среды: {PREFIX_}URLS

Задайте для списка префиксов URL-адресов, разделенных точкой с запятой ;, на которые должен отвечать сервер. Например, http://localhost:123. Используйте подстановочный символ звездочка *, чтобы указать, что сервер должен прослушивать запросы с любого IP-адреса или узла, с использованием указанного порта и протокола (например, http://*:5000). Протокол (http:// или https://) должен указываться для каждого URL-адреса. Поддерживаемые форматы зависят от сервера.

webBuilder.UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002");

webBuilder.UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002");

Kestrel имеет собственный API настройки конечных точек. Дополнительные сведения см. в разделе "Настройка конечных точек для Kestrel веб-сервера".

Корень веб-сайта

Задает относительный путь к статическим ресурсам приложения.

Ключ: webroot
Тип: строка
По умолчанию:wwwroot
Настройка с помощью: переменная среды или UseWebRoot в IWebHostBuilder
переменная среды: {PREFIX_}WEBROOT

Свойство WebRootPath определяет относительный путь к статическим ресурсам приложения.

Путь к {content root}/wwwroot должен существовать. Если этот путь не существует, используется фиктивный поставщик файлов.

webBuilder.UseWebRoot("public");

webBuilder.UseWebRoot("public");

Дополнительные сведения см. в разделе:

• Основы: веб-корень
• Корень содержимого

Управление временем существования узла

Чтобы запустить и остановить приложение, вызовите методы реализации IHost . Методы влияют на все IHostedService реализации, зарегистрированные в контейнере служб.

Разница между методами Run* и Start* заключается в том, что методы Run* ожидают завершения работы хоста перед возвратом, в то время как методы Start* возвращаются немедленно. Методы Run* обычно используются в консольных приложениях, а методы Start* обычно используются в длительных сервисах.

Run

Метод Run запускает приложение и блокирует вызывающий поток до завершения работы узла.

RunAsync

Метод RunAsync запускает приложение и возвращает объект Task, который завершается при активации маркера отмены или завершении работы.

RunConsoleAsync

Этот RunConsoleAsync метод включает поддержку консоли, сборку и запуск узла и ожидает завершения работы ctrl+/SIGINT (Windows), CTRL+C (macOS) или SIGTERM.

Start

Метод Start запускает хост синхронно.

StartAsync

Метод StartAsync запускает главный процесс и возвращает объект Task, который завершается, когда активируется маркер отмены или выключение.

Метод WaitForStartAsync вызывается в начале StartAsync, и StartAsync ожидает его завершения, прежде чем продолжить. С помощью этого метода можно отложить запуск до получения сигнала от внешнего события.

StopAsync

Метод StopAsync пытается остановить хост в течение предоставленного времени ожидания.

WaitForShutdown

Метод WaitForShutdown блокирует вызывающий поток, пока реализация IHostLifetime не активирует завершение работы с помощью CTRLC/SIGINT (Windows), ++ (macOS) или SIGTERM.

WaitForShutdownAsync

Метод WaitForShutdownAsync возвращает объект Task, который завершается, когда завершение работы инициируется заданным токеном, а затем вызывает метод StopAsync.

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