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

作成者: Luke LathamBy Luke Latham

.NET Core アプリはホストを構成して起動します。.NET Core apps configure and launch a host. ホストはアプリの起動と有効期間の管理を担当します。The host is responsible for app startup and lifetime management. このトピックでは、HTTP 要求の処理を行わないアプリをホストするのに便利な、ASP.NET Core の汎用ホスト (HostBuilder) について説明します。This topic covers the ASP.NET Core Generic Host (HostBuilder), which is useful for hosting apps that don't process HTTP requests. Web ホスト (WebHostBuilder) の対象範囲については、ASP.NET Core の Web ホスト を参照してください。For coverage of the Web Host (WebHostBuilder), see ASP.NET Core の Web ホスト.

汎用ホストの目的は、Web ホスト API から HTTP パイプラインを切り離して、多様なホスト シナリオを有効にすることです。The goal of the 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 the Generic Host benefit from cross-cutting capabilities, such as configuration, dependency injection (DI), and logging.

汎用ホストは ASP.NET Core 2.1 の新機能であり、Web ホスティングのシナリオには適していません。The 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 として機能するようになります。The Generic Host is under development to replace the 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>")

環境Environment

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

キー: 環境Key: environment
: 文字列Type: string
既定値: ProductionDefault: 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.

ホストの構成は自動的にアプリの構成に送られます (ConfigureAppConfiguration とアプリの残りの部分)。Host configuration automatically flows to app configuration (ConfigureAppConfiguration and the rest of the app).

既定ではプロバイダーが含まれていません。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>

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. ConsoleLifetime は、既定の有効期間の実装として事前に登録されています。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 は、ConsoleLifetime (Ctrl+C/SIGINT or SIGTERM をリッスンする) などの IHostLifetime を介してトリガーされます。WaitForShutdown is triggered via the IHostLifetime, such as 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