ASP.NET Core 中的 .NET 泛型主機

本文提供在 ASP.NET Core 中使用 .NET 泛型主機的相關資訊。

ASP.NET Core範本會 WebApplicationBuilder 建立 和 WebApplication ，其提供簡化的方式來設定和執行不含類別的 Startup Web 應用程式。 如需 和 的詳細資訊 WebApplicationBuilder ，請參閱從 ASP.NET Core 5.0 移轉至 6.0。 WebApplication

如需在主控台應用程式中使用 .NET 泛型主機的資訊，請參閱 .NET 泛型主機。

主機定義

「主機」是封裝所有應用程式資源的物件，例如：

• 相依性插入 (DI)
• 記錄
• 組態
• IHostedService 實作

當主機啟動時，它會在服務容器的託管服務集合中註冊的每個實 IHostedService 作上呼叫 IHostedService.StartAsync 。 在 Web 應用程式中，其中一個 IHostedService 實作是一種 Web 服務，負責啟動 HTTP 伺服器實作。

在一個物件中包含所有應用程式相依的資源，可讓您控制應用程式啟動和正常關機。

設定主機

主機通常會由 中的 Program.cs 程式碼設定、建置和執行。 下列程式碼會建立已新增至 DI 容器實作的主機 IHostedService ：

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

針對 HTTP 工作負載，請在 之後 CreateDefaultBuilder 呼叫 ConfigureWebHostDefaults ：

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

預設建立器設定

CreateDefaultBuilder 方法：

• 將 內容根目錄 設定為 所 GetCurrentDirectory 傳回的路徑。
• 從下列項目載入主機組態：
  • 前面加上 的 DOTNET_ 環境變數。
  • 命令列引數。
• 從下列項目載入應用程式組態：
  • appsettings.json.
  • appsettings.{Environment}.json.
  • 應用程式在 Development 環境中執行時的使用者密碼。
  • 環境變數。
  • 命令列引數。
• 新增下列記錄提供者：
  • 主控台
  • 偵錯
  • EventSource
  • EventLog (僅當在 Windows 上執行時)
• 環境為開發時，會啟用範圍驗證和相依性驗證。

ConfigureWebHostDefaults 方法：

• 從前面加上 ASPNETCORE_ 的環境變數載入主機組態。
• 將伺服器設定 Kestrel 為網頁伺服器，並使用應用程式的裝載組態提供者進行設定。 Kestrel如需伺服器的預設選項，請參閱設定ASP.NET Core Kestrel 網頁伺服器的選項。
• 新增主機篩選中介軟體。
• 如果 ASPNETCORE_FORWARDEDHEADERS_ENABLED 等於 true ，則加入轉送標頭中介軟體。
• 啟用 IIS 整合。 如需 IIS 預設選項，請參閱Windows 上的主機 ASP.NET Core IIS。

本文稍後的＜設定所有應用程式類型＞和＜Web 應用程式設定＞章節，將說明如何覆寫預設的建立器設定。

架構提供的服務

下列服務會自動註冊：

• IHostApplicationLifetime
• IHostLifetime
• IHostEnvironment / IWebHostEnvironment

如需架構服務的詳細資訊，請參閱ASP.NET Core中的相依性插入。

IHostApplicationLifetime

將 IHostApplicationLifetime (先前稱為 IApplicationLifetime) 服務插入任何類別來處理啟動後和順利關機工作。 介面上的三個屬性是用於註冊應用程式啟動和應用程式關閉事件處理程序方法的取消語彙基元。 介面也包含 StopApplication 方法，可讓應用程式要求正常關機。

執行正常關機時，主機：

• ApplicationStopping觸發事件處理常式，這可讓應用程式在關機程式開始之前執行邏輯。
• 停止伺服器，這會停用新的連線。 只要 關機逾 時允許，伺服器就會等候現有連線上的要求完成。 伺服器會傳送連線關閉標頭，以取得現有連線上的進一步要求。
• ApplicationStopped觸發事件處理常式，這可讓應用程式在應用程式關閉之後執行邏輯。

下列範例是 IHostedService 註冊 IHostApplicationLifetime 事件處理常式的實作：

public class HostApplicationLifetimeEventsHostedService : IHostedService
{
    private readonly IHostApplicationLifetime _hostApplicationLifetime;

    public HostApplicationLifetimeEventsHostedService(
        IHostApplicationLifetime hostApplicationLifetime)
        => _hostApplicationLifetime = hostApplicationLifetime;

    public Task StartAsync(CancellationToken cancellationToken)
    {
        _hostApplicationLifetime.ApplicationStarted.Register(OnStarted);
        _hostApplicationLifetime.ApplicationStopping.Register(OnStopping);
        _hostApplicationLifetime.ApplicationStopped.Register(OnStopped);

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
        => Task.CompletedTask;

    private void OnStarted()
    {
        // ...
    }

    private void OnStopping()
    {
        // ...
    }

    private void OnStopped()
    {
        // ...
    }
}

IHostLifetime

IHostLifetime 實作會控制主機啟動及停止的時機。 會使用最後一個註冊的實作。

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime 是預設的 IHostLifetime 實作。 ConsoleLifetime:

• 接聽Ctrl+C/SIGINT (Windows) 、⌘+C (macOS) 或 SIGTERM，並呼叫 StopApplication 以啟動關機程式。
• 會解除封鎖 RunAsync 和 WaitForShutdownAsync 等延伸模組。

IHostEnvironment

將 IHostEnvironment 服務插入 類別，以取得下列設定的相關資訊：

• ApplicationName
• EnvironmentName
• ContentRootPath

Web 應用程式會實作 IWebHostEnvironment 介面，它會繼承 IHostEnvironment 並新增 WebRootPath。

主機組態

主機組態用於 IHostEnvironment 實作的屬性。

主機組態可從 HostBuilderContext.Configuration 內部 ConfigureAppConfiguration 取得。 在 ConfigureAppConfiguration 之後，應用程式組態會取代 HostBuilderContext.Configuration。

若要新增主機組態，請呼叫 IHostBuilder 上的 ConfigureHostConfiguration。 ConfigureHostConfiguration 可以多次呼叫，其結果是累加的。 主機會使用指定索引鍵上最後設定值的任何選項。

包含前置詞 DOTNET_ 和命令列引數的 CreateDefaultBuilder 環境變數提供者。 針對 Web 應用程式，會新增具有前置詞 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);
    });

應用程式組態

應用程式組態的建立方式是在 IHostBuilder 上呼叫 ConfigureAppConfiguration。 ConfigureAppConfiguration 可以多次呼叫，其結果是累加的。 應用程式會使用指定索引鍵上最後設定值的任何選項。

所 ConfigureAppConfiguration 建立的組態適用于 HostBuilderContext.Configuration 後續作業，以及從 DI 做為服務。 主機組態也會新增至應用程式組態。

如需詳細資訊，請參閱 ASP.NET Core 中的組態。

所有應用程式類型的設定

本節列出適用於 HTTP 和非 HTTP 工作負載的主機設定。 根據預設，用來設定這些設定的環境變數可以有 DOTNET_ 或 ASPNETCORE_ 前置詞，其會出現在下列設定清單中做為 {PREFIX_} 預留位置。 如需詳細資訊，請參閱 預設產生器設定 一節和組 態：環境變數。

ApplicationName

屬性 IHostEnvironment.ApplicationName 是在主機建構期間從主機組態設定。

索引鍵：applicationName
類型：string
預設值：包含應用程式進入點的元件名稱。
環境變數： {PREFIX_}APPLICATIONNAME

若要設定此值，請使用環境變數。

ContentRoot

屬性 IHostEnvironment.ContentRootPath 會決定主機開始搜尋內容檔案的位置。 如果路徑不存在，就無法啟動主機。

索引鍵：contentRoot
類型：string
預設值：應用程式元件所在的資料夾。
環境變數： {PREFIX_}CONTENTROOT

若要設定此值，請使用環境變數或呼叫 IHostBuilder 上的 UseContentRoot：

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

如需詳細資訊，請參閱

• 基本概念：內容根目錄
• WebRoot

EnvironmentName

屬性 IHostEnvironment.EnvironmentName 可以設定為任何值。 架構定義的值包括 Development、Staging 和 Production。 值不區分大小寫。

索引鍵：environment
類型：string
預設：Production
環境變數： {PREFIX_}ENVIRONMENT

若要設定此值，請使用環境變數或呼叫 IHostBuilder 上的 UseEnvironment：

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>(options =>
        {
            options.ShutdownTimeout = TimeSpan.FromSeconds(20);
        });
    });

在變更時停用應用程式設定重載

根據 預設， appsettings.json 當檔案變更時，會重載 和 appsettings.{Environment}.json 。 若要在 ASP.NET Core 5.0 或更新版本中停用此重載行為，請將 hostBuilder:reloadConfigOnChange 機碼設定為 false 。

索引鍵y：hostBuilder:reloadConfigOnChange
類型： bool (true 或 false)
預設：true
命令列引數： hostBuilder:reloadConfigOnChange
環境變數： {PREFIX_}hostBuilder:reloadConfigOnChange

警告

冒號 (:) 分隔符號不適用於所有平臺上的環境變數階層式索引鍵。 如需詳細資訊，請參閱環境變數。

Web 應用程式的設定

某些主機設定僅適用於 HTTP 工作負載。 根據預設，用來設定這些設定的環境變數可以有 DOTNET_ 或 ASPNETCORE_ 前置詞，其會出現在下列設定清單中做為 {PREFIX_} 預留位置。

IWebHostBuilder 上的擴充方法適用於這些設定。 示範如何呼叫擴充方法的程式碼範例假設 webBuilder 是 IWebHostBuilder 的執行個體，如下列範例所示：

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

CaptureStartupErrors

當它為 false 時，啟動期間發生的錯誤會導致主機結束。 當它為 true 時，主機會擷取啟動期間的例外狀況，並嘗試啟動伺服器。

索引鍵y：captureStartupErrors
類型： bool (1/true 或) false/0
預設值： false 除非應用程式在 Kestrel IIS 後方執行，否則預設值為 true 。
環境變數： {PREFIX_}CAPTURESTARTUPERRORS

若要設定此值，請使用組態或呼叫 CaptureStartupErrors：

webBuilder.CaptureStartupErrors(true);

DetailedErrors

啟用時 (或當環境為 Development 時)，應用程式會擷取詳細錯誤。

索引鍵：detailedErrors
類型： bool (1/true 或) false/0
預設：false
環境變數： {PREFIX_}DETAILEDERRORS

若要設定此值，請使用組態或呼叫 UseSetting：

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

HostingStartupAssemblies

在啟動時載入的裝載啟動組件字串，以分號分隔。 雖然設定值會預設為空字串，但裝載啟動組件一律會包含應用程式的組件。 提供裝載啟動組件時，它們會新增至應用程式的組件，以便在應用程式在啟動時建置其通用服務時載入。

索引鍵y：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

指出主機是否應該接聽以 IWebHostBuilder 設定的 URL，而不是使用 實作所設定的 IServer URL。

索引鍵：preferHostingUrls
類型： bool (1/true 或) false/0
預設：true
環境變數： {PREFIX_}PREFERHOSTINGURLS

若要設定此值，請使用環境變數或呼叫 PreferHostingUrls：

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

可防止自動載入裝載啟動組件，包括應用程式組件所設定的裝載啟動組件。 如需詳細資訊，請參閱在 ASP.NET Core 中使用裝載啟動組件 (部分機器翻譯)。

索引鍵：preventHostingStartup
類型： bool (1/true 或) 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 (1/true 或) 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。 如需詳細資訊，請參閱設定 ASP.NET Core Kestrel Web 服務器的端點。

WebRoot

IWebHostEnvironment.WebRootPath屬性會決定應用程式靜態資產的相對路徑。 如果路徑不存在，則會使用無作業檔案提供者。

索引鍵：webroot
類型：string
預設值：預設值為 wwwroot 。 {content root}/wwwroot的路徑必須存在。
環境變數： {PREFIX_}WEBROOT

若要設定此值，請使用環境變數或呼叫 IWebHostBuilder 上的 UseWebRoot：

webBuilder.UseWebRoot("public");

如需詳細資訊，請參閱

• 基本概念：Web 根目錄
• ContentRoot

管理主機存留期

在建置的 IHost 實作上呼叫方法來啟動和停止應用程式。 這些方法會影響服務容器中註冊的所有 IHostedService 實作。

執行

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 泛型主機 (HostBuilder) 。

本文提供在 ASP.NET Core 中使用 .NET 泛型主機的相關資訊。 如需在主控台應用程式中使用 .NET 泛型主機的資訊，請參閱 .NET 泛型主機。

主機定義

「主機」是封裝所有應用程式資源的物件，例如：

• 相依性插入 (DI)
• 記錄
• 組態
• IHostedService 實作

當主機啟動時，它會在服務容器的託管服務集合中註冊的每個實 IHostedService 作上呼叫 IHostedService.StartAsync 。 在 Web 應用程式中，其中一個 IHostedService 實作是一種 Web 服務，負責啟動 HTTP 伺服器實作。

在單一物件中包含所有應用程式相互依存資源的主要理由便是生命週期管理：控制應用程式的啟動及順利關機。

設定主機

主機通常由 Program 類別的程式碼來設定、建置並執行。 Main 方法：

• 呼叫 CreateHostBuilder 方法來建立及設定建立器物件。
• 在建立器物件上呼叫 Build 和 Run 方法。

ASP.NET Core Web 範本會產生下列程式碼來建立主機：

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

如果應用程式使用 Entity Framework Core，請勿變更 CreateHostBuilder 方法的名稱或簽章。 Entity Framework Core 工具預期找到 CreateHostBuilder 方法，其在不執行應用程式的情況下設定主機。 如需詳細資訊，請參閱設計階段 DbContext 建立。

預設建立器設定

CreateDefaultBuilder 方法：

• 將 內容根目錄 設定為 所 GetCurrentDirectory 傳回的路徑。
• 從下列項目載入主機組態：
  • 前面加上 的 DOTNET_ 環境變數。
  • 命令列引數。
• 從下列項目載入應用程式組態：
  • appsettings.json.
  • appsettings.{Environment}.json.
  • 應用程式在 Development 環境中執行時的使用者密碼。
  • 環境變數。
  • 命令列引數。
• 新增下列記錄提供者：
  • 主控台
  • 偵錯
  • EventSource
  • EventLog (僅當在 Windows 上執行時)
• 環境為開發時，會啟用範圍驗證和相依性驗證。

ConfigureWebHostDefaults 方法：

• 從前面加上 ASPNETCORE_ 的環境變數載入主機組態。
• 將伺服器設定 Kestrel 為網頁伺服器，並使用應用程式的裝載組態提供者進行設定。 Kestrel如需伺服器的預設選項，請參閱設定ASP.NET Core Kestrel 網頁伺服器的選項。
• 新增主機篩選中介軟體。
• 如果 ASPNETCORE_FORWARDEDHEADERS_ENABLED 等於 true ，則加入轉送標頭中介軟體。
• 啟用 IIS 整合。 如需 IIS 預設選項，請參閱使用 IIS 在 Windows 上裝載 ASP.NET Core。

本文稍後的＜設定所有應用程式類型＞和＜Web 應用程式設定＞章節，將說明如何覆寫預設的建立器設定。

架構提供的服務

下列服務會自動註冊：

• IHostApplicationLifetime
• IHostLifetime
• IHostEnvironment / IWebHostEnvironment

如需架構提供之服務的詳細資訊，請參閱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 服務插入 類別，以取得下列設定的相關資訊：

• ApplicationName
• EnvironmentName
• ContentRootPath

Web 應用程式會實作 IWebHostEnvironment 介面，此介面會 IHostEnvironment 繼承並新增 WebRootPath。

主機組態

主機組態用於 IHostEnvironment 實作的屬性。

主機組態可從 HostBuilderContext.Configuration 內部 ConfigureAppConfiguration 取得。 在 ConfigureAppConfiguration 之後，應用程式組態會取代 HostBuilderContext.Configuration。

若要新增主機組態，請呼叫 IHostBuilder 上的 ConfigureHostConfiguration。 ConfigureHostConfiguration 可以多次呼叫，其結果是累加的。 主機會使用指定索引鍵上最後設定值的任何選項。

包含前置詞 DOTNET_ 和命令列引數的 CreateDefaultBuilder 環境變數提供者。 針對 Web 應用程式，會新增具有前置詞 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);
    });

應用程式組態

應用程式組態的建立方式是在 IHostBuilder 上呼叫 ConfigureAppConfiguration。 ConfigureAppConfiguration 可以多次呼叫，其結果是累加的。 應用程式會使用指定索引鍵上最後設定值的任何選項。

建立的 ConfigureAppConfiguration 組態適用于 HostBuilderContext.Configuration 後續作業，以及從 DI 作為服務。 主機組態也會新增至應用程式組態。

如需詳細資訊，請參閱 ASP.NET Core 中的組態。

所有應用程式類型的設定

本節列出適用於 HTTP 和非 HTTP 工作負載的主機設定。 根據預設，用來設定這些設定的環境變數可以有 DOTNET_ 或 ASPNETCORE_ 前置詞，其會顯示在下列設定清單中做為 {PREFIX_} 預留位置。 如需詳細資訊，請參閱 預設產生器設定 一節和組 態：環境變數。

ApplicationName

屬性 IHostEnvironment.ApplicationName 是在主機建構期間從主機組態進行設定。

索引鍵：applicationName
類型：string
預設值：包含應用程式進入點的元件名稱。
環境變數： {PREFIX_}APPLICATIONNAME

若要設定此值，請使用環境變數。

ContentRoot

屬性 IHostEnvironment.ContentRootPath 會決定主機開始搜尋內容檔案的位置。 如果路徑不存在，就無法啟動主機。

索引鍵：contentRoot
類型：string
預設值：應用程式元件所在的資料夾。
環境變數： {PREFIX_}CONTENTROOT

若要設定此值，請使用環境變數或呼叫 IHostBuilder 上的 UseContentRoot：

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

如需詳細資訊，請參閱

• 基本概念：內容根目錄
• WebRoot

EnvironmentName

屬性 IHostEnvironment.EnvironmentName 可以設定為任何值。 架構定義的值包括 Development、Staging 和 Production。 值不區分大小寫。

索引鍵：environment
類型：string
預設：Production
環境變數： {PREFIX_}ENVIRONMENT

若要設定此值，請使用環境變數或呼叫 IHostBuilder 上的 UseEnvironment：

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 。

索引鍵y：hostBuilder:reloadConfigOnChange
類型： bool (true 或 false)
預設：true
命令列引數： hostBuilder:reloadConfigOnChange
環境變數： {PREFIX_}hostBuilder:reloadConfigOnChange

警告

冒號 (:) 分隔符號不適用於所有平臺上的環境變數階層式索引鍵。 如需詳細資訊，請參閱環境變數。

Web 應用程式的設定

某些主機設定僅適用於 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 時，主機會擷取啟動期間的例外狀況，並嘗試啟動伺服器。

索引鍵y：captureStartupErrors
類型： bool (1/true 或) false/0
預設值：除非 false 應用程式在 Kestrel IIS 後方執行，否則預設為 true 。
環境變數： {PREFIX_}CAPTURESTARTUPERRORS

若要設定此值，請使用組態或呼叫 CaptureStartupErrors：

webBuilder.CaptureStartupErrors(true);

DetailedErrors

啟用時 (或當環境為 Development 時)，應用程式會擷取詳細錯誤。

索引鍵y：detailedErrors
類型： bool (1/true 或) false/0
預設：false
環境變數： {PREFIX_}DETAILEDERRORS

若要設定此值，請使用組態或呼叫 UseSetting：

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

HostingStartupAssemblies

在啟動時載入的裝載啟動組件字串，以分號分隔。 雖然設定值會預設為空字串，但裝載啟動組件一律會包含應用程式的組件。 提供裝載啟動組件時，它們會新增至應用程式的組件，以便在應用程式在啟動時建置其通用服務時載入。

索引鍵y：hostingStartupAssemblies
類型：string
預設值：空字串
環境變數： {PREFIX_}HOSTINGSTARTUPASSEMBLIES

若要設定此值，請使用組態或呼叫 UseSetting：

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

HostingStartupExcludeAssemblies

在啟動時排除以分號分隔的裝載啟動組件字串。

索引鍵y：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

指出主機是否應該接聽以 IWebHostBuilder 設定的 URL，而不是使用 實作所設定的 IServer URL。

索引鍵：preferHostingUrls
類型： bool (1/true 或) false/0
預設：true
環境變數： {PREFIX_}PREFERHOSTINGURLS

若要設定此值，請使用環境變數或呼叫 PreferHostingUrls：

webBuilder.PreferHostingUrls(false);

PreventHostingStartup

可防止自動載入裝載啟動組件，包括應用程式組件所設定的裝載啟動組件。 如需詳細資訊，請參閱在 ASP.NET Core 中使用裝載啟動組件 (部分機器翻譯)。

索引鍵：preventHostingStartup
類型： bool (1/true 或) 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 (1/true 或) 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。 如需詳細資訊，請參閱設定 ASP.NET Core Kestrel Web 服務器的端點。

WebRoot

IWebHostEnvironment.WebRootPath屬性會決定應用程式靜態資產的相對路徑。 如果路徑不存在，則會使用無作業檔案提供者。

索引鍵：webroot
類型：string
預設值：預設值為 wwwroot 。 {content root}/wwwroot的路徑必須存在。
環境變數： {PREFIX_}WEBROOT

若要設定此值，請使用環境變數或呼叫 IWebHostBuilder 上的 UseWebRoot：

webBuilder.UseWebRoot("public");

如需詳細資訊，請參閱

• 基本概念：Web 根目錄
• ContentRoot

管理主機存留期

在建置的 IHost 實作上呼叫方法來啟動和停止應用程式。 這些方法會影響服務容器中註冊的所有 IHostedService 實作。

執行

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 泛型主機 (HostBuilder) 。

本文提供在 ASP.NET Core 中使用 .NET 泛型主機的相關資訊。 如需在主控台應用程式中使用 .NET 泛型主機的資訊，請參閱 .NET 泛型主機。

主機定義

「主機」是封裝所有應用程式資源的物件，例如：

• 相依性插入 (DI)
• 記錄
• 組態
• IHostedService 實作

當主機啟動時，它會在服務容器的託管服務集合中註冊的每個實 IHostedService 作上呼叫 IHostedService.StartAsync 。 在 Web 應用程式中，其中一個 IHostedService 實作是一種 Web 服務，負責啟動 HTTP 伺服器實作。

在單一物件中包含所有應用程式相互依存資源的主要理由便是生命週期管理：控制應用程式的啟動及順利關機。

設定主機

主機通常由 Program 類別的程式碼來設定、建置並執行。 Main 方法：

• 呼叫 CreateHostBuilder 方法來建立及設定建立器物件。
• 在建立器物件上呼叫 Build 和 Run 方法。

ASP.NET Core Web 範本會產生下列程式碼來建立一般主機：

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 方法，其在不執行應用程式的情況下設定主機。 如需詳細資訊，請參閱設計階段 DbContext 建立。

預設建立器設定

CreateDefaultBuilder 方法：

• 將 內容根目錄 設定為 所 GetCurrentDirectory 傳回的路徑。
• 從下列項目載入主機組態：
  • 前面加上 的 DOTNET_ 環境變數。
  • 命令列引數。
• 從下列項目載入應用程式組態：
  • appsettings.json.
  • appsettings.{Environment}.json.
  • 應用程式在 Development 環境中執行時的使用者密碼。
  • 環境變數。
  • 命令列引數。
• 新增下列記錄提供者：
  • 主控台
  • 偵錯
  • EventSource
  • EventLog (僅當在 Windows 上執行時)
• 環境為開發時，會啟用範圍驗證和相依性驗證。

ConfigureWebHostDefaults 方法：

• 從前面加上 ASPNETCORE_ 的環境變數載入主機組態。
• 將伺服器設定 Kestrel 為網頁伺服器，並使用應用程式的裝載組態提供者進行設定。 Kestrel如需伺服器的預設選項，請參閱Kestrel ASP.NET Core 中的網頁伺服器實作。
• 新增主機篩選中介軟體。
• 如果 ASPNETCORE_FORWARDEDHEADERS_ENABLED 等於 true ，則加入轉送標頭中介軟體。
• 啟用 IIS 整合。 如需 IIS 預設選項，請參閱Windows 上的主機 ASP.NET Core IIS。

本文稍後的＜設定所有應用程式類型＞和＜Web 應用程式設定＞章節，將說明如何覆寫預設的建立器設定。

架構提供的服務

下列服務會自動註冊：

• IHostApplicationLifetime
• IHostLifetime
• IHostEnvironment / IWebHostEnvironment

如需架構服務的詳細資訊，請參閱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 服務插入 類別，以取得下列設定的相關資訊：

• ApplicationName
• EnvironmentName
• ContentRootPath

Web 應用程式會實作 IWebHostEnvironment 介面，它會繼承 IHostEnvironment 並新增 WebRootPath。

主機組態

主機組態用於 IHostEnvironment 實作的屬性。

主機組態可從 HostBuilderContext.Configuration 內部 ConfigureAppConfiguration 取得。 在 ConfigureAppConfiguration 之後，應用程式組態會取代 HostBuilderContext.Configuration。

若要新增主機組態，請呼叫 IHostBuilder 上的 ConfigureHostConfiguration。 ConfigureHostConfiguration 可以多次呼叫，其結果是累加的。 主機會使用指定索引鍵上最後設定值的任何選項。

包含前置詞 DOTNET_ 和命令列引數的 CreateDefaultBuilder 環境變數提供者。 針對 Web 應用程式，會新增具有前置詞 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);
    });

應用程式組態

應用程式組態的建立方式是在 IHostBuilder 上呼叫 ConfigureAppConfiguration。 ConfigureAppConfiguration 可以多次呼叫，其結果是累加的。 應用程式會使用指定索引鍵上最後設定值的任何選項。

所 ConfigureAppConfiguration 建立的組態適用于 HostBuilderContext.Configuration 後續作業，以及從 DI 做為服務。 主機組態也會新增至應用程式組態。

如需詳細資訊，請參閱 ASP.NET Core 中的組態。

所有應用程式類型的設定

本節列出適用於 HTTP 和非 HTTP 工作負載的主機設定。 根據預設，用來設定這些設定的環境變數可以有 DOTNET_ 或 ASPNETCORE_ 前置詞，其會出現在預留位置的下列組 {PREFIX_} 態中。

ApplicationName

屬性 IHostEnvironment.ApplicationName 是在主機建構期間從主機組態設定。

索引鍵：applicationName
類型：string
預設值：包含應用程式進入點的元件名稱。
環境變數： {PREFIX_}APPLICATIONNAME

若要設定此值，請使用環境變數。

ContentRoot

屬性 IHostEnvironment.ContentRootPath 會決定主機開始搜尋內容檔案的位置。 如果路徑不存在，就無法啟動主機。

索引鍵：contentRoot
類型：string
預設值：應用程式元件所在的資料夾。
環境變數： {PREFIX_}CONTENTROOT

若要設定此值，請使用環境變數或呼叫 IHostBuilder 上的 UseContentRoot：

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

如需詳細資訊，請參閱

• 基本概念：內容根目錄
• WebRoot

EnvironmentName

屬性 IHostEnvironment.EnvironmentName 可以設定為任何值。 架構定義的值包括 Development、Staging 和 Production。 值不區分大小寫。

索引鍵：environment
類型：string
預設：Production
環境變數： {PREFIX_}ENVIRONMENT

若要設定此值，請使用環境變數或呼叫 IHostBuilder 上的 UseEnvironment：

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

Web 應用程式的設定

某些主機設定僅適用於 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 時，主機會擷取啟動期間的例外狀況，並嘗試啟動伺服器。

索引鍵y：captureStartupErrors
類型： bool (1/true 或) false/0
預設值： false 除非應用程式在 Kestrel IIS 後方執行，否則預設值為 true 。
環境變數： {PREFIX_}CAPTURESTARTUPERRORS

若要設定此值，請使用組態或呼叫 CaptureStartupErrors：

webBuilder.CaptureStartupErrors(true);

DetailedErrors

啟用時 (或當環境為 Development 時)，應用程式會擷取詳細錯誤。

索引鍵：detailedErrors
類型： bool (1/true 或) 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

指出主機是否應該接聽以 IWebHostBuilder 設定的 URL，而不是使用 實作所設定的 IServer URL。

索引鍵：preferHostingUrls
類型： bool (1/true 或) false/0
預設：true
環境變數： {PREFIX_}PREFERHOSTINGURLS

若要設定此值，請使用環境變數或呼叫 PreferHostingUrls：

webBuilder.PreferHostingUrls(false);

PreventHostingStartup

可防止自動載入裝載啟動組件，包括應用程式組件所設定的裝載啟動組件。 如需詳細資訊，請參閱在 ASP.NET Core 中使用裝載啟動組件 (部分機器翻譯)。

索引鍵y：preventHostingStartup
類型： bool (1/true 或) 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 (1/true 或) false/0
預設：false
環境變數： {PREFIX_}SUPPRESSSTATUSMESSAGES

若要設定此值，請使用組態或呼叫 UseSetting：

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

URL

以分號分隔的 IP 位址或主機位址，包含伺服器應接聽要求的連接埠和通訊協定。 例如： http://localhost:123 。 使用 「*」 表示伺服器應該使用指定的埠和通訊協定接聽任何 IP 位址或主機名稱的要求，例如 () http://*:5000 。 通訊協定 (http:// 或 https://) 必須包含在每個 URL 中。 支援的格式會依伺服器而有所不同。

索引鍵y：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 中的網頁伺服器實作。

WebRoot

IWebHostEnvironment.WebRootPath屬性會決定應用程式靜態資產的相對路徑。 如果路徑不存在，則會使用無作業檔案提供者。

索引鍵y：webroot
類型：string
預設值：預設值為 wwwroot 。 {content root}/wwwroot的路徑必須存在。
環境變數： {PREFIX_}WEBROOT

若要設定此值，請使用環境變數或呼叫 IWebHostBuilder 上的 UseWebRoot：

webBuilder.UseWebRoot("public");

如需詳細資訊，請參閱

• 基本概念：Web 根目錄
• ContentRoot

管理主機存留期

在建置的 IHost 實作上呼叫方法來啟動和停止應用程式。 這些方法會影響服務容器中註冊的所有 IHostedService 實作。

執行

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 中使用託管服務的背景工作
• GitHub 連結至 一般主機來源

  注意

  .NET 參考來源的文件連結通常會載入存放庫的預設分支，這表示下一版 .NET 的目前開發。 若要選取特定版本的標籤，請使用 [切換分支或標籤] 下拉式清單。 如需詳細資訊，請參閱如何選取 ASP.NET Core 原始程式碼 (dotnet/AspNetCore.Docs #26205) 的版本標籤。