ASP.NET Core 中的 .NET 泛型主機
注意
這不是這篇文章的最新版本。 如需目前版本,請參閱本文的 .NET 8 版本。
警告
不再支援此版本的 ASP.NET Core。 如需詳細資訊,請參閱 .NET 和 .NET Core 支援原則。 如需目前版本,請參閱本文的 .NET 8 版本。
本文提供在 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();
預設建立器設定
- 將內容根目錄設定為 GetCurrentDirectory 所傳回的路徑。
- 從下列項目載入主機組態:
- 前面加上
DOTNET_
的環境變數。 - 命令列引數。
- 前面加上
- 從下列項目載入應用程式組態:
appsettings.json
.appsettings.{Environment}.json
.- 應用程式在
Development
環境中執行時的使用者密碼。 - 環境變數。
- 命令列引數。
- 新增下列記錄提供者:
- 主控台
- 偵錯
- EventSource
- EventLog (僅當在 Windows 上執行時)
- 環境為開發時,會啟用範圍驗證和相依性驗證。
- 會從環境變數中載入前置詞為
ASPNETCORE_
的主機組態。 - 將 Kestrel 伺服器設為網頁伺服器,並使用應用程式的主機組態提供者進行設定。 如需 Kestrel 伺服器的預設選項,請參閱設定 ASP.NET Core Kestrel 網頁伺服器的選項。
- 新增主機篩選中介軟體。
- 如果
ASPNETCORE_FORWARDEDHEADERS_ENABLED
等於true
,則新增轉送的標頭中介軟體。 - 啟用 IIS 整合。 如需 IIS 預設選項,請參閱在使用 IIS 的 Windows 上裝載 ASP.NET Core。
本文稍後的<設定所有應用程式類型>和<Web 應用程式設定>章節,將說明如何覆寫預設的建立器設定。
架構提供的服務
下列服務會自動進行註冊:
如需架構所提供服務的詳細資訊,請參閱 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 服務插入至類別,以取得下列設定的相關資訊:
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")
// ...
如需詳細資訊,請參閱
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_port
類型:string
預設值:未設定預設值。
環境變數:{PREFIX_}HTTPS_PORT
若要設定此值,請使用組態或呼叫 UseSetting
:
webBuilder.UseSetting("https_port", "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");
如需詳細資訊,請參閱
管理主機存留期
在建置的 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 範本會建立 .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 建立。
預設建立器設定
- 將內容根目錄設定為 GetCurrentDirectory 所傳回的路徑。
- 從下列項目載入主機組態:
- 前面加上
DOTNET_
的環境變數。 - 命令列引數。
- 前面加上
- 從下列項目載入應用程式組態:
appsettings.json
.appsettings.{Environment}.json
.- 應用程式在
Development
環境中執行時的使用者密碼。 - 環境變數。
- 命令列引數。
- 新增下列記錄提供者:
- 主控台
- 偵錯
- EventSource
- EventLog (僅當在 Windows 上執行時)
- 環境為開發時,會啟用範圍驗證和相依性驗證。
- 會從環境變數中載入前置詞為
ASPNETCORE_
的主機組態。 - 將 Kestrel 伺服器設為網頁伺服器,並使用應用程式的主機組態提供者進行設定。 如需 Kestrel 伺服器的預設選項,請參閱設定 ASP.NET Core Kestrel 網頁伺服器的選項。
- 新增主機篩選中介軟體。
- 如果
ASPNETCORE_FORWARDEDHEADERS_ENABLED
等於true
,則新增轉送的標頭中介軟體。 - 啟用 IIS 整合。 如需 IIS 預設選項,請參閱在使用 IIS 的 Windows 上裝載 ASP.NET Core。
本文稍後的<設定所有應用程式類型>和<Web 應用程式設定>章節,將說明如何覆寫預設的建立器設定。
架構提供的服務
下列服務會自動進行註冊:
如需架構所提供服務的詳細資訊,請參閱 ASP.NET Core 中的相依性插入。
IHostApplicationLifetime
將 IHostApplicationLifetime (先前稱為 IApplicationLifetime
) 服務插入任何類別來處理啟動後和順利關機工作。 介面上的三個屬性是用於註冊應用程式啟動和應用程式關閉事件處理程序方法的取消語彙基元。 介面也包括 StopApplication
方法。
下例為可註冊 IHostApplicationLifetime
事件的 IHostedService
實作:
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 服務插入至類別,以取得下列設定的相關資訊:
Web 應用程式會實作 IWebHostEnvironment
介面,其繼承 IHostEnvironment
並新增 WebRootPath。
主機組態
主機組態用於 IHostEnvironment 實作的屬性。
主機組態可從 ConfigureAppConfiguration 內的 HostBuilderContext.Configuration 取得。 在 ConfigureAppConfiguration
之後,應用程式組態會取代 HostBuilderContext.Configuration
。
若要新增主機組態,請呼叫 IHostBuilder
上的 ConfigureHostConfiguration。 ConfigureHostConfiguration
可以多次呼叫,其結果是累加的。 主機會使用指定索引鍵上最後設定值的任何選項。
CreateDefaultBuilder
包含前置詞 DOTNET_
的環境變數提供者和命令列引數。 針對 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")
//...
如需詳細資訊,請參閱
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
。
金鑰: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
時,主機會擷取啟動期間的例外狀況,並嘗試啟動伺服器。
金鑰: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_port
類型:string
預設值:未設定預設值。
環境變數:{PREFIX_}HTTPS_PORT
若要設定此值,請使用組態或呼叫 UseSetting
:
webBuilder.UseSetting("https_port", "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");
如需詳細資訊,請參閱
管理主機存留期
在建置的 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。
外部控制
主機存留期直接控制可以使用可從外部呼叫的方法來達成:
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 建立。
預設建立器設定
- 將內容根目錄設定為 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 應用程式設定>章節,將說明如何覆寫預設的建立器設定。
架構提供的服務
下列服務會自動進行註冊:
如需架構所提供服務的詳細資訊,請參閱 ASP.NET Core 中的相依性插入。
IHostApplicationLifetime
將 IHostApplicationLifetime (先前稱為 IApplicationLifetime
) 服務插入任何類別來處理啟動後和順利關機工作。 介面上的三個屬性是用於註冊應用程式啟動和應用程式關閉事件處理程序方法的取消語彙基元。 介面也包括 StopApplication
方法。
下例為可註冊 IHostApplicationLifetime
事件的 IHostedService
實作:
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 服務插入至類別,以取得下列設定的相關資訊:
Web 應用程式會實作 IWebHostEnvironment
介面,其繼承 IHostEnvironment
並新增 WebRootPath。
主機組態
主機組態用於 IHostEnvironment 實作的屬性。
主機組態可從 ConfigureAppConfiguration 內的 HostBuilderContext.Configuration 取得。 在 ConfigureAppConfiguration
之後,應用程式組態會取代 HostBuilderContext.Configuration
。
若要新增主機組態,請呼叫 IHostBuilder
上的 ConfigureHostConfiguration。 ConfigureHostConfiguration
可以多次呼叫,其結果是累加的。 主機會使用指定索引鍵上最後設定值的任何選項。
CreateDefaultBuilder
包含前置詞 DOTNET_
的環境變數提供者和命令列引數。 針對 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")
//...
如需詳細資訊,請參閱
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
時,主機會擷取啟動期間的例外狀況,並嘗試啟動伺服器。
金鑰: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_port
類型:string
預設值:未設定預設值。
環境變數:{PREFIX_}HTTPS_PORT
若要設定此值,請使用組態或呼叫 UseSetting
:
webBuilder.UseSetting("https_port", "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");
如需詳細資訊,請參閱
管理主機存留期
在建置的 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。
外部控制
主機存留期直接控制可以使用可從外部呼叫的方法來達成:
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) 的版本標籤。