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

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

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

ContentRoot

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

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

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

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

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

EnvironmentName

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

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

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

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

ShutdownTimeout

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

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

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

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

Чтобы задать это значение, используйте переменную среды или настройте 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)
По умолчанию:
Аргумент командной строки:
Переменная среды:

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

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

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

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

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

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

CaptureStartupErrors

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

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

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

webBuilder.CaptureStartupErrors(true);

DetailedErrors

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

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

Чтобы задать это значение, используйте конфигурацию или вызов 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

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

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

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

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

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

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

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

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

StartupAssembly

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

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

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

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

SuppressStatusMessages

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

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

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

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

URL-адреса

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

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

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

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

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

WebRoot

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

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

Чтобы задать это значение, используйте переменную среды или вызов 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 задается в конфигурации узла во время создания узла.

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

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

ContentRoot

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

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

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

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

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

EnvironmentName

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

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

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

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

ShutdownTimeout

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

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

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

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

Чтобы задать это значение, используйте переменную среды или настройте 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)
По умолчанию:
Аргумент командной строки:
Переменная среды:

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

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

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

Некоторые параметры узла применяются только к рабочим нагрузкам 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.
Переменная среды:

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

webBuilder.CaptureStartupErrors(true);

DetailedErrors

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

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

Чтобы задать это значение, используйте конфигурацию или вызов 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

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

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

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

webBuilder.PreferHostingUrls(false);

PreventHostingStartup

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

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

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

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

StartupAssembly

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

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

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

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

SuppressStatusMessages

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

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

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

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

URL-адреса

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

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

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

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

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

WebRoot

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

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

Чтобы задать это значение, используйте переменную среды или вызов 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 задается в конфигурации узла во время создания узла.

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

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

ContentRoot

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

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

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

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

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

EnvironmentName

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

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

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

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

ShutdownTimeout

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

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

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

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

Чтобы задать это значение, используйте переменную среды или настройте 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.
Переменная среды:

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

webBuilder.CaptureStartupErrors(true);

DetailedErrors

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

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

Чтобы задать это значение, используйте конфигурацию или вызов 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

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

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

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

webBuilder.PreferHostingUrls(false);

PreventHostingStartup

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

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

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

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

StartupAssembly

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

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

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

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

SuppressStatusMessages

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

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

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

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

URL-адреса

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

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

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

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

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

WebRoot

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

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

Чтобы задать это значение, используйте переменную среды или вызов 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));
        }
    }
}

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