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

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

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

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

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

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

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

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

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

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

Узел обычно настраивается, собирается и выполняется кодом в классе 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:

Метод ConfigureWebHostDefaults:

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

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

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

Дополнительные сведения о службах, предоставляемых платформой, см. в разделе Внедрение зависимостей в 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:

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

IHostEnvironment

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

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

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

Конфигурация узла используется для свойств реализации 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 задается в конфигурации узла во время создания узла.

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

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

ContentRoot

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

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

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

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

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

EnvironmentName

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

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

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

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

ShutdownTimeout

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

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

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

Ключ:
Тип:
По умолчанию: 5 секунд
Переменная среды: {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.

Ключ:
Тип: (true или false)
По умолчанию: true
Аргумент командной строки:
Переменная среды:

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

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

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

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

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

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

CaptureStartupErrors

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

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

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

webBuilder.CaptureStartupErrors(true);

DetailedErrors

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

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

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

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

HostingStartupAssemblies

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

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

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

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

HostingStartupExcludeAssemblies

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

Ключ:
Тип:
По умолчанию: Пустая строка
Переменная среды: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

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

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

HTTPS_Port

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

Ключ:
Тип:
По умолчанию: значение по умолчанию не задано.
Переменная среды: {PREFIX_}HTTPS_PORT

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

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

PreferHostingUrls

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

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

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

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

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

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

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

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

StartupAssembly

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

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

Чтобы задать это значение, используйте переменную среды или вызов UseStartup. UseStartup может использовать имя сборки (string) или тип (TStartup). При вызове нескольких методов UseStartup приоритет имеет последний.

webBuilder.UseStartup("StartupAssemblyName");
webBuilder.UseStartup<Startup>();

SuppressStatusMessages

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

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

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

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

URL-адреса

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

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

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

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

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

WebRoot

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

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

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

webBuilder.UseWebRoot("public");

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

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

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

Выполнить

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

RunAsync

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

RunConsoleAsync

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

Начало

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

StartAsync

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

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

StopAsync

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

WaitForShutdown

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

WaitForShutdownAsync

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

Шаблоны ASP.NET Core создают .NET Core Generic Host (HostBuilder).

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

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

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

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

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

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

Метод CreateDefaultBuilder:

Метод ConfigureWebHostDefaults:

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

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

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

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

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

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

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

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

IHostEnvironment

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

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

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

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

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

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

Поставщик переменных среды с префиксом DOTNET_ и аргументы командной строки включены в CreateDefaultBuilder. Для веб-приложений добавляется поставщик переменных среды с префиксом ASPNETCORE_. Префикс удаляется при чтении переменных среды. Например, значение переменной среды для ASPNETCORE_ENVIRONMENT становится значением конфигурации узла для ключа environment.

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

// using Microsoft.Extensions.Configuration;

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

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

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

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

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

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

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

ApplicationName

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

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

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

ContentRoot

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

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

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

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

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

EnvironmentName

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

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

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

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

ShutdownTimeout

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

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

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

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

Чтобы задать это значение, используйте переменную среды или настройте HostOptions. В следующем примере устанавливается время ожидания в 20 секунд:

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

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

По умолчанию при изменении файла выполняется перезагрузка appsettings.json и appsettings.{Environment}.json. Чтобы отключить эту функцию перезагрузки в ASP.NET Core 5.0 или более поздней версии, присвойте ключу hostBuilder:reloadConfigOnChange значение false.

Ключ:
Тип: (true или false)
По умолчанию: true
Аргумент командной строки:
Переменная среды:

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

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

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

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

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

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

CaptureStartupErrors

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

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

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

webBuilder.CaptureStartupErrors(true);

DetailedErrors

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

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

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

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

HostingStartupAssemblies

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

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

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

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

HostingStartupExcludeAssemblies

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

Ключ:
Тип:
По умолчанию: Пустая строка
Переменная среды: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

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

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

HTTPS_Port

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

Ключ:
Тип:
По умолчанию: значение по умолчанию не задано.
Переменная среды: {PREFIX_}HTTPS_PORT

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

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

PreferHostingUrls

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

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

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

webBuilder.PreferHostingUrls(false);

PreventHostingStartup

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

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

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

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

StartupAssembly

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

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

Чтобы задать это значение, используйте переменную среды или вызов UseStartup. UseStartup может использовать имя сборки (string) или тип (TStartup). При вызове нескольких методов UseStartup приоритет имеет последний.

webBuilder.UseStartup("StartupAssemblyName");
webBuilder.UseStartup<Startup>();

SuppressStatusMessages

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

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

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

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

URL-адреса

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

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

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

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

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

WebRoot

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

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

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

webBuilder.UseWebRoot("public");

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

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

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

Выполнить

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

RunAsync

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

RunConsoleAsync

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

Начало

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

StartAsync

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

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

StopAsync

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

WaitForShutdown

WaitForShutdown блокирует вызывающий поток до завершения работы, активированного IHostLifetime, например через WaitForShutdown++/SIGINT (Windows), C (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 создают .NET Core Generic Host (HostBuilder).

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

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

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

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

После запуска узла он вызывает IHostedService.StartAsync в каждой реализации IHostedService, зарегистрированной в коллекции размещенных служб контейнера службы. В веб-приложении одна из реализаций IHostedService является веб-службой, которая запускает 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.

Если приложение использует Entity Framework Core, не изменяйте имя или сигнатуру метода CreateHostBuilder. Инструменты Entity Framework Core ищут метод , который настраивает узел без необходимости запускать приложение. Подробные сведения см. в статье Design-time DbContext Creation (Создание экземпляра DbContext во время разработки).

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

Метод CreateDefaultBuilder:

Метод ConfigureWebHostDefaults:

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

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

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

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

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

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

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

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

IHostEnvironment

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

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

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

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

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

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

Поставщик переменных среды с префиксом DOTNET_ и аргументы командной строки включены в CreateDefaultBuilder. Для веб-приложений добавляется поставщик переменных среды с префиксом ASPNETCORE_. Префикс удаляется при чтении переменных среды. Например, значение переменной среды для ASPNETCORE_ENVIRONMENT становится значением конфигурации узла для ключа environment.

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

// using Microsoft.Extensions.Configuration;

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

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

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

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

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

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

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

ApplicationName

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

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

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

ContentRoot

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

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

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

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

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

EnvironmentName

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

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

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

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

ShutdownTimeout

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

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

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

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

Чтобы задать это значение, используйте переменную среды или настройте HostOptions. В следующем примере устанавливается время ожидания в 20 секунд:

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

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

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

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

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

CaptureStartupErrors

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

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

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

webBuilder.CaptureStartupErrors(true);

DetailedErrors

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

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

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

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

HostingStartupAssemblies

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

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

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

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

HostingStartupExcludeAssemblies

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

Ключ:
Тип:
По умолчанию: Пустая строка
Переменная среды: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

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

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

HTTPS_Port

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

Ключ:
Тип:
По умолчанию: значение по умолчанию не задано.
Переменная среды: {PREFIX_}HTTPS_PORT

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

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

PreferHostingUrls

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

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

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

webBuilder.PreferHostingUrls(false);

PreventHostingStartup

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

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

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

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

StartupAssembly

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

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

Чтобы задать это значение, используйте переменную среды или вызов UseStartup. UseStartup может использовать имя сборки (string) или тип (TStartup). При вызове нескольких методов UseStartup приоритет имеет последний.

webBuilder.UseStartup("StartupAssemblyName");
webBuilder.UseStartup<Startup>();

SuppressStatusMessages

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

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

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

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

URL-адреса

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

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

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

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

Kestrel имеет собственный API настройки конечных точек. Дополнительные сведения см. в статье Реализация веб-сервера в ASP.NET Core.

WebRoot

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

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

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

webBuilder.UseWebRoot("public");

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

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

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

Выполнить

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

RunAsync

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

RunConsoleAsync

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

Начало

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

StartAsync

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

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

StopAsync

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

WaitForShutdown

WaitForShutdown блокирует вызывающий поток до завершения работы, активированного IHostLifetime, например через WaitForShutdown++/SIGINT (Windows), C (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 на исходный код универсального узла

    Примечание

    По предыдущим ссылкам в документации на справочные материалы по ASP.NET Core загружается ветвь main репозитория, которая представляет текущую разработку единицы продукта для следующего выпуска ASP.NET Core. Чтобы выбрать ветвь для другого выпуска, используйте раскрывающийся список Switch branches/tags (Переключение ветвей или тегов). Например, выберите ветвь release/6.0 для выпуска ASP.NET Core 6.0.