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

  • Статья

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Метод CreateDefaultBuilder:

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

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

IHostEnvironment

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ApplicationName

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

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

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

ContentRoot

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

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

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

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

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

EnvironmentName

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

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

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

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

ShutdownTimeout

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

CaptureStartupErrors

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

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

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

webBuilder.CaptureStartupErrors(true);

DetailedErrors

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

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

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

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

HostingStartupAssemblies

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

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

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

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

HostingStartupExcludeAssemblies

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

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

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

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

HTTPS_Port

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

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

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

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

PreferHostingUrls

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

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

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

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

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

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

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

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

StartupAssembly

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

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

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

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

SuppressStatusMessages

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

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

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

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

URL-адреса

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

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

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

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

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

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

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

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

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

webBuilder.UseWebRoot("public");

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

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

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

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

Выполнить

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

RunAsync

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

RunConsoleAsync

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

Начать

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

StartAsync

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

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

StopAsync

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

WaitForShutdown

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

WaitForShutdownAsync

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

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

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

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

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

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

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

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

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

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

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

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

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

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

Следующий код создают нагрузку, отличную от HTTP, с одной реализацией IHostedService, добавленной в контейнер внедрения зависимостей.

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureServices((hostContext, services) =>
            {
               services.AddHostedService<Worker>();
            });
}

При использовании рабочей нагрузки HTTP метод Main остается прежним, но CreateHostBuilder вызывает ConfigureWebHostDefaults:

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

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

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

Метод CreateDefaultBuilder:

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

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

IHostEnvironment

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

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

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

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

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

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

ContentRoot

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

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

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

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

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

EnvironmentName

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

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

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

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

ShutdownTimeout

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

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

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

Ключ: shutdownTimeoutSeconds
Тип: int
Значение по умолчанию: 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.

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

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

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

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

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

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

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

webBuilder.CaptureStartupErrors(true);

DetailedErrors

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

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

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

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

HostingStartupAssemblies

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

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

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

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

HostingStartupExcludeAssemblies

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

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

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

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

HTTPS_Port

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

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

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

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

PreferHostingUrls

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

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

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

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

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

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

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

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

StartupAssembly

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

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

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

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

SuppressStatusMessages

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

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

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

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

URL-адреса

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

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

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

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

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

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

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

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

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

webBuilder.UseWebRoot("public");

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

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

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

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

Выполнить

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

RunAsync

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

RunConsoleAsync

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

Начать

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

StartAsync

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

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

StopAsync

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

WaitForShutdown

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

WaitForShutdownAsync

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

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

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

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.

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

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

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

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

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

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

Узел обычно настраивается, собирается и выполняется кодом в классе 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 ищут метод CreateHostBuilder, который настраивает узел без необходимости запускать приложение. Подробные сведения см. в статье 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:

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

IHostEnvironment

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

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

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

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

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

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

ContentRoot

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

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

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

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

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

EnvironmentName

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

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

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

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

ShutdownTimeout

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

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

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

Ключ: shutdownTimeoutSeconds
Тип: int
Значение по умолчанию: 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, узел перехватывает исключения во время запуска и пытается запустить сервер.

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

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

webBuilder.CaptureStartupErrors(true);

DetailedErrors

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

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

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

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

HostingStartupAssemblies

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

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

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

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

HostingStartupExcludeAssemblies

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

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

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

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

HTTPS_Port

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

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

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

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

PreferHostingUrls

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

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

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

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

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

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

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

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

StartupAssembly

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

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

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

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

SuppressStatusMessages

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

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

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

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

URL-адреса

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

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

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

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

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

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

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

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

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

webBuilder.UseWebRoot("public");

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

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

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

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

Выполнить

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

RunAsync

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

RunConsoleAsync

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

Начать

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

StartAsync

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

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

StopAsync

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

WaitForShutdown

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

WaitForShutdownAsync

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

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

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

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

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