.NET での汎用ホスト.NET Generic Host

この記事では .NET Core 汎用ホスト (HostBuilder) について紹介し、その使用方法に関するガイダンスを示します。This article introduces the .NET Core Generic Host (HostBuilder) and provides guidance on how to use it.

ホストとは何ですか?What's a host?

"ホスト" とは、以下のようなアプリのリソースをカプセル化するオブジェクトです:A host is an object that encapsulates an app's resources, such as:

  • 依存関係の挿入 (DI)Dependency injection (DI)
  • ログの記録Logging
  • 構成Configuration
  • IHostedService の実装IHostedService implementations

ホストを開始すると、DI コンテナー内で検出された IHostedService の各実装に対して IHostedService.StartAsync が呼び出されます。When a host starts, it calls IHostedService.StartAsync on each implementation of IHostedService that it finds in the DI container. Web アプリでは、IHostedService 実装の 1 つが HTTP サーバー実装を起動する Web サービスとなります。In a web app, one of the IHostedService implementations is a web service that starts an HTTP server implementation.

アプリの相互依存するすべてのリソースを 1 つのオブジェクトに含める主な理由は、アプリの起動と正常なシャットダウンの制御の有効期間の管理のためです。The main reason for including all of the app's interdependent resources in one object is lifetime management: control over app startup and graceful shutdown.

ASP.NET Core の 3.0 より前のバージョンでは、Web ホストが HTTP ワークロードに使用されます。In versions of ASP.NET Core earlier than 3.0, the Web Host is used for HTTP workloads. Web ホストは Web アプリの推奨ホストではなくなり、下位互換性用のみに引き続き利用できます。The Web Host is no longer recommended for web apps and remains available only for backward compatibility.

ホストを設定するSet up a host

ホストは通常、Program クラス内のコードによって構成、ビルド、および実行されます。The host is typically configured, built, and run by code in the Program class. Main メソッド:The Main method:

  • CreateHostBuilder メソッドを呼び出して、builder オブジェクトを作成および構成します。Calls a CreateHostBuilder method to create and configure a builder object.
  • builder オブジェクト上で Build メソッドと Run メソッドを呼び出します。Calls Build and Run methods on the builder object.

HTTP 以外のワークロード用の Program.cs コードを次に示します。単一の IHostedService 実装が DI コンテナーに追加されています。Here's Program.cs code for a non-HTTP workload, with a single IHostedService implementation added to the DI container.

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 が呼び出されます。For an HTTP workload, the Main method is the same but CreateHostBuilder calls ConfigureWebHostDefaults:

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

Entity Framework Core がアプリで使用されている場合は、CreateHostBuilder メソッドの名前またはシグネチャを変更しないでください。If the app uses Entity Framework Core, don't change the name or signature of the CreateHostBuilder method. Entity Framework Core ツール では、アプリを実行することなくホストを構成する CreateHostBuilder メソッドを検出することが想定されています。The Entity Framework Core tools expect to find a CreateHostBuilder method that configures the host without running the app. 詳細については、「デザイン時 DbContext 作成」をご覧ください。For more information, see Design-time DbContext Creation.

既定の builder 設定Default builder settings

CreateDefaultBuilder メソッド:The CreateDefaultBuilder method:

  • コンテンツ ルートを、GetCurrentDirectory によって返されるパスに設定します。Sets the content root to the path returned by GetCurrentDirectory.
  • 次からホスト構成を読み込みます。Loads host configuration from:
    • プレフィックス "DOTNET_" が付いた環境変数。Environment variables prefixed with "DOTNET_".
    • コマンド ライン引数。Command-line arguments.
  • 次からアプリの構成を読み込みます。Loads app configuration from:
    • appsettings.jsonappsettings.json.
    • appsettings.{Environment}.jsonappsettings.{Environment}.json.
    • Development 環境でアプリが実行される場合に使用されるシークレット マネージャーSecret Manager when the app runs in the Development environment.
    • 環境変数。Environment variables.
    • コマンド ライン引数。Command-line arguments.
  • 次のログ プロバイダーを追加します。Adds the following logging providers:
    • コンソールConsole
    • デバッグDebug
    • EventSourceEventSource
    • イベント ログ (Windows で実行されている場合のみ)EventLog (only when running on Windows)
  • 環境が [開発] になっている場合は、スコープの検証依存関係の検証を有効にします。Enables scope validation and dependency validation when the environment is Development.

ConfigureWebHostDefaults メソッド:The ConfigureWebHostDefaults method:

この記事で後述する「すべての種類のアプリの設定」および「Web アプリの設定」セクションに、既定のビルダー設定をオーバーライドする方法を示します。The Settings for all app types and Settings for web apps sections later in this article show how to override default builder settings.

フレームワークが提供するサービスFramework-provided services

自動的に登録されるサービスには、次のものが含まれます。Services that are registered automatically include the following:

フレームワークによって提供されるサービスの詳細については、ASP.NET Core での依存関係の挿入 を参照してください。For more information on framework-provided services, see ASP.NET Core での依存関係の挿入.

IHostApplicationLifetimeIHostApplicationLifetime

起動後タスクとグレースフル シャットダウン タスクを処理するために IHostApplicationLifetime (旧称 IApplicationLifetime) サービスを任意のクラスに注入します。Inject the IHostApplicationLifetime (formerly IApplicationLifetime) service into any class to handle post-startup and graceful shutdown tasks. インターフェイス上の 3 つのプロパティは、アプリの起動およびアプリの停止のイベント ハンドラー メソッドを登録するために使用されるキャンセル トークンです。Three properties on the interface are cancellation tokens used to register app start and app stop event handler methods. インターフェイスには StopApplication メソッドも含まれています。The interface also includes a StopApplication method.

次の例は、IHostApplicationLifetime イベントを登録する IHostedService の実装です。The following example is an IHostedService implementation that registers IHostApplicationLifetime events:

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

IHostLifetimeIHostLifetime

IHostLifetime 実装では、ホストを開始および停止するタイミングが制御されます。The IHostLifetime implementation controls when the host starts and when it stops. 登録されている最後の実装が使用されます。The last implementation registered is used.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime は、既定の IHostLifetime 実装です。Microsoft.Extensions.Hosting.Internal.ConsoleLifetime is the default IHostLifetime implementation. ConsoleLifetime:ConsoleLifetime:

IHostEnvironmentIHostEnvironment

次に関する情報を取得するために、クラスに IHostEnvironment サービスを注入します。Inject the IHostEnvironment service into a class to get information about the following:

Web アプリでは IWebHostEnvironment インターフェイスが追加されます。こによって、IHostEnvironment が継承され、次が追加されます。Web apps implement the IWebHostEnvironment interface, which inherits IHostEnvironment and adds:

ホストの構成Host configuration

ホストの構成は、IHostEnvironment 実装のプロパティで使用されます。Host configuration is used for the properties of the IHostEnvironment implementation.

ホストの構成は、ConfigureAppConfiguration 内の HostBuilderContext.Configuration から使用できます。Host configuration is available from HostBuilderContext.Configuration inside ConfigureAppConfiguration. ConfigureAppConfiguration の後、HostBuilderContext.Configuration はアプリの構成に置き換えられます。After ConfigureAppConfiguration, HostBuilderContext.Configuration is replaced with the app config.

ホストの構成を追加するには、IHostBuilder 上で ConfigureHostConfiguration を呼び出します。To add host configuration, call ConfigureHostConfiguration on IHostBuilder. ConfigureHostConfiguration を複数回呼び出して結果を追加できます。ConfigureHostConfiguration can be called multiple times with additive results. ホストは、指定されたキーで最後に値を設定したオプションを使用します。The host uses whichever option sets a value last on a given key.

プレフィックス DOTNET_ を持つ環境変数プロバイダーと、コマンド ライン引数が CreateDefaultBuilder によって取り込まれます。The environment variable provider with prefix DOTNET_ and command line args are included by CreateDefaultBuilder. Web アプリの場合は、プレフィックス ASPNETCORE_ を持つ環境変数プロバイダーが追加されます。For web apps, the environment variable provider with prefix ASPNETCORE_ is added. 環境変数が読み取られると、プレフィックスは削除されます。The prefix is removed when the environment variables are read. たとえば、ASPNETCORE_ENVIRONMENT の環境変数の値が environment キーのホスト構成値になります。For example, the environment variable value for ASPNETCORE_ENVIRONMENT becomes the host configuration value for the environment key.

次の例では、ホストの構成を作成します。The following example creates host configuration:

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

アプリの構成App configuration

アプリの構成は、IHostBuilder 上で ConfigureAppConfiguration を呼び出すことで作成されます。App configuration is created by calling ConfigureAppConfiguration on IHostBuilder. ConfigureAppConfiguration を複数回呼び出して結果を追加できます。ConfigureAppConfiguration can be called multiple times with additive results. アプリは、指定されたキーで最後に値を設定したオプションを使用します。The app uses whichever option sets a value last on a given key.

ConfigureAppConfiguration によって作成された構成は、 HostBuilderContext.Configuration で、以降の操作のために、かつ DI からのサービスとして利用できます。The configuration created by ConfigureAppConfiguration is available at HostBuilderContext.Configuration for subsequent operations and as a service from DI. ホストの構成はアプリの構成にも追加されます。The host configuration is also added to the app configuration.

詳細については、「ASP.NET Core の構成」を参照してください。For more information, see Configuration in ASP.NET Core.

すべての種類のアプリの設定Settings for all app types

このセクションでは、HTTP のワークロードと HTTP 以外のワークロードの両方に適用されるホストの設定を一覧します。This section lists host settings that apply to both HTTP and non-HTTP workloads. 既定では、これらの設定を構成するのに使用する環境変数には、プレフィックスとして DOTNET_ または ASPNETCORE_ を付けることができます。By default, environment variables used to configure these settings can have a DOTNET_ or ASPNETCORE_ prefix.

ApplicationNameApplicationName

IHostEnvironment.ApplicationName プロパティは、ホストの構築時にホストの構成から設定されます。The IHostEnvironment.ApplicationName property is set from host configuration during host construction.

キー: applicationNameKey: applicationName
: 文字列Type: string
既定: アプリのエントリ ポイントを含むアセンブリの名前。Default: The name of the assembly that contains the app's entry point. 環境変数: <PREFIX_>APPLICATIONNAMEEnvironment variable: <PREFIX_>APPLICATIONNAME

この値を設定するには、環境変数を使用します。To set this value, use the environment variable.

ContentRootPathContentRootPath

IHostEnvironment.ContentRootPath プロパティでは、ホストがコンテンツ ファイルの検索を開始する位置が決定されます。The IHostEnvironment.ContentRootPath property determines where the host begins searching for content files. パスが存在しない場合は、ホストを起動できません。If the path doesn't exist, the host fails to start.

キー: contentRootKey: contentRoot
: 文字列Type: string
既定: アプリ アセンブリが存在するフォルダー。Default: The folder where the app assembly resides.
環境変数: <PREFIX_>CONTENTROOTEnvironment variable: <PREFIX_>CONTENTROOT

この値を設定するには、環境変数を使用するか、または IHostBuilder 上で UseContentRoot を呼び出します。To set this value, use the environment variable or call UseContentRoot on IHostBuilder:

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

詳細については次を参照してください:For more information, see:

EnvironmentNameEnvironmentName

IHostEnvironment.EnvironmentName プロパティは、任意の値に設定することができます。The IHostEnvironment.EnvironmentName property can be set to any value. フレームワークで定義された値には DevelopmentStagingProduction が含まれます。Framework-defined values include Development, Staging, and Production. 値は大文字と小文字が区別されません。Values aren't case sensitive.

キー: 環境Key: environment
: 文字列Type: string
既定値:実稼働Default: Production
環境変数: <PREFIX_>ENVIRONMENTEnvironment variable: <PREFIX_>ENVIRONMENT

この値を設定するには、環境変数を使用するか、または IHostBuilder 上で UseEnvironment を呼び出します。To set this value, use the environment variable or call UseEnvironment on IHostBuilder:

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

ShutdownTimeoutShutdownTimeout

HostOptions.ShutdownTimeout では、StopAsync のタイムアウトが設定されます。HostOptions.ShutdownTimeout sets the timeout for StopAsync. 既定値は 5 秒です。The default value is five seconds. タイムアウト期間中、ホストでは次のことが行われます。During the timeout period, the host:

すべてのホステッド サービスが停止する前にタイムアウト時間が切れた場合、残っているアクティブなサービスはアプリのシャットダウン時に停止します。If the timeout period expires before all of the hosted services stop, any remaining active services are stopped when the app shuts down. 処理が完了していない場合でも、サービスは停止します。The services stop even if they haven't finished processing. サービスが停止するまでにさらに時間が必要な場合は、タイムアウト値を増やします。If services require additional time to stop, increase the timeout.

キー: shutdownTimeoutSecondsKey: shutdownTimeoutSeconds
: intType: int
既定: 5 秒 環境変数: <PREFIX_>SHUTDOWNTIMEOUTSECONDSDefault: 5 seconds Environment variable: <PREFIX_>SHUTDOWNTIMEOUTSECONDS

この値を設定するには、環境変数を使用するか、または HostOptions を構成します。To set this value, use the environment variable or configure HostOptions. 次の例では、タイムアウトを 20 秒に設定します。The following example sets the timeout to 20 seconds:

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

Web アプリの設定Settings for web apps

一部のホスト設定は、HTTP のワークロードにのみに適用されます。Some host settings apply only to HTTP workloads. 既定では、これらの設定を構成するのに使用する環境変数には、プレフィックスとして DOTNET_ または ASPNETCORE_ を付けることができます。By default, environment variables used to configure these settings can have a DOTNET_ or ASPNETCORE_ prefix.

IWebHostBuilder 上の拡張メソッドはこれらの設定で使用できます。Extension methods on IWebHostBuilder are available for these settings. 次の例に示すように、拡張メソッドを呼び出す方法を示すコード サンプルでは webBuilderIWebHostBuilder のインスタンスであると想定しています。Code samples that show how to call the extension methods assume webBuilder is an instance of IWebHostBuilder, as in the following example:

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

CaptureStartupErrorsCaptureStartupErrors

false の場合、起動時にエラーが発生するとホストが終了します。When false, errors during startup result in the host exiting. true の場合、ホストは起動時に例外をキャプチャして、サーバーを起動しようとします。When true, the host captures exceptions during startup and attempts to start the server.

キー: captureStartupErrorsKey: captureStartupErrors
: ブール (true または 1)Type: bool (true or 1)
既定値:アプリが IIS の背後で Kestrel を使用して実行されている場合 (既定値は true) を除き、既定では false に設定されます。Default: Defaults to false unless the app runs with Kestrel behind IIS, where the default is true.
環境変数: <PREFIX_>CAPTURESTARTUPERRORSEnvironment variable: <PREFIX_>CAPTURESTARTUPERRORS

この値を設定するには、構成を使用するか、または CaptureStartupErrors を呼び出します。To set this value, use configuration or call CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

DetailedErrorsDetailedErrors

有効にされている場合、または環境が Development である場合、アプリによって詳細なエラーがキャプチャされます。When enabled, or when the environment is Development, the app captures detailed errors.

キー: detailedErrorsKey: detailedErrors
: ブール (true または 1)Type: bool (true or 1)
既定値: falseDefault: false
環境変数: <PREFIX_>_DETAILEDERRORSEnvironment variable: <PREFIX_>_DETAILEDERRORS

この値を設定するには、構成を使用するか、または UseSetting を呼び出します。To set this value, use configuration or call UseSetting:

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

HostingStartupAssembliesHostingStartupAssemblies

起動時に読み込むホスティング スタートアップ アセンブリのセミコロンで区切られた文字列。A semicolon-delimited string of hosting startup assemblies to load on startup. 構成値は既定で空の文字列に設定されますが、ホスティング スタートアップ アセンブリには常にアプリのアセンブリが含まれます。Although the configuration value defaults to an empty string, the hosting startup assemblies always include the app's assembly. ホスティング スタートアップ アセンブリが提供されている場合、アプリが起動中に共通サービスをビルドしたときに読み込むためにアプリのアセンブリに追加されます。When hosting startup assemblies are provided, they're added to the app's assembly for loading when the app builds its common services during startup.

キー: hostingStartupAssembliesKey: hostingStartupAssemblies
: 文字列Type: string
既定値:空の文字列Default: Empty string
環境変数: <PREFIX_>_HOSTINGSTARTUPASSEMBLIESEnvironment variable: <PREFIX_>_HOSTINGSTARTUPASSEMBLIES

この値を設定するには、構成を使用するか、または UseSetting を呼び出します。To set this value, use configuration or call UseSetting:

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

HostingStartupExcludeAssembliesHostingStartupExcludeAssemblies

起動時に除外するホスティング スタートアップ アセンブリのセミコロン区切り文字列。A semicolon-delimited string of hosting startup assemblies to exclude on startup.

キー: hostingStartupExcludeAssembliesKey: hostingStartupExcludeAssemblies
: 文字列Type: string
既定値:空の文字列Default: Empty string
環境変数: <PREFIX_>_HOSTINGSTARTUPEXCLUDEASSEMBLIESEnvironment variable: <PREFIX_>_HOSTINGSTARTUPEXCLUDEASSEMBLIES

この値を設定するには、構成を使用するか、または UseSetting を呼び出します。To set this value, use configuration or call UseSetting:

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

HTTPS_PortHTTPS_Port

HTTPS リダイレクト ポート。The HTTPS redirect port. HTTPS の適用に使用されます。Used in enforcing HTTPS.

キー: https_portKey: https_port
: 文字列Type: string
既定:既定値は設定されていません。Default: A default value isn't set.
環境変数: <PREFIX_>HTTPS_PORTEnvironment variable: <PREFIX_>HTTPS_PORT

この値を設定するには、構成を使用するか、または UseSetting を呼び出します。To set this value, use configuration or call UseSetting:

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

PreferHostingUrlsPreferHostingUrls

IServer 実装で構成されているものではなく、IWebHostBuilder で構成されている URL でホストがリッスンするかどうかを示します。Indicates whether the host should listen on the URLs configured with the IWebHostBuilder instead of those configured with the IServer implementation.

キー: preferHostingUrlsKey: preferHostingUrls
: ブール (true または 1)Type: bool (true or 1)
既定値: trueDefault: true
環境変数: <PREFIX_>_PREFERHOSTINGURLSEnvironment variable: <PREFIX_>_PREFERHOSTINGURLS

この値を設定するには、環境変数を使用するか、または PreferHostingUrls を呼び出します。To set this value, use the environment variable or call PreferHostingUrls:

webBuilder.PreferHostingUrls(false);

PreventHostingStartupPreventHostingStartup

アプリのアセンブリで構成されているホスティング スタートアップ アセンブリを含む、ホスティング スタートアップ アセンブリの自動読み込みを回避します。Prevents the automatic loading of hosting startup assemblies, including hosting startup assemblies configured by the app's assembly. 詳細については、ASP.NET Core でホスティング スタートアップ アセンブリを使用する を参照してください。For more information, see ASP.NET Core でホスティング スタートアップ アセンブリを使用する.

キー: preventHostingStartupKey: preventHostingStartup
: ブール (true または 1)Type: bool (true or 1)
既定値: falseDefault: false
環境変数: <PREFIX_>_PREVENTHOSTINGSTARTUPEnvironment variable: <PREFIX_>_PREVENTHOSTINGSTARTUP

この値を設定するには、環境変数を使用するか、または UseSetting を呼び出します。To set this value, use the environment variable or call UseSetting :

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

StartupAssemblyStartupAssembly

Startup クラスを検索するアセンブリ。The assembly to search for the Startup class.

キー: startupAssemblyKey: startupAssembly
: 文字列Type: string
既定値:アプリのアセンブリDefault: The app's assembly
環境変数: <PREFIX_>STARTUPASSEMBLYEnvironment variable: <PREFIX_>STARTUPASSEMBLY

この値を設定するには、環境変数を使用するか、または UseStartup を呼び出します。To set this value, use the environment variable or call UseStartup. UseStartup は、アセンブリ名 (string) または型 (TStartup) を取ることができます。UseStartup can take an assembly name (string) or a type (TStartup). 複数の UseStartup メソッドが呼び出された場合は、最後のメソッドが優先されます。If multiple UseStartup methods are called, the last one takes precedence.

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

URLURLs

サーバーが要求をリッスンする必要があるポートとプロトコルを含む IP アドレスまたはホスト アドレスを示すセミコロンで区切られたリスト。A semicolon-delimited list of IP addresses or host addresses with ports and protocols that the server should listen on for requests. たとえば、http://localhost:123 のようにします。For example, http://localhost:123. "*" を使用し、サーバーが指定されたポートとプロトコル (http://*:5000 など) を使用して IP アドレスまたはホスト名に関する要求をリッスンする必要があることを示します。Use "*" to indicate that the server should listen for requests on any IP address or hostname using the specified port and protocol (for example, http://*:5000). プロトコル (http:// または https://) は各 URL に含める必要があります。The protocol (http:// or https://) must be included with each URL. サポートされている形式はサーバー間で異なります。Supported formats vary among servers.

キー: urlsKey: urls
: 文字列Type: string
既定値: http://localhost:5000 および https://localhost:5001Default: http://localhost:5000 and https://localhost:5001
環境変数: <PREFIX_>URLSEnvironment variable: <PREFIX_>URLS

この値を設定するには、環境変数を使用するか、または UseUrls を呼び出します。To set this value, use the environment variable or call UseUrls:

webBuilder.UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002");

Kestrel には独自のエンドポイント構成 API があります。Kestrel has its own endpoint configuration API. 詳細については、ASP.NET Core への Kestrel Web サーバーの実装 を参照してください。For more information, see ASP.NET Core への Kestrel Web サーバーの実装.

WebRootWebRoot

アプリの静的資産への相対パス。The relative path to the app's static assets.

キー: webrootKey: webroot
: 文字列Type: string
既定:既定値は、wwwroot です。Default: The default is wwwroot. {content root}/wwwroot へのパスが存在する必要があります。The path to {content root}/wwwroot must exist. パスが存在しない場合は、no-op ファイル プロバイダーが使用されます。If the path doesn't exist, a no-op file provider is used.
環境変数: <PREFIX_>WEBROOTEnvironment variable: <PREFIX_>WEBROOT

この値を設定するには、環境変数を使用するか、または UseWebRoot を呼び出します。To set this value, use the environment variable or call UseWebRoot:

webBuilder.UseWebRoot("public");

詳細については次を参照してください:For more information, see:

ホストの有効期間を管理するManage the host lifetime

組み込みの IHost 実装でメソッドを呼び出して、アプリの開始および停止を行います。Call methods on the built IHost implementation to start and stop the app. これらのメソッドは、サービス コンテナーに登録されているすべての IHostedService 実装に影響を与えます。These methods affect all IHostedService implementations that are registered in the service container.

実行Run

Run はアプリを実行し、ホストがシャットダウンされるまで呼び出し元のスレッドをブロックします。Run runs the app and blocks the calling thread until the host is shut down.

RunAsyncRunAsync

RunAsync はアプリを実行し、キャンセル トークンまたはシャットダウンがトリガーされると完了する Task を返します。RunAsync runs the app and returns a Task that completes when the cancellation token or shutdown is triggered.

RunConsoleAsyncRunConsoleAsync

RunConsoleAsync は、コンソールのサポートを有効にし、ホストをビルドして開始した後、Ctrl + C/SIGINT または SIGTERM がシャットダウンするのを待機します。RunConsoleAsync enables console support, builds and starts the host, and waits for Ctrl+C/SIGINT or SIGTERM to shut down.

[開始]Start

Start は、ホストを同期的に開始します。Start starts the host synchronously.

StartAsyncStartAsync

StartAsync ではホストが開始され、キャンセル トークンまたはシャットダウンがトリガーされると完了する Task が返されます。StartAsync starts the host and returns a Task that completes when the cancellation token or shutdown is triggered.

WaitForStartAsyncStartAsync の開始時に呼び出され、これが完了するまで待機してから続行します。WaitForStartAsync is called at the start of StartAsync, which waits until it's complete before continuing. これを使って、外部イベントによって通知されるまで開始を遅らせることができます。This can be used to delay startup until signaled by an external event.

StopAsyncStopAsync

StopAsync は、指定されたタイムアウト内でホストの停止を試みます。StopAsync attempts to stop the host within the provided timeout.

WaitForShutdownWaitForShutdown

Ctrl + C/SIGINT や SIGTERM を介するなどして IHostLifetime によってシャットダウンがトリガされるまで、WaitForShutdown では呼び出し側スレッドがブロックされます。WaitForShutdown blocks the calling thread until shutdown is triggered by the IHostLifetime, such as via Ctrl+C/SIGINT or SIGTERM.

WaitForShutdownAsyncWaitForShutdownAsync

WaitForShutdownAsync が返す Task は、提供されたトークンによってシャットダウンがトリガーされると完了し、StopAsync を呼び出します。WaitForShutdownAsync returns a Task that completes when shutdown is triggered via the given token and calls StopAsync.

外部コントロールExternal control

ホストの有効期間の直接コントロールは、外部から呼び出すことができるメソッドを使って実現できます。Direct control of the host lifetime can be achieved using methods that can be called externally:

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 apps configure and launch a host. ホストはアプリの起動と有効期間の管理を担当します。The host is responsible for app startup and lifetime management.

この記事では、HTTP 要求を処理しないアプリに使用される、ASP.NET Core の汎用ホスト (HostBuilder) について説明します。This article covers the ASP.NET Core Generic Host (HostBuilder), which is used for apps that don't process HTTP requests.

汎用ホストの目的は、Web ホスト API から HTTP パイプラインを切り離して、多様なホスト シナリオを有効にすることです。The purpose of Generic Host is to decouple the HTTP pipeline from the Web Host API to enable a wider array of host scenarios. メッセージング、バックグラウンド タスク、汎用ホストに基づくその他の HTTP ワークロードに対して、構成、依存関係の挿入 (DI)、ログなどの横断的機能によるメリットがあります。Messaging, background tasks, and other non-HTTP workloads based on Generic Host benefit from cross-cutting capabilities, such as configuration, dependency injection (DI), and logging.

汎用ホストは ASP.NET Core 2.1 の新機能であり、Web ホスティングのシナリオには適していません。Generic Host is new in ASP.NET Core 2.1 and isn't suitable for web hosting scenarios. Web ホスティングのシナリオの場合は、Web ホストを使ってください。For web hosting scenarios, use the Web Host. 汎用ホストは将来のリリースで Web ホストに代わるものであり、HTTP と非 HTTP 両方のシナリオのプライマリ ホスト API として機能するようになります。Generic Host will replace Web Host in a future release and act as the primary host API in both HTTP and non-HTTP scenarios.

サンプル コードを表示またはダウンロードします (ダウンロード方法)。View or download sample code (how to download)

Visual Studio Code でサンプル アプリを実行するときは、"外部ターミナルまたは統合ターミナル" を使います。When running the sample app in Visual Studio Code, use an external or integrated terminal. internalConsole ではサンプルを実行しないでください。Don't run the sample in an internalConsole.

Visual Studio Code でコンソールを設定するには:To set the console in Visual Studio Code:

  1. .vscode/launch.json ファイルを開きます。Open the .vscode/launch.json file.
  2. .NET Core Launch (console) の構成で、console エントリを探します。In the .NET Core Launch (console) configuration, locate the console entry. 値を externalTerminal または integratedTerminal に設定します。Set the value to either externalTerminal or integratedTerminal.

はじめにIntroduction

汎用ホスト ライブラリは、Microsoft.Extensions.Hosting 名前空間で使用でき、Microsoft.Extensions.Hosting パッケージで提供されます。The Generic Host library is available in the Microsoft.Extensions.Hosting namespace and provided by the Microsoft.Extensions.Hosting package. Microsoft.Extensions.Hosting パッケージは、Microsoft.AspNetCore.App メタパッケージに含まれます (ASP.NET Core 2.1 以降)。The Microsoft.Extensions.Hosting package is included in the Microsoft.AspNetCore.App metapackage (ASP.NET Core 2.1 or later).

IHostedService がコード実行のエントリ ポイントです。IHostedService is the entry point to code execution. IHostedService の各実装は、ConfigureServices でのサービス登録の順序で実行されます。Each IHostedService implementation is executed in the order of service registration in ConfigureServices. ホストが開始するときは IHostedService ごとに StartAsync が呼び出され、ホストが正常に終了するときは登録と逆の順序で StopAsync が呼び出されます。StartAsync is called on each IHostedService when the host starts, and StopAsync is called in reverse registration order when the host shuts down gracefully.

ホストを設定するSet up a host

IHostBuilder は、ライブラリとアプリがホストの初期化、ビルド、実行に使用するメイン コンポーネントです。IHostBuilder is the main component that libraries and apps use to initialize, build, and run the host:

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

    await host.RunAsync();
}

オプションOptions

IHostHostOptions 構成オプションです。HostOptions configure options for the IHost.

シャットダウン タイムアウトShutdown timeout

ShutdownTimeout によって StopAsync のタイムアウトが設定されます。ShutdownTimeout sets the timeout for StopAsync. 既定値は 5 秒です。The default value is five seconds.

次に示す Program.Main のオプション構成では、既定の 5 秒のシャットダウン タイムアウトが 20 秒に延長されます。The following option configuration in Program.Main increases the default five second shutdown timeout to 20 seconds:

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

既定のサービスDefault services

次のサービスは、ホストの初期化中に登録されます。The following services are registered during host initialization:

ホストの構成Host configuration

ホストの構成は、次のようにして作成されます。Host configuration is created by:

拡張メソッドExtension methods

アプリケーション キー (名前)Application key (name)

IHostingEnvironment.ApplicationName プロパティは、ホストの構築時にホストの構成から設定されます。The IHostingEnvironment.ApplicationName property is set from host configuration during host construction. 値を明示的に設定するには、HostDefaults.ApplicationKey を使用します。To set the value explicitly, use the HostDefaults.ApplicationKey:

キー: applicationNameKey: applicationName
: 文字列Type: string
既定値:アプリのエントリ ポイントを含むアセンブリの名前。Default: The name of the assembly containing the app's entry point.
次を使用して設定: HostBuilderContext.HostingEnvironment.ApplicationNameSet using: HostBuilderContext.HostingEnvironment.ApplicationName
環境変数: <PREFIX_>APPLICATIONNAME (<PREFIX_>オプションであり、ユーザー定義です)Environment variable: <PREFIX_>APPLICATIONNAME (<PREFIX_> is optional and user-defined)

コンテンツ ルートContent root

この設定では、ホストがコンテンツ ファイルの検索を開始する場所を決定します。This setting determines where the host begins searching for content files.

キー: contentRootKey: contentRoot
: 文字列Type: string
既定値:既定でアプリ アセンブリが存在するフォルダーに設定されます。Default: Defaults to the folder where the app assembly resides.
次を使用して設定: UseContentRootSet using: UseContentRoot
環境変数: <PREFIX_>CONTENTROOT (<PREFIX_>オプションであり、ユーザー定義です)Environment variable: <PREFIX_>CONTENTROOT (<PREFIX_> is optional and user-defined)

パスが存在しない場合は、ホストを起動できません。If the path doesn't exist, the host fails to start.

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

詳細については、基礎: コンテンツ ルートに関する記事を参照してください。For more information, see Fundamentals: Content root.

環境Environment

アプリの環境を設定します。Sets the app's environment.

キー: 環境Key: environment
: 文字列Type: string
既定値:実稼働Default: Production
次を使用して設定: UseEnvironmentSet using: UseEnvironment
環境変数: <PREFIX_>ENVIRONMENT (<PREFIX_>オプションであり、ユーザー定義です)Environment variable: <PREFIX_>ENVIRONMENT (<PREFIX_> is optional and user-defined)

環境は任意の値に設定することができます。The environment can be set to any value. フレームワークで定義された値には DevelopmentStagingProduction が含まれます。Framework-defined values include Development, Staging, and Production. 値は大文字と小文字が区別されません。Values aren't case sensitive.

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

ConfigureHostConfigurationConfigureHostConfiguration

ConfigureHostConfigurationIConfigurationBuilder を使用して、ホストの IConfiguration を作成します。ConfigureHostConfiguration uses an IConfigurationBuilder to create an IConfiguration for the host. ホストの構成は、IHostingEnvironment をアプリのビルド プロセスで使用するための初期化に使用されます。The host configuration is used to initialize the IHostingEnvironment for use in the app's build process.

ConfigureHostConfiguration を複数回呼び出して結果を追加できます。ConfigureHostConfiguration can be called multiple times with additive results. ホストは、指定されたキーで最後に値を設定したオプションを使用します。The host uses whichever option sets a value last on a given key.

既定ではプロバイダーが含まれていません。No providers are included by default. 次のような、アプリが ConfigureHostConfiguration で必要とする構成プロバイダーを明示的に指定する必要があります。You must explicitly specify whatever configuration providers the app requires in ConfigureHostConfiguration, including:

  • ファイルの構成 (hostsettings.json ファイルからなど)。File configuration (for example, from a hostsettings.json file).
  • 環境変数の構成。Environment variable configuration.
  • コマンドライン引数の構成。Command-line argument configuration.
  • その他に必要なすべての構成プロバイダー。Any other required configuration providers.

ホストのファイル構成は、いずれかのファイル構成プロバイダーに対する呼び出しの前に SetBasePath のアプリのベース パスを指定することで有効になります。File configuration of the host is enabled by specifying the app's base path with SetBasePath followed by a call to one of the file configuration providers. サンプル アプリは、JSON ファイル (hostsettings.json) を使用し、AddJsonFile を呼び出して、ファイルのホスト構成設定を使用します。The sample app uses a JSON file, hostsettings.json, and calls AddJsonFile to consume the file's host configuration settings.

ホストの環境変数の構成を追加するには、ホスト ビルダーで AddEnvironmentVariables を呼び出します。To add environment variable configuration of the host, call AddEnvironmentVariables on the host builder. AddEnvironmentVariables は、オプションのユーザー定義プレフィックスを受け入れます。AddEnvironmentVariables accepts an optional user-defined prefix. サンプル アプリは、PREFIX_ のプレフィックスを使用します。The sample app uses a prefix of PREFIX_. 環境変数が読み取られると、プレフィックスは削除されます。The prefix is removed when the environment variables are read. サンプル アプリのホストが構成されると、PREFIX_ENVIRONMENT の環境変数の値が environment キーのホスト構成値になります。When the sample app's host is configured, the environment variable value for PREFIX_ENVIRONMENT becomes the host configuration value for the environment key.

開発中に Visual Studio を使用している、または dotnet run を使用してアプリを実行している場合は、環境変数を Properties/launchSettings.json ファイルに設定することができます。During development when using Visual Studio or running an app with dotnet run, environment variables may be set in the Properties/launchSettings.json file. Visual Studio Code では、開発中に環境変数を .vscode/launch.json ファイルに設定することができます。In Visual Studio Code, environment variables may be set in the .vscode/launch.json file during development. 詳細については、ASP.NET Core で複数の環境を使用する を参照してください。For more information, see ASP.NET Core で複数の環境を使用する.

コマンドラインの構成は、AddCommandLineを呼び出すことで追加されます。Command-line configuration is added by calling AddCommandLine. コマンドラインの構成は、コマンドライン引数を許可して以前の構成プロバイダーから提供された構成をオーバーライドするために最後に追加されます。Command-line configuration is added last to permit command-line arguments to override configuration provided by the earlier configuration providers.

hostsettings.json:hostsettings.json:

{
  "environment": "Development"
}

追加の構成は、applicationNamecontentRoot キーで指定することができます。Additional configuration can be provided with the applicationName and contentRoot keys.

ConfigureHostConfiguration を使う HostBuilder の構成の例:Example HostBuilder configuration using ConfigureHostConfiguration:

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

ConfigureAppConfigurationConfigureAppConfiguration

アプリの構成は、IHostBuilder の実装で ConfigureAppConfiguration を呼び出すことで作成されます。App configuration is created by calling ConfigureAppConfiguration on the IHostBuilder implementation. ConfigureAppConfigurationIConfigurationBuilder を使用して、アプリの IConfiguration を作成します。ConfigureAppConfiguration uses an IConfigurationBuilder to create an IConfiguration for the app. ConfigureAppConfiguration を複数回呼び出して結果を追加できます。ConfigureAppConfiguration can be called multiple times with additive results. アプリは、指定されたキーで最後に値を設定したオプションを使用します。The app uses whichever option sets a value last on a given key. ConfigureAppConfiguration によって作成された構成は、以降の操作に対する HostBuilderContext.Configuration において、および Servicesサービス内で使用できます。The configuration created by ConfigureAppConfiguration is available at HostBuilderContext.Configuration for subsequent operations and in Services.

アプリの構成は、ConfigureHostConfiguration によって提供されたホストの構成を自動的に受信します。App configuration automatically receives host configuration provided by ConfigureHostConfiguration.

ConfigureAppConfiguration を使うアプリ構成の例:Example app configuration using 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:appsettings.json:

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

appsettings.Development.json:appsettings.Development.json:

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

appsettings.Production.json:appsettings.Production.json:

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

設定ファイルを出力ディレクトリに移動するには、プロジェクト ファイルの設定ファイルを MSBuild プロジェクト項目 として指定します。To move settings files to the output directory, specify the settings files as MSBuild project items in the project file. サンプル アプリはその JSON アプリ設定ファイルと、次の <Content> 項目を含む hostsettings.json を移動します。The sample app moves its JSON app settings files and hostsettings.json with the following <Content> item:

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

注意

AddJsonFileAddEnvironmentVariables などの構成拡張メソッドでは、Microsoft.Extensions.Configuration.JsonMicrosoft.Extensions.Configuration.EnvironmentVariables など、追加の NuGet パッケージを必要とします。Configuration extension methods, such as AddJsonFile and AddEnvironmentVariables require additional NuGet packages, such as Microsoft.Extensions.Configuration.Json and Microsoft.Extensions.Configuration.EnvironmentVariables. アプリが Microsoft.AspNetCore.App metapackage を使用しない限り、中心となる Microsoft.Extensions.Configuration パッケージに加えて、これらのパッケージがプロジェクトに追加されます。Unless the app uses the Microsoft.AspNetCore.App metapackage, these packages must be added to the project in addition to the core Microsoft.Extensions.Configuration package. 詳細については、ASP.NET Core の構成 を参照してください。For more information, see ASP.NET Core の構成.

ConfigureServicesConfigureServices

ConfigureServices は、アプリの依存関係の挿入コンテナーにサービスを追加します。ConfigureServices adds services to the app's dependency injection container. ConfigureServices を複数回呼び出して結果を追加できます。ConfigureServices can be called multiple times with additive results.

ホストされるサービスは、IHostedService インターフェイスを実装するバックグラウンド タスク ロジックを持つクラスです。A hosted service is a class with background task logic that implements the IHostedService interface. 詳細については、ASP.NET Core でホステッド サービスを使用するバックグラウンド タスク を参照してください。For more information, see ASP.NET Core でホステッド サービスを使用するバックグラウンド タスク.

サンプル アプリでは、AddHostedService 拡張メソッドを使って、有効期間イベント LifetimeEventsHostedService と時刻指定付きバックグラウンド タスク TimedHostedService のサービスをアプリに追加します。The sample app uses the AddHostedService extension method to add a service for lifetime events, LifetimeEventsHostedService, and a timed background task, TimedHostedService, to the app:

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

ConfigureLoggingConfigureLogging

ConfigureLogging は、指定された ILoggingBuilder を構成するためのデリゲートを追加します。ConfigureLogging adds a delegate for configuring the provided ILoggingBuilder. ConfigureLogging を複数回呼び出して結果を追加できます。ConfigureLogging may be called multiple times with additive results.

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

UseConsoleLifetimeUseConsoleLifetime

UseConsoleLifetime では、Ctrl + C/SIGINT または SIGTERM がリッスンされ、StopApplication が呼び出されてシャットダウン プロセスが開始されます。UseConsoleLifetime listens for Ctrl+C/SIGINT or SIGTERM and calls StopApplication to start the shutdown process. UseConsoleLifetime は、RunAsyncWaitForShutdownAsync などの拡張機能のブロックを解除します。UseConsoleLifetime unblocks extensions such as RunAsync and WaitForShutdownAsync. Microsoft.Extensions.Hosting.Internal.ConsoleLifetime は、既定の有効期間の実装として事前に登録されています。Microsoft.Extensions.Hosting.Internal.ConsoleLifetime is pre-registered as the default lifetime implementation. 最後に登録された有効期間が使用されます。The last lifetime registered is used.

var host = new HostBuilder()
    .UseConsoleLifetime()

コンテナーの構成Container configuration

他のコンテナーの接続をサポートするため、ホストは IServiceProviderFactory<TContainerBuilder> を受け入れることができます。To support plugging in other containers, the host can accept an IServiceProviderFactory<TContainerBuilder>. ファクトリの提供は、DI コンテナーの登録の一部ではなく、具象 DI コンテナーの作成に使用されるホストの組み込みです。Providing a factory isn't part of the DI container registration but is instead a host intrinsic used to create the concrete DI container. UseServiceProviderFactory(IServiceProviderFactory<TContainerBuilder>) は、アプリのサービス プロバイダーの作成に使われる既定のファクトリをオーバーライドします。UseServiceProviderFactory(IServiceProviderFactory<TContainerBuilder>) overrides the default factory used to create the app's service provider.

カスタム コンテナーの構成は、ConfigureContainer メソッドによって管理されます。Custom container configuration is managed by the ConfigureContainer method. ConfigureContainer は、基盤のホスト API を基にしてコンテナーを構成するための、厳密に型指定されたエクスペリエンスを提供します。ConfigureContainer provides a strongly-typed experience for configuring the container on top of the underlying host API. ConfigureContainer を複数回呼び出して結果を追加できます。ConfigureContainer can be called multiple times with additive results.

アプリのサービス コンテナーを作成します。Create a service container for the app:

namespace GenericHostSample
{
    internal class ServiceContainer
    {
    }
}

サービス コンテナーのファクトリを提供します。Provide a service container factory:

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

ファクトリを使って、アプリのカスタム サービス コンテナーを構成します。Use the factory and configure the custom service container for the app:

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

機能拡張Extensibility

ホスト拡張機能は、IHostBuilder 上の拡張メソッドによって実行されます。Host extensibility is performed with extension methods on IHostBuilder. 次の例では、拡張メソッドが ASP.NET Core でホステッド サービスを使用するバックグラウンド タスク で示される TimedHostedService の例を使って IHostBuilder の実装を拡張する方法を示しています。The following example shows how an extension method extends an IHostBuilder implementation with the TimedHostedService example demonstrated in ASP.NET Core でホステッド サービスを使用するバックグラウンド タスク.

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

await host.StartAsync();

アプリは UseHostedService 拡張メソッドを確率して T に渡されたホステッド サービスを登録します。An app establishes the UseHostedService extension method to register the hosted service passed in 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>());
    }
}

ホストを管理するManage the host

IHost の実装は、サービス コンテナーに登録されている IHostedService の実装の開始と停止を行います。The IHost implementation is responsible for starting and stopping the IHostedService implementations that are registered in the service container.

実行Run

Run はアプリを実行し、ホストがシャットダウンされるまで呼び出し元のスレッドをブロックします。Run runs the app and blocks the calling thread until the host is shut down:

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

        host.Run();
    }
}

RunAsyncRunAsync

RunAsync はアプリを実行し、キャンセル トークンまたはシャットダウンがトリガーされると完了する Task を返します。RunAsync runs the app and returns a Task that completes when the cancellation token or shutdown is triggered:

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

        await host.RunAsync();
    }
}

RunConsoleAsyncRunConsoleAsync

RunConsoleAsync は、コンソールのサポートを有効にし、ホストをビルドして開始した後、Ctrl + C/SIGINT または SIGTERM がシャットダウンするのを待機します。RunConsoleAsync enables console support, builds and starts the host, and waits for Ctrl+C/SIGINT or SIGTERM to shut down.

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

        await hostBuilder.RunConsoleAsync();
    }
}

Start と StopAsyncStart and StopAsync

Start は、ホストを同期的に開始します。Start starts the host synchronously.

StopAsync は、指定されたタイムアウト内でホストの停止を試みます。StopAsync attempts to stop the host within the provided timeout.

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 と StopAsyncStartAsync and StopAsync

StartAsync がアプリを起動します。StartAsync starts the app.

StopAsync がアプリを停止します。StopAsync stops the app.

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

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

            await host.StopAsync();
        }
    }
}

WaitForShutdownWaitForShutdown

WaitForShutdown は、Microsoft.Extensions.Hosting.Internal.ConsoleLifetime (Ctrl + C/SIGINT または SIGTERM をリッスンする) などの IHostLifetime を介してトリガーされます。WaitForShutdown is triggered via the IHostLifetime, such as Microsoft.Extensions.Hosting.Internal.ConsoleLifetime (listens for Ctrl+C/SIGINT or SIGTERM). WaitForShutdownStopAsync を呼び出します。WaitForShutdown calls StopAsync.

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

        using (host)
        {
            host.Start();

            host.WaitForShutdown();
        }
    }
}

WaitForShutdownAsyncWaitForShutdownAsync

WaitForShutdownAsync が返す Task は、提供されたトークンによってシャットダウンがトリガーされると完了し、StopAsync を呼び出します。WaitForShutdownAsync returns a Task that completes when shutdown is triggered via the given token and calls StopAsync.

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

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

            await host.WaitForShutdownAsync();
        }

    }
}

外部コントロールExternal control

ホストの外部コントロールは、外部から呼び出すことができるメソッドを使って実現できます。External control of the host can be achieved using methods that can be called externally:

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 の開始時に呼び出され、これが完了するまで待機してから続行します。WaitForStartAsync is called at the start of StartAsync, which waits until it's complete before continuing. これを使って、外部イベントによって通知されるまで開始を遅らせることができます。This can be used to delay startup until signaled by an external event.

IHostingEnvironment インターフェイスIHostingEnvironment interface

IHostingEnvironment は、アプリのホスティング環境に関する情報を提供します。IHostingEnvironment provides information about the app's hosting environment. プロパティと拡張メソッドを使用するには、コンストラクターの挿入を使用して IHostingEnvironment を取得します。Use constructor injection to obtain the IHostingEnvironment in order to use its properties and extension methods:

public class MyClass
{
    private readonly IHostingEnvironment _env;

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

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

詳細については、ASP.NET Core で複数の環境を使用する を参照してください。For more information, see ASP.NET Core で複数の環境を使用する.

IApplicationLifetime インターフェイスIApplicationLifetime interface

IApplicationLifetime は、正常なシャットダウンの要求など、起動後とシャットダウンのアクティビティに対応します。IApplicationLifetime allows for post-startup and shutdown activities, including graceful shutdown requests. インターフェイスの 3 つのプロパティは、起動とシャットダウン イベントを定義する Action メソッドを登録するために使用されるキャンセル トークンです。Three properties on the interface are cancellation tokens used to register Action methods that define startup and shutdown events.

キャンセル トークンCancellation Token トリガーのタイミングTriggered when…
ApplicationStarted ホストが完全に起動されたとき。The host has fully started.
ApplicationStopped ホストが正常なシャットダウンを完了しているとき。The host is completing a graceful shutdown. すべての要求を処理する必要があります。All requests should be processed. このイベントが完了するまで、シャットダウンはブロックされます。Shutdown blocks until this event completes.
ApplicationStopping ホストが正常なシャットダウンを行っているとき。The host is performing a graceful shutdown. 要求がまだ処理されている可能性がある場合。Requests may still be processing. このイベントが完了するまで、シャットダウンはブロックされます。Shutdown blocks until this event completes.

コンストラクターは任意のクラスに IApplicationLifetime サービスを挿入します。Constructor-inject the IApplicationLifetime service into any class. サンプル アプリは、LifetimeEventsHostedService クラス (IHostedService の実装) へのコンストラクターの挿入を使って、イベントを登録します。The sample app uses constructor injection into a LifetimeEventsHostedService class (an IHostedService implementation) to register the events.

LifetimeEventsHostedService.cs: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 は、アプリの終了を要求します。StopApplication requests termination of the app. 以下のクラスは、クラスの Shutdown メソッドが呼び出されると、StopApplication を使ってアプリを正常にシャットダウンします。The following class uses StopApplication to gracefully shut down an app when the class's Shutdown method is called:

public class MyClass
{
    private readonly IApplicationLifetime _appLifetime;

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

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

その他の技術情報Additional resources