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

ASP.NET Core 範本會建立 .net Core 泛型主機 (HostBuilder) 。

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

主機定義

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

  • 相依性插入 (DI)
  • 記錄
  • 設定
  • IHostedService 實作

當主機啟動時,它會呼叫 IHostedService.StartAsync IHostedService 服務容器的託管服務集合中註冊的每個執行。 在 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 應用程式設定>章節,將說明如何覆寫預設的建立器設定。

架構提供的服務

下列服務會自動註冊:

如需架構所提供之服務的詳細資訊,請參閱 .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:

IHostEnvironment

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

Web apps 會執行 IWebHostEnvironment 介面,此介面會繼承 IHostEnvironment 並新增 WebRootPath

主機組態

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

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

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

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

ConfigureAppConfiguration 建立的組態位於 HostBuilderContext.Configuration,可用於後續作業並用作 DI 中的服務。 主機組態也會新增至應用程式組態。

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

所有應用程式類型的設定

本節列出適用於 HTTP 和非 HTTP 工作負載的主機設定。 根據預設,用來設定這些設定的環境變數可以具有 DOTNET_ASPNETCORE_ 前置詞。 如需詳細資訊,請參閱預設建立器 設定 一節。

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。環境}。 當檔案變更時,會重載 json。 若要在 ASP.NET Core 5.0 或更新版本中停用這個重載行為,請將索引 hostBuilder:reloadConfigOnChange 鍵設定為 false

機碼hostBuilder:reloadConfigOnChange
類型bool (true1)
預設值true
命令列引數hostBuilder:reloadConfigOnChange
環境變數<PREFIX_>hostBuilder:reloadConfigOnChange

警告

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

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 (true1)
預設 值:預設為, false 除非應用程式在 Kestrel IIS 後方執行,預設值為 true
環境變數<PREFIX_>CAPTURESTARTUPERRORS

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

webBuilder.CaptureStartupErrors(true);

DetailedErrors

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

機碼detailedErrors
類型bool (true1)
預設值false
環境變數<PREFIX_>_DETAILEDERRORS

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

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

HostingStartupAssemblies

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

機碼hostingStartupAssemblies
類型string
預設值:空字串
環境變數<PREFIX_>_HOSTINGSTARTUPASSEMBLIES

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

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

HostingStartupExcludeAssemblies

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

機碼hostingStartupExcludeAssemblies
類型string
預設值:空字串
環境變數<PREFIX_>_HOSTINGSTARTUPEXCLUDEASSEMBLIES

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

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

HTTPS_Port

HTTPS 重新導向連接埠。 用於強制 HTTPS

機碼https_port
類型string
預設 值:未設定預設值。
環境變數<PREFIX_>HTTPS_PORT

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

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

PreferHostingUrls

指出主機是否應接聽使用設定的 Url, IWebHostBuilder 而不是使用執行時所設定的 url IServer

機碼preferHostingUrls
類型bool (true1)
預設值true
環境變數<PREFIX_>_PREFERHOSTINGURLS

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

webBuilder.PreferHostingUrls(false);

PreventHostingStartup

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

機碼preventHostingStartup
類型bool (true1)
預設值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>();

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 web 伺服器的端點

WebRoot

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

機碼webroot
類型string
預設 值:預設值為 wwwroot{Content root}/wwwroot 的路徑必須存在。
環境變數<PREFIX_>WEBROOT

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

webBuilder.UseWebRoot("public");

如需詳細資訊,請參閱

管理主機存留期

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

執行

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

RunAsync

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

RunConsoleAsync

RunConsoleAsync啟用主控台支援、建立並啟動主機,以及等候Ctrl + C/SIGINT 或 SIGTERM 關閉。

開始

Start 會同步啟動主機。

StartAsync

StartAsync 會啟動主機,並傳回觸發取消語彙基元或關機時所完成的 Task

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

StopAsync

StopAsync 會嘗試在提供的逾時內停止主機。

WaitForShutdown

WaitForShutdown封鎖呼叫的執行緒,直到 IHostLifetime 觸發關機(例如 via Ctrl + C/SIGINT 或 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.StartAsync IHostedService 服務容器的託管服務集合中註冊的每個執行。 在 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 應用程式設定>章節,將說明如何覆寫預設的建立器設定。

架構提供的服務

下列服務會自動註冊:

如需架構所提供之服務的詳細資訊,請參閱 .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:

IHostEnvironment

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

Web apps 會執行 IWebHostEnvironment 介面,此介面會繼承 IHostEnvironment 並新增 WebRootPath

主機組態

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

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

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

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

ConfigureAppConfiguration 建立的組態位於 HostBuilderContext.Configuration,可用於後續作業並用作 DI 中的服務。 主機組態也會新增至應用程式組態。

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

所有應用程式類型的設定

本節列出適用於 HTTP 和非 HTTP 工作負載的主機設定。 根據預設,用來設定這些設定的環境變數可以具有 DOTNET_ASPNETCORE_ 前置詞。

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 (true1)
預設 值:預設為, false 除非應用程式在 Kestrel IIS 後方執行,預設值為 true
環境變數<PREFIX_>CAPTURESTARTUPERRORS

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

webBuilder.CaptureStartupErrors(true);

DetailedErrors

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

機碼detailedErrors
類型bool (true1)
預設值false
環境變數<PREFIX_>_DETAILEDERRORS

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

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

HostingStartupAssemblies

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

機碼hostingStartupAssemblies
類型string
預設值:空字串
環境變數<PREFIX_>_HOSTINGSTARTUPASSEMBLIES

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

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

HostingStartupExcludeAssemblies

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

機碼hostingStartupExcludeAssemblies
類型string
預設值:空字串
環境變數<PREFIX_>_HOSTINGSTARTUPEXCLUDEASSEMBLIES

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

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

HTTPS_Port

HTTPS 重新導向連接埠。 用於強制 HTTPS

機碼https_port
類型string
預設 值:未設定預設值。
環境變數<PREFIX_>HTTPS_PORT

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

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

PreferHostingUrls

指出主機是否應接聽使用設定的 Url, IWebHostBuilder 而不是使用執行時所設定的 url IServer

機碼preferHostingUrls
類型bool (true1)
預設值true
環境變數<PREFIX_>_PREFERHOSTINGURLS

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

webBuilder.PreferHostingUrls(false);

PreventHostingStartup

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

機碼preventHostingStartup
類型bool (true1)
預設值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>();

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。 如需詳細資訊,請參閱KestrelASP.NET Core 中的 web 伺服器執行

WebRoot

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

機碼webroot
類型string
預設 值:預設值為 wwwroot{Content root}/wwwroot 的路徑必須存在。
環境變數<PREFIX_>WEBROOT

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

webBuilder.UseWebRoot("public");

如需詳細資訊,請參閱

管理主機存留期

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

執行

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

RunAsync

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

RunConsoleAsync

RunConsoleAsync啟用主控台支援、建立並啟動主機,以及等候Ctrl + C/SIGINT 或 SIGTERM 關閉。

開始

Start 會同步啟動主機。

StartAsync

StartAsync 會啟動主機,並傳回觸發取消語彙基元或關機時所完成的 Task

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

StopAsync

StopAsync 會嘗試在提供的逾時內停止主機。

WaitForShutdown

WaitForShutdown封鎖呼叫的執行緒,直到 IHostLifetime 觸發關機(例如 via Ctrl + C/SIGINT 或 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 應用程式會設定並啟動主機。 主機負責應用程式啟動和存留期管理。

本文所涵蓋的 ASP.NET Core 泛型主機 (HostBuilder),可用來不會處理 HTTP 要求的應用程式。

泛型主機的用途是將 HTTP 管線從 Web 主機 API 分離,以允許更廣泛的主機陣列案例。 傳訊、背景工作及其他以泛型主機為基礎的非 HTTP 工作負載都受益於跨領域的功能,例如設定、相依性插入 (DI) 和記錄。

泛型主機是 ASP.NET Core 2.1 的新功能,不適用於虛擬主機案例。 針對虛擬主機案例,請使用 Web 主機。 泛型主機將在未來版本中取代 Web 主機,並成為 HTTP 和非 HTTP 案例中的主要主機 API。

查看或下載範例程式碼 (如何下載)

Visual Studio Code 中執行範例應用程式時,請使用「外部或整合式終端機」。 請勿在 internalConsole 中執行範例。

若要在 Visual Studio Code 中設定主控台:

  1. 開啟 .vscode/launch.json 檔案。
  2. 在 [.NET Core Launch (console)] (.NET Core 啟動 (主控台)) 設定中,尋找 console 項目。 將此值設定為 externalTerminalintegratedTerminal

簡介

可使用位於 Microsoft.Extensions.Hosting 命名空間的泛型主機程式庫,且該程式庫由 Microsoft.Extensions.Hosting 套件提供。 Microsoft.AspNetCore.App 中繼套件 (ASP.NET Core 2.1 或更新版本) 包含 Microsoft.Extensions.Hosting 套件。

IHostedService 是程式碼執行的進入點。 每個 IHostedService 實作會依 ConfigureServices 中的服務註冊順序執行。 當主機啟動時,會在每個 IHostedService 上呼叫 StartAsync;當主機順利關閉時,則會依反向註冊順序呼叫 StopAsync

設定主機

IHostBuilder 是程式庫和應用程式用來初始化、建置及執行主機的主要元件:

public static async Task Main(string[] args)
{
    var host = new HostBuilder()
        .Build();

    await host.RunAsync();
}

選項

IHostHostOptions 設定選項。

關機逾時

ShutdownTimeout 會為 StopAsync 設定逾時。 預設值是五秒鐘。

中的下列選項 Program.Main 設定會將預設的五秒關機超時時間增加為20秒:

var host = new HostBuilder()
    .ConfigureServices((hostContext, services) =>
    {
        services.Configure<HostOptions>(option =>
        {
            option.ShutdownTimeout = System.TimeSpan.FromSeconds(20);
        });
    })
    .Build();

預設服務

下列服務會在主機初始化期間註冊:

主機組態

主機組態的建立方式:

擴充方法

應用程式索引鍵 (名稱)

IHostingEnvironment.ApplicationName 屬性是在主機建構期間從主機設定當中設定。 若要明確設定該值,請使用 HostDefaults.ApplicationKey

機碼applicationName
類型string
預設:包含應用程式進入點的組件名稱。
設定使用HostBuilderContext.HostingEnvironment.ApplicationName
環境變數<PREFIX_>APPLICATIONNAME (<PREFIX_>選擇性的,而且是使用者定義的)

內容根目錄

此設定可決定主機開始搜尋內容檔案的位置。

機碼contentRoot
類型string
預設值:預設為應用程式組件所在的資料夾。
設定使用UseContentRoot
環境變數<PREFIX_>CONTENTROOT (<PREFIX_>選擇性的,而且是使用者定義的)

如果路徑不存在,就無法啟動主機。

var host = new HostBuilder()
    .UseContentRoot("c:\\<content-root>")

如需詳細資訊,請參閱 基本概念:內容根目錄

環境

設定應用程式的 環境

機碼environment
類型string
預設值Production
設定使用UseEnvironment
環境變數<PREFIX_>ENVIRONMENT (<PREFIX_>選擇性的,而且是使用者定義的)

環境可以設定為任何值。 架構定義的值包括 DevelopmentStagingProduction。 值不區分大小寫。

var host = new HostBuilder()
    .UseEnvironment(EnvironmentName.Development)

ConfigureHostConfiguration

ConfigureHostConfiguration 會使用 IConfigurationBuilder 來建立主機的 IConfiguration。 主機組態會用來將 IHostingEnvironment 初始化,使其在應用程式建置流程中可供使用。

ConfigureHostConfiguration 可以多次呼叫,其結果是累加的。 主機會使用指定索引鍵上最後設定值的任何選項。

預設不會包含任何提供者。 您必須明確地指定應用程式在 ConfigureHostConfiguration 之中需要哪個組態提供者,包括:

  • 檔案組態 (例如,來自 hostsettings.json 的檔案)。
  • 環境變數組態。
  • 命令列引數組態。
  • 任何其他必要的組態提供者。

使用之後呼叫檔案組態提供者SetBasePath,並透過指定應用程式基底路徑,就可使用主機的檔案設定。 範例應用程式會使用 JSON 檔案,hostsettings.json,並呼叫 AddJsonFile 取用檔案的主機組態設定。

若要新增主機的環境變數組態,請在主機建立器上呼叫 AddEnvironmentVariablesAddEnvironmentVariables 可接受選擇性的使用者定義前置詞。 範例應用程式會使用前置詞 PREFIX_。 讀取環境變數時,就會移除前置詞。 在設定範例應用程式的主機時,PREFIX_ENVIRONMENT 的環境變數值會變成 environment 索引鍵的主機組態值。

在開發期間使用 Visual Studio 或以 dotnet run 執行應用程式時,可能會在 Properties/launchSettings.json 檔案中設定環境變數。 在 Visual Studio Code 中,可以在開發期間於 .vscode/launch.json 檔案中設定環境變數。 如需詳細資訊,請參閱在 ASP.NET Core 中使用多個環境

命令列組態可透過呼叫 AddCommandLine 新增。 命令列組態會在最後新增,以便命令列引數覆寫由先前組態提供者提供的組態。

hostsettings.json

{
  "environment": "Development"
}

您可以使用 applicationNamecontentRoot 索引鍵來提供其他組態。

使用 ConfigureHostConfigurationHostBuilder 組態範例:

var host = new HostBuilder()
    .ConfigureHostConfiguration(configHost =>
    {
        configHost.SetBasePath(Directory.GetCurrentDirectory());
        configHost.AddJsonFile("hostsettings.json", optional: true);
        configHost.AddEnvironmentVariables(prefix: "PREFIX_");
        configHost.AddCommandLine(args);
    })

ConfigureAppConfiguration

應用程式組態的建立方式是在 IHostBuilder 實作上呼叫 ConfigureAppConfigurationConfigureAppConfiguration 會使用 IConfigurationBuilder 來建立應用程式的 IConfigurationConfigureAppConfiguration 可以多次呼叫,其結果是累加的。 應用程式會使用指定索引鍵上最後設定值的任何選項。 您可以從後續作業的 HostBuilderContext.ConfigurationServices 中存取 ConfigureAppConfiguration 所建立的組態。

應用程式組態會自動接收由 ConfigureHostConfiguration 提供的主機組態。

使用 ConfigureAppConfiguration 的應用程式組態範例:

var host = new HostBuilder()
    .ConfigureAppConfiguration((hostContext, configApp) =>
    {
        configApp.SetBasePath(Directory.GetCurrentDirectory());
        configApp.AddJsonFile("appsettings.json", optional: true);
        configApp.AddJsonFile(
            $"appsettings.{hostContext.HostingEnvironment.EnvironmentName}.json", 
            optional: true);
        configApp.AddEnvironmentVariables(prefix: "PREFIX_");
        configApp.AddCommandLine(args);
    })

appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "AllowedHosts": "*"
}

appsettings.Development.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "System": "Information",
      "Microsoft": "Information"
    }
  }
}

appsettings.Production.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Error",
      "System": "Information",
      "Microsoft": "Information"
    }
  }
}

若要將設定檔移至輸出目錄,請在專案檔中將設定檔指定為 MSBuild 專案項目。 範例應用程式使用下列 <Content> 項目,移動其 JSON 應用程式設定檔和 hostsettings.json

<ItemGroup>
  <Content Include="**\*.json" Exclude="bin\**\*;obj\**\*" 
      CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

注意

組態擴充方法 (例如 AddJsonFileAddEnvironmentVariables) 需要其他的 NuGet 套件,例如 Microsoft.Extensions.Configuration.Json (英文) 和Microsoft.Extensions.Configuration.EnvironmentVariables (英文)。 除非應用程式使用 Microsoft.AspNetCore.App metapackage,否則,除了核心 Microsoft.Extensions.Configuration (英文) 套件,還必須將這些套件新增至專案。 如需詳細資訊,請參閱ASP.NET Core 的設定

ConfigureServices

ConfigureServices 會將服務新增至應用程式的相依性插入容器。 ConfigureServices 可以多次呼叫,其結果是累加的。

託管服務是具有背景工作邏輯的類別,可實作 IHostedService 介面。 如需詳細資訊,請參閱在 ASP.NET Core 中使用託管服務的背景工作

範例應用程式使用 AddHostedService 擴充方法,將存留期事件 LifetimeEventsHostedService 和計時背景工作 TimedHostedService 等服務新增至應用程式:

var host = new HostBuilder()
    .ConfigureServices((hostContext, services) =>
    {
        if (hostContext.HostingEnvironment.IsDevelopment())
        {
            // Development service configuration
        }
        else
        {
            // Non-development service configuration
        }

        services.AddHostedService<LifetimeEventsHostedService>();
        services.AddHostedService<TimedHostedService>();
    })

ConfigureLogging

ConfigureLogging 會新增委派以設定提供的 ILoggingBuilderConfigureLogging 可以多次呼叫,其結果是累加的。

var host = new HostBuilder()
    .ConfigureLogging((hostContext, configLogging) =>
    {
        configLogging.AddConsole();
        configLogging.AddDebug();
    })

UseConsoleLifetime

UseConsoleLifetime接聽Ctrl + C/SIGINT 或 SIGTERM,並呼叫 StopApplication 以啟動關機程式。 UseConsoleLifetime 解除封鎖 RunAsync>waitforshutdownasync等擴充功能。 Microsoft.Extensions.Hosting.Internal.ConsoleLifetime 會預先註冊為預設存留期實作。 系統會使用最後一個註冊的存留期。

var host = new HostBuilder()
    .UseConsoleLifetime()

容器設定

為支援插入其他容器,主機可以接受 IServiceProviderFactory<TContainerBuilder>。 提供處理站不是 DI 容器註冊的一部分,而是用來建立實體 DI 容器的主機內建功能。 UseServiceProviderFactory(IServiceProviderFactory<TContainerBuilder>) 會覆寫用來建立應用程式服務提供者的預設處理站。

自訂容器組態由 ConfigureContainer 方法管理。 ConfigureContainer 提供在基礎主機 API 上設定容器的強型別體驗。 ConfigureContainer 可以多次呼叫,其結果是累加的。

建立應用程式的服務容器:

namespace GenericHostSample
{
    internal class ServiceContainer
    {
    }
}

提供服務容器處理站:

using System;
using Microsoft.Extensions.DependencyInjection;

namespace GenericHostSample
{
    internal class ServiceContainerFactory : 
        IServiceProviderFactory<ServiceContainer>
    {
        public ServiceContainer CreateBuilder(
            IServiceCollection services)
        {
            return new ServiceContainer();
        }

        public IServiceProvider CreateServiceProvider(
            ServiceContainer containerBuilder)
        {
            throw new NotImplementedException();
        }
    }
}

使用處理站,並設定應用程式的自訂服務容器:

var host = new HostBuilder()
    .UseServiceProviderFactory<ServiceContainer>(new ServiceContainerFactory())
    .ConfigureContainer<ServiceContainer>((hostContext, container) =>
    {
    })

擴充性

主機擴充性是透過 IHostBuilder 上的擴充方法執行。 下列範例使用 在 ASP.NET Core 中使用託管服務的背景工作 中示範的 TimedHostedService 範例顯示擴充方法如何擴充 IHostBuilder 實作。

var host = new HostBuilder()
    .UseHostedService<TimedHostedService>()
    .Build();

await host.StartAsync();

應用程式會建立 UseHostedService 擴充方法以註冊在 T 中傳遞的裝載服務:

using System;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

public static class Extensions
{
    public static IHostBuilder UseHostedService<T>(this IHostBuilder hostBuilder)
        where T : class, IHostedService, IDisposable
    {
        return hostBuilder.ConfigureServices(services =>
            services.AddHostedService<T>());
    }
}

管理主機

IHost 實作負責啟動及停止服務容器中已註冊的 IHostedService 實作。

執行

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

public class Program
{
    public void Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        host.Run();
    }
}

RunAsync

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

public class Program
{
    public static async Task Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        await host.RunAsync();
    }
}

RunConsoleAsync

RunConsoleAsync啟用主控台支援、建立並啟動主機,以及等候Ctrl + C/SIGINT 或 SIGTERM 關閉。

public class Program
{
    public static async Task Main(string[] args)
    {
        var hostBuilder = new HostBuilder();

        await hostBuilder.RunConsoleAsync();
    }
}

Start 和 StopAsync

Start 會同步啟動主機。

StopAsync 會嘗試在提供的逾時內停止主機。

public class Program
{
    public static async Task Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        using (host)
        {
            host.Start();

            await host.StopAsync(TimeSpan.FromSeconds(5));
        }
    }
}

StartAsync 和 StopAsync

StartAsync 會啟動應用程式。

StopAsync 會停止應用程式。

public class Program
{
    public static async Task Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        using (host)
        {
            await host.StartAsync();

            await host.StopAsync();
        }
    }
}

WaitForShutdown

WaitForShutdown會透過來觸發 IHostLifetime ,例如 Microsoft.Extensions.Hosting.Internal.ConsoleLifetime (接聽Ctrl + C/SIGINT 或 SIGTERM) 。 WaitForShutdown 會呼叫 StopAsync

public class Program
{
    public void Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        using (host)
        {
            host.Start();

            host.WaitForShutdown();
        }
    }
}

WaitForShutdownAsync

WaitForShutdownAsync 會傳回透過指定語彙基元觸發關機時所完成的 Task,並呼叫 StopAsync

public class Program
{
    public static async Task Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        using (host)
        {
            await host.StartAsync();

            await host.WaitForShutdownAsync();
        }

    }
}

外部控制

主機的外部控制可以使用可從外部呼叫的方法來達成:

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

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

IHostingEnvironment 介面

IHostingEnvironment 提供應用程式主控環境的相關資訊。 使用建構函式插入以取得 IHostingEnvironment,才能使用其屬性和擴充方法:

public class MyClass
{
    private readonly IHostingEnvironment _env;

    public MyClass(IHostingEnvironment env)
    {
        _env = env;
    }

    public void DoSomething()
    {
        var environmentName = _env.EnvironmentName;
    }
}

如需詳細資訊,請參閱在 ASP.NET Core 中使用多個環境

IApplicationLifetime 介面

IApplicationLifetime 允許啟動後和關機活動,包括順利關機要求。 在介面上的三個屬性是用來註冊定義啟動和關閉事件之 Action 方法的取消語彙基元。

取消權杖 觸發時機…
ApplicationStarted 已完全啟動主機。
ApplicationStopped 主機正在完成正常關機程序。 應該處理所有要求。 關機封鎖,直到完成此事件。
ApplicationStopping 主機正在執行正常關機程序。 可能仍在處理要求。 關機封鎖,直到完成此事件。

建構函式將 IApplicationLifetime 服務插入任何類別。 範例應用程式使用建構函式插入 LifetimeEventsHostedService 類別 (IHostedService 實作) 來註冊事件。

LifetimeEventsHostedService.cs

internal class LifetimeEventsHostedService : IHostedService
{
    private readonly ILogger _logger;
    private readonly IApplicationLifetime _appLifetime;

    public LifetimeEventsHostedService(
        ILogger<LifetimeEventsHostedService> logger, 
        IApplicationLifetime 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
    }
}

StopApplication 會要求應用程式終止。 當呼叫類別的 Shutdown 方法時,下列類別使用 StopApplication 來順利關閉應用程式:

public class MyClass
{
    private readonly IApplicationLifetime _appLifetime;

    public MyClass(IApplicationLifetime appLifetime)
    {
        _appLifetime = appLifetime;
    }

    public void Shutdown()
    {
        _appLifetime.StopApplication();
    }
}

其他資源

  • 在 ASP.NET Core 中使用託管服務的背景工作
  • GitHub 連結至一般主機來源

    注意

    ASP.NET Core 參考來源的檔連結會載入儲存機制的 main 分支,代表下一版 ASP.NET Core 的產品單位目前的開發。 若要選取不同版本的分支,請使用 [ 切換分支或標記 ] 下拉式清單來選取分支。 例如,選取 release/5.0 ASP.NET Core 5.0 版本的分支。