共用方式為


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

注意

這不是這篇文章的最新版本。 如需目前版本,請參閱本文的 .NET 8 版本

警告

不再支援此版本的 ASP.NET Core。 如需詳細資訊,請參閱 .NET 和 .NET Core 支援原則。 如需目前版本,請參閱本文的 .NET 8 版本

重要

這些發行前產品的相關資訊在產品正式發行前可能會有大幅修改。 Microsoft 對此處提供的資訊,不做任何明確或隱含的瑕疵擔保。

如需目前版本,請參閱本文的 .NET 8 版本

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

ASP.NET Core 範本會建立 WebApplicationBuilderWebApplication,以提供簡化的方式來設定及執行沒有 Startup 類別的 Web 應用程式。 如需 WebApplicationBuilderWebApplication 的詳細資訊,請參閱從 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 方法:

本文稍後的<設定所有應用程式類型><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

IHostEnvironment

IHostEnvironment 服務插入至類別,以取得下列設定的相關資訊:

Web 應用程式會實作 IWebHostEnvironment 介面,其繼承 IHostEnvironment 並新增 WebRootPath

主機組態

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

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

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

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 上呼叫 ConfigureAppConfigurationConfigureAppConfiguration 可以多次呼叫,其結果是累加的。 應用程式會使用指定索引鍵上最後設定值的任何選項。

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 屬性可以設定為任何值。 架構定義的值包括 DevelopmentStagingProduction。 值不區分大小寫。

金鑰environment
類型string
預設值:Production
環境變數{PREFIX_}ENVIRONMENT

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

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

ShutdownTimeout

HostOptions.ShutdownTimeout 會為 StopAsync 設定逾時。 預設值為 30 秒。 在逾時期間,主機會:

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

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

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

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

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

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

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

警告

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

Web 應用程式的設定

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

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

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

CaptureStartupErrors

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

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

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

webBuilder.CaptureStartupErrors(true);

DetailedErrors

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

金鑰detailedErrors
類型bool (true/1false/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/1false/0)
預設值:false
環境變數{PREFIX_}PREFERHOSTINGURLS

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

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

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

金鑰preventHostingStartup
類型bool (true/1false/0)
預設值:false
環境變數{PREFIX_}PREVENTHOSTINGSTARTUP

若要設定此值,請使用環境變數或呼叫 UseSetting

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

StartupAssembly

要搜尋 Startup 類別的組件。

金鑰startupAssembly
類型string
預設值:應用程式的組件
環境變數{PREFIX_}STARTUPASSEMBLY

若要設定此值,請使用環境變數或呼叫 UseStartupUseStartup 可以採用組件名稱 (string) 或類型 (TStartup)。 如果呼叫多個 UseStartup 方法,最後一個將會優先。

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

SuppressStatusMessages

啟用時,隱藏裝載啟動狀態訊息。

金鑰suppressStatusMessages
類型bool (true/1false/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:5000https://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

WaitForStartAsyncStartAsync 開始時呼叫,並等到完成後再繼續進行。 此方法可用來將啟動延遲到外部事件發出訊號為止。

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 方法來建立及設定建立器物件。
  • 在建立器物件上呼叫 BuildRun 方法。

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 方法:

本文稍後的<設定所有應用程式類型><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

IHostEnvironment

IHostEnvironment 服務插入至類別,以取得下列設定的相關資訊:

Web 應用程式會實作 IWebHostEnvironment 介面,其繼承 IHostEnvironment 並新增 WebRootPath

主機組態

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

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

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

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 上呼叫 ConfigureAppConfigurationConfigureAppConfiguration 可以多次呼叫,其結果是累加的。 應用程式會使用指定索引鍵上最後設定值的任何選項。

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 屬性可以設定為任何值。 架構定義的值包括 DevelopmentStagingProduction。 值不區分大小寫。

金鑰environment
類型string
預設值:Production
環境變數{PREFIX_}ENVIRONMENT

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

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

ShutdownTimeout

HostOptions.ShutdownTimeout 會為 StopAsync 設定逾時。 預設值是五秒鐘。 在逾時期間,主機會:

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

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

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

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

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

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

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

警告

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

Web 應用程式的設定

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

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

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

CaptureStartupErrors

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

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

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

webBuilder.CaptureStartupErrors(true);

DetailedErrors

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

金鑰detailedErrors
類型bool (true/1false/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/1false/0)
預設值:false
環境變數{PREFIX_}PREFERHOSTINGURLS

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

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

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

金鑰preventHostingStartup
類型bool (true/1false/0)
預設值:false
環境變數{PREFIX_}PREVENTHOSTINGSTARTUP

若要設定此值,請使用環境變數或呼叫 UseSetting

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

StartupAssembly

要搜尋 Startup 類別的組件。

金鑰startupAssembly
類型string
預設值:應用程式的組件
環境變數{PREFIX_}STARTUPASSEMBLY

若要設定此值,請使用環境變數或呼叫 UseStartupUseStartup 可以採用組件名稱 (string) 或類型 (TStartup)。 如果呼叫多個 UseStartup 方法,最後一個將會優先。

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

SuppressStatusMessages

啟用時,隱藏裝載啟動狀態訊息。

金鑰suppressStatusMessages
類型bool (true/1false/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:5000https://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

WaitForStartAsyncStartAsync 開始時呼叫,並等到完成後再繼續進行。 此方法可用來將啟動延遲到外部事件發出訊號為止。

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 方法來建立及設定建立器物件。
  • 在建立器物件上呼叫 BuildRun 方法。

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 方法:

本文稍後的<設定所有應用程式類型><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

IHostEnvironment

IHostEnvironment 服務插入至類別,以取得下列設定的相關資訊:

Web 應用程式會實作 IWebHostEnvironment 介面,其繼承 IHostEnvironment 並新增 WebRootPath

主機組態

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

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

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

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 上呼叫 ConfigureAppConfigurationConfigureAppConfiguration 可以多次呼叫,其結果是累加的。 應用程式會使用指定索引鍵上最後設定值的任何選項。

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 屬性可以設定為任何值。 架構定義的值包括 DevelopmentStagingProduction。 值不區分大小寫。

金鑰environment
類型string
預設值:Production
環境變數{PREFIX_}ENVIRONMENT

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

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

ShutdownTimeout

HostOptions.ShutdownTimeout 會為 StopAsync 設定逾時。 預設值是五秒鐘。 在逾時期間,主機會:

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

金鑰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 上的擴充方法適用於這些設定。 示範如何呼叫擴充方法的程式碼範例假設 webBuilderIWebHostBuilder 的執行個體,如下列範例所示:

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

CaptureStartupErrors

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

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

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

webBuilder.CaptureStartupErrors(true);

DetailedErrors

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

金鑰detailedErrors
類型bool (true/1false/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/1false/0)
預設值:false
環境變數{PREFIX_}PREFERHOSTINGURLS

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

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

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

金鑰preventHostingStartup
類型bool (true/1false/0)
預設值:false
環境變數{PREFIX_}PREVENTHOSTINGSTARTUP

若要設定此值,請使用環境變數或呼叫 UseSetting

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

StartupAssembly

要搜尋 Startup 類別的組件。

金鑰startupAssembly
類型string
預設值:應用程式的組件
環境變數{PREFIX_}STARTUPASSEMBLY

若要設定此值,請使用環境變數或呼叫 UseStartupUseStartup 可以採用組件名稱 (string) 或類型 (TStartup)。 如果呼叫多個 UseStartup 方法,最後一個將會優先。

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

SuppressStatusMessages

啟用時,隱藏裝載啟動狀態訊息。

金鑰suppressStatusMessages
類型bool (true/1false/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:5000https://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

WaitForStartAsyncStartAsync 開始時呼叫,並等到完成後再繼續進行。 此方法可用來將啟動延遲到外部事件發出訊號為止。

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

其他資源