Универсальный узел .NET в ASP.NET Core

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

С помощью шаблонов ASP.NET Core создаются WebApplicationBuilder и WebApplication, которые обеспечивают упрощенный способ настройки и запуска веб-приложений без класса Startup. Дополнительные сведения о WebApplicationBuilder и WebApplication см. в статье Миграция с ASP.NET Core 5.0 на 6.0.

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

Определение узла

Узел — это объект, который инкапсулирует все ресурсы приложения, такие как:

• Внедрение зависимостей
• Ведение журнала
• Настройка
• Реализации IHostedService

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

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

Создание узла

Узел обычно настраивается, собирается и выполняется кодом в классе Program.cs. С помощью следующего кода создается узел с одной реализацией IHostedService, добавленной в контейнер внедрения зависимостей:

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

Для рабочей нагрузки HTTP вызовите ConfigureWebHostDefaults после CreateDefaultBuilder:

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

Параметры построителя по умолчанию

Метод CreateDefaultBuilder:

• В качестве корневого каталога содержимого задает путь, возвращенный методом GetCurrentDirectory.
• Загружает конфигурацию узла из:
  • Переменные среды с префиксом DOTNET_.
  • аргументы командной строки.
• Загружает конфигурацию приложения из:
  • appsettings.json.
  • appsettings.{Environment}.json.
  • секреты пользователя, когда приложение выполняется в среде Development;
  • среды.
  • аргументы командной строки.
• Добавляет следующие поставщики ведения журнала :
  • Консоль
  • Отладка
  • EventSource
  • Журнал событий (только при запуске в Windows)
• Включает проверку области и проверку зависимостей, если это среда разработки.

Метод ConfigureWebHostDefaults:

• Загружает конфигурацию узла из переменных среды с префиксом ASPNETCORE_.
• Задает сервер Kestrel в качестве веб-сервера и настраивает его с помощью поставщиков конфигурации размещения приложения. Параметры сервера Kestrel по умолчанию см. в статье Настройка параметров веб-сервера Kestrel для ASP.NET Core.
• Добавляет ПО промежуточного слоя фильтрации узлов.
• Добавляет Параметры ПО промежуточного слоя перенаправления заголовков, если ASPNETCORE_FORWARDEDHEADERS_ENABLED равно true.
• Обеспечивает интеграцию служб IIS. Параметры служб IIS по умолчанию см. в статье Размещение ASP.NET Core в Windows со службами IIS.

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

Платформенные службы

Следующие службы регистрируются автоматически.

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

IHostLifetime

Реализация IHostLifetime контролирует, когда узел запускается и останавливается. Используется последняя зарегистрированная реализация.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime — это реализация IHostLifetime по умолчанию. ConsoleLifetime:

• Ожидает передачи данных с использованием сигналов CTRL+C/SIGINT (Windows), ⌘+C (macOS) или SIGTERM и вызывает метод StopApplication для запуска процесса завершения работы.
• разблокирует расширения, такие как RunAsync и WaitForShutdownAsync.

IHostEnvironment

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

• ApplicationName
• EnvironmentName
• ContentRootPath

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

Конфигурация узла

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

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

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

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

конфигурация приложения;

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

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

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

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

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

ApplicationName

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

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

Чтобы задать это значение, используйте переменную среды.

ContentRoot

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

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

Чтобы задать это значение, используйте переменную среды или вызов UseContentRoot в IHostBuilder:

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

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

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

EnvironmentName

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

Ключ: environment
Тип: string
По умолчанию: Production
переменной среды: {PREFIX_}ENVIRONMENT

Чтобы задать это значение, используйте переменную среды или вызов UseEnvironment в IHostBuilder:

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

ShutdownTimeout

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

• Активирует 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
Тип: bool (true или false)
По умолчанию: true
Аргумент командной строки: hostBuilder:reloadConfigOnChange
переменной среды: {PREFIX_}hostBuilder:reloadConfigOnChange

Предупреждение

Двоеточие (:) не работает в качестве разделителя с иерархическими ключами переменных среды на всех платформах. Дополнительную информацию см. в разделе Переменные среды.

Параметры для веб-приложений

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

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

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

CaptureStartupErrors

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

Ключ: captureStartupErrors
Тип: bool (true/1 или false/0)
Значение по умолчанию: false, если только приложение не работает с сервером Kestrel за IIS; в этом случае значение по умолчанию — true.
переменной среды: {PREFIX_}CAPTURESTARTUPERRORS

Чтобы задать это значение, используйте конфигурацию или вызов CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

DetailedErrors

Если этот параметр включен или если среда имеет значение Development, приложение перехватывает подробные ошибки.

Ключ: detailedErrors
Тип: bool (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. Этот параметр не приводит к тому, что сервер будет прослушивать указанный порт. То есть можно случайно перенаправить запросы на неиспользуемый порт.

Ключ: тип: https_portstring
Значение по умолчанию: значение по умолчанию не задано.
переменной среды: {PREFIX_}HTTPS_PORT

Чтобы задать это значение, используйте конфигурацию или вызов UseSetting:

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

HTTPS_Ports

Порты для прослушивания подключений HTTPS.

Ключ: https_ports
Тип: string
Значение по умолчанию: значение по умолчанию не задано.
переменной среды: {PREFIX_}HTTPS_PORTS

Чтобы задать это значение, используйте конфигурацию или вызов UseSetting:

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

PreferHostingUrls

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

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

Чтобы задать это значение, используйте переменную среды или вызов PreferHostingUrls:

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

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

Ключ: preventHostingStartup
Тип: bool (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
Тип: bool (true/1 или false/0)
По умолчанию: false
переменной среды: {PREFIX_}SUPPRESSSTATUSMESSAGES

Чтобы задать это значение, используйте конфигурацию или вызов UseSetting:

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

URL-адреса

Разделенный точками с запятой список IP-адресов или адресов узлов с портами и протоколами, по которым сервер должен ожидать получения запросов. Например, http://localhost:123. Используйте символ "*", чтобы указать, что сервер должен ожидать получения запросов через определенный порт и по определенному протоколу по любому IP-адресу или имени узла (например, http://*:5000). Протокол (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 настройки конечных точек. Дополнительные сведения см. в статье KestrelНастройка конечных точек для веб-сервера для ASP.NET Core.

Корневой каталог документов

Свойство IWebHostEnvironment.WebRootPath определяет относительный путь к статическим ресурсам приложения. Если этот путь не существует, используется фиктивный поставщик файлов.

Ключ: webroot
Тип: string
По умолчанию: значение по умолчанию — wwwroot. Наличие пути {корневой_каталог_содержимого}/wwwroot обязательно.
переменной среды: {PREFIX_}WEBROOT

Чтобы задать это значение, используйте переменную среды или вызов UseWebRoot в IWebHostBuilder:

webBuilder.UseWebRoot("public");

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

• Основы: корневой веб-каталог
• 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, который завершается при активации токена отмены или завершении работы.

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

StopAsync

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

WaitForShutdown

WaitForShutdown блокирует вызывающий поток до завершения работы, активированного IHostLifetime, например через CTRL+C/SIGINT (Windows), ⌘+C (macOS) или SIGTERM.

WaitForShutdownAsync

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

Дополнительные ресурсы

• Фоновые задачи с размещенными службами в ASP.NET Core
• Ссылка в GitHub на исходный код универсального узла

  Примечание.

  По ссылкам в документации на справочные материалы по .NET обычно загружается ветвь репозитория по умолчанию, которая представляет текущую разработку для следующего выпуска .NET. Чтобы выбрать тег для определенного выпуска, используйте раскрывающийся список Switch branches or tags (Переключение ветвей или тегов). Дополнительные сведения см. в статье Выбор тега версии исходного кода ASP.NET Core (dotnet/AspNetCore.Docs #26205).