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

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

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

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

主機定義

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

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

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

將應用程式的所有相互依賴資源包含在一個物件中，可控制應用程式的啟動及順利關機。

設定主機

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

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 預設選項，請參閱在使用 IIS 的 Windows 上裝載 ASP.NET Core。

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

架構提供的服務

下列服務會自動進行註冊：

• IHostApplicationLifetime
• IHostLifetime
• IHostEnvironment / IWebHostEnvironment

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

IHostApplicationLifetime

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

執行順利關機時，主機會：

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

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

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 實作的屬性。

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

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

CreateDefaultBuilder 包含前置詞 DOTNET_ 的環境變數提供者和命令列引數。 針對 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 設定逾時。 預設值為 30 秒。 在逾時期間，主機會：

• 觸發程序 IHostApplicationLifetime.ApplicationStopping。
• 嘗試停止託管的服務，並記錄無法停止之服務的錯誤。

如果在所有的託管服務停止之前逾時期限已到期，則應用程式關閉時，會停止任何剩餘的作用中服務。 即使服務尚未完成處理也會停止。 如果服務需要更多時間才能停止，請增加逾時。

金鑰：shutdownTimeoutSeconds
類型：int
預設值：30 秒
環境變數：{PREFIX_}SHUTDOWNTIMEOUTSECONDS

若要設定此值，請使用環境變數或設定 HostOptions。 下列範例將逾時設為 20 秒：

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

在變更時停用應用程式組態重新載入

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

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

警告

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

Web 應用程式的設定

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

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

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

CaptureStartupErrors

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

金鑰：captureStartupErrors
類型：bool (true/1 或 false/0)
預設值：預設值為 false，除非應用程式在 IIS 後端使用 true 執行，其中預設值為 Kestrel。
環境變數：{PREFIX_}CAPTURESTARTUPERRORS

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

webBuilder.CaptureStartupErrors(true);

DetailedErrors

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

金鑰：detailedErrors
類型：bool (true/1 或 false/0)
預設值：false
環境變數：{PREFIX_}DETAILEDERRORS

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

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

HostingStartupAssemblies

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

金鑰：hostingStartupAssemblies
類型：string
預設值：空字串
環境變數：{PREFIX_}HOSTINGSTARTUPASSEMBLIES

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

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

HostingStartupExcludeAssemblies

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

金鑰：hostingStartupExcludeAssemblies
類型：string
預設值：空字串
環境變數：{PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

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

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

HTTPS_Port

如果您取得非 HTTPS 連線，請設定要重新導向的 HTTPS 連接埠。 用於強制 HTTPS。 此設定不會讓伺服器接聽指定的埠。 也就是說，可能會意外地將要求重新導向至未使用的連接埠。

金鑰：https_port類型：string
預設值：未設定預設值。
環境變數：{PREFIX_}HTTPS_PORT

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

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

HTTPS_Ports

要接聽 HTTPS 連線的連接埠。

金鑰：https_ports
類型：string
預設值：未設定預設值。
環境變數：{PREFIX_}HTTPS_PORTS

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

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

PreferHostingUrls

表示主機是否應接聽使用 IWebHostBuilder 設定的 URL，而不是使用 IServer 實作所設定的 URL。

金鑰：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。 如需詳細資訊，請參閱設定 ASP.NET Core Kestrel 網頁伺服器的端點。

WebRoot

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

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

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

webBuilder.UseWebRoot("public");

如需詳細資訊，請參閱

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

管理主機存留期

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

Run* 和 Start* 方法之間的差異在於 Run* 方法會先等候主機完成後再傳回，而 Start* 方法會立即傳回。 Run* 方法通常用於主控台應用程式，而 Start* 方法通常用於長時間執行的服務。

執行

Run 會執行應用程式並封鎖呼叫執行緒，直到主機關閉為止。

RunAsync

RunAsync 會執行應用程式，並傳回觸發取消語彙基元或關機時所完成的 Task。

RunConsoleAsync

RunConsoleAsync 啟用主控台支援、建置和啟動主機，並等候 Ctrl+C/SIGINT (Windows)、⌘+C (macOS) 或 SIGTERM 關閉。

Start

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

  注意

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