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

Статья
11/06/2024

Примечание.

Это не последняя версия этой статьи. В текущем выпуске см . версию .NET 8 этой статьи.

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

Эта версия ASP.NET Core больше не поддерживается. Дополнительные сведения см. в статье о политике поддержки .NET и .NET Core. В текущем выпуске см . версию .NET 8 этой статьи.

Внимание

Эта информация относится к предварительному выпуску продукта, который может быть существенно изменен до его коммерческого выпуска. Майкрософт не предоставляет никаких гарантий, явных или подразумеваемых, относительно приведенных здесь сведений.

В текущем выпуске см . версию .NET 8 этой статьи.

В этой статье приведены сведения об использовании универсального узла .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");

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

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

Вызывает методы в реализации 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 создают .NET Core Generic Host (HostBuilder).

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

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

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

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

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

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

Узел обычно настраивается, собирается и выполняется кодом в классе Program. Метод Main:

Вызывает метод CreateHostBuilder для создания и настройки объекта построителя.
Вызывает методы Build и Run в объекте построителя.

Веб-шаблоны ASP.NET Core создают следующий код для создания узла:

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, добавленной в контейнер внедрения зависимостей.

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, который настраивает узел без необходимости запускать приложение. Подробные сведения см. в статье Design-time DbContext Creation (Создание экземпляра DbContext во время разработки).

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

Метод 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

IHostApplicationLifetime

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

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

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

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.

В следующем примере создается конфигурация узла:

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

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

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

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

ApplicationName

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

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

ContentRoot

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

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

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

EnvironmentName

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

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

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

ShutdownTimeout

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

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

Ключ: shutdownTimeoutSeconds
Тип: int
Значение по умолчанию: 5 секунд
переменной среды: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

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

Отключение перезагрузки конфигурации приложения при изменении

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

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

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

CaptureStartupErrors

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

webBuilder.CaptureStartupErrors(true);

DetailedErrors

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

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

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

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

HostingStartupAssemblies

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

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

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

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

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

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

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

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

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

StartupAssembly

Сборка, в которой необходимо искать класс Startup.

Ключ: startupAssembly
Тип: string
Значение по умолчанию: сборка приложения
переменной среды: {PREFIX_}STARTUPASSEMBLY

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

SuppressStatusMessages

Если этот флажок установлен, размещение сообщений о состоянии запуска подавляется.

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

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

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

URL-адреса

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

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

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

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

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

webBuilder.UseWebRoot("public");

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

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

Выполнить

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

RunAsync

RunConsoleAsync

Начать

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

StartAsync

StopAsync

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

WaitForShutdown

WaitForShutdownAsync

Внешнее управление

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

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 Generic Host (HostBuilder).

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

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

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

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

Узел обычно настраивается, собирается и выполняется кодом в классе Program. Метод Main:

Вызывает метод CreateHostBuilder для создания и настройки объекта построителя.
Вызывает методы Build и Run в объекте построителя.

Веб-шаблоны ASP.NET Core создают следующий код для создания универсального узла:

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.

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

Метод 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

IHostApplicationLifetime

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

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

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

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.

В следующем примере создается конфигурация узла:

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

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

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

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

ApplicationName

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

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

ContentRoot

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

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

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

EnvironmentName

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

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

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

ShutdownTimeout

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

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

Ключ: shutdownTimeoutSeconds
Тип: int
Значение по умолчанию: 5 секунд
переменной среды: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

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

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

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

CaptureStartupErrors

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

webBuilder.CaptureStartupErrors(true);

DetailedErrors

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

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

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

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

HostingStartupAssemblies

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

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

HostingStartupExcludeAssemblies

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

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

HTTPS_Port

Порт перенаправления HTTPS. Используется при принудительном применении HTTPS.

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

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

PreferHostingUrls

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

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

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

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

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

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

StartupAssembly

Сборка, в которой необходимо искать класс Startup.

Ключ: startupAssembly
Тип: string
Значение по умолчанию: сборка приложения
переменной среды: {PREFIX_}STARTUPASSEMBLY

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

SuppressStatusMessages

Если этот флажок установлен, размещение сообщений о состоянии запуска подавляется.

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

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

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

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.

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

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

webBuilder.UseWebRoot("public");

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

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

Выполнить

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

RunAsync

RunConsoleAsync

Начать

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

StartAsync

StopAsync

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

WaitForShutdown

WaitForShutdownAsync

Внешнее управление

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 на исходный код универсального узла

Примечание.

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

Поделиться через

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

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

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

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

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

IHostApplicationLifetime

IHostLifetime

IHostEnvironment

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

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

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

ApplicationName

ContentRoot

EnvironmentName

ShutdownTimeout

Отключение перезагрузки конфигурации приложения при изменении

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

CaptureStartupErrors

DetailedErrors

HostingStartupAssemblies

HostingStartupExcludeAssemblies

HTTPS_Port

HTTPS_Ports

PreferHostingUrls

PreventHostingStartup

StartupAssembly

SuppressStatusMessages

URL-адреса

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

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

Выполнить

RunAsync

RunConsoleAsync

Начать

StartAsync

StopAsync

WaitForShutdown

WaitForShutdownAsync

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

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

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

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

IHostApplicationLifetime

IHostLifetime

IHostEnvironment

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

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

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

ApplicationName

ContentRoot

EnvironmentName

ShutdownTimeout

Отключение перезагрузки конфигурации приложения при изменении

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

CaptureStartupErrors

DetailedErrors

HostingStartupAssemblies

HostingStartupExcludeAssemblies

HTTPS_Port

PreferHostingUrls

PreventHostingStartup

StartupAssembly

SuppressStatusMessages

URL-адреса

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

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

Выполнить

RunAsync

RunConsoleAsync

Начать

StartAsync

StopAsync

WaitForShutdown

WaitForShutdownAsync

Внешнее управление

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

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

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

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