ASP.NET Core の .NET 汎用ホスト

この記事では、ASP.NET Core での .NET 汎用ホストの使用方法について説明します。

ASP.NET Coreテンプレートでは、WebApplicationBuilder と WebApplication が作成されます。これらは、Startup クラスを使用せずに Web アプリケーションを構成して実行するための、効率的な方法を提供するものです。 WebApplicationBuilder と WebApplication の詳細については、「WebApplicationBuilder」を参照してください。

コンソール アプリで .NET 汎用ホストを使用する方法の詳細については、「.NET 汎用ホスト」を参照してください。

ホストの定義

"ホスト" とは、以下のようなアプリのリソースをカプセル化するオブジェクトです:

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

ホストが起動すると、サービス コンテナーのホステッド サービスのコレクションに登録されている IHostedService の各実装で IHostedService.StartAsync が呼び出されます。 Web アプリでは、IHostedService 実装の 1 つが IHostedServiceを起動する Web サービスとなります。

アプリの相互依存するすべてのリソースを 1 つのオブジェクトに含めると、アプリの起動と正常なシャットダウンを制御できます。

ホストを設定する

通常、ホストは Program.cs 内のコードによって構成、ビルド、および実行されます。 次のコードを実行すると、DI コンテナーに追加された IHostedService の実装を使用して、ホストが作成されます。

await Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        services.AddHostedService<SampleHostedService>();
    })
    .Build()
    .RunAsync();

HTTP ワークロードの場合は、CreateDefaultBuilder の後に ConfigureWebHostDefaults を呼び出します。

await Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseStartup<Startup>();
    })
    .Build()
    .RunAsync();

既定の builder 設定

CreateDefaultBuilder メソッド:

• コンテンツ ルートを、GetCurrentDirectory によって返されるパスに設定します。
• 次から ホスト構成を読み込みます。
  • プレフィックス DOTNET_ が付いた環境変数。
  • コマンド ライン引数。
• 次からアプリの構成を読み込みます。
  • appsettings.json。
  • appsettings.{Environment}.json。
  • Development 環境でアプリが実行される場合に使用されるユーザー シークレット。
  • 環境変数。
  • コマンド ライン引数。
• 次のログ プロバイダーを追加します。
  • コンソール
  • デバッグ
  • EventSource
  • イベント ログ (Windows で実行されている場合のみ)
• 環境が [開発] になっている場合は、スコープの検証と依存関係の検証を有効にします。

ConfigureWebHostDefaults メソッド:

• プレフィックス ASPNETCORE_ が付いた環境変数からホスト構成を読み込みます。
• Kestrel サーバーを Web サーバーとして設定し、アプリのホスティング構成プロバイダーを使用してそれを構成します。 Kestrel サーバーの既定のオプションについては、「Kestrel」を参照してください。
• Host Filtering middleware を追加します。
• ASPNETCORE_FORWARDEDHEADERS_ENABLED が true の場合、Forwarded Headers Middleware を追加します。
• IIS 統合を有効にします。 IIS の既定のオプションについては、「IIS を使用した Windows での ASP.NET Core のホスト」を参照してください。

この記事で後述する「すべての種類のアプリの設定」および「Web アプリの設定」セクションに、既定のビルダー設定をオーバーライドする方法を示します。

フレームワークが提供するサービス

以下のサービスは、自動的に登録されます。

• IHostApplicationLifetime
• IHostLifetime
• IHostEnvironment / IWebHostEnvironment

フレームワークによって提供されるサービスの詳細については、「ASP.NET Core での依存関係の挿入」を参照してください。

IHostApplicationLifetime

起動後タスクとグレースフル シャットダウン タスクを処理するために IHostApplicationLifetime (旧称 IApplicationLifetime) サービスを任意のクラスに注入します。 インターフェイス上の 3 つのプロパティは、アプリの起動およびアプリの停止のイベント ハンドラー メソッドを登録するために使用されるキャンセル トークンです。 このインターフェイスには、アプリが正常なシャットダウンを要求できるようにするための、StopApplication メソッドも含まれています。

正常なシャットダウンを行っている場合、ホストは次の操作を実行します。

• ApplicationStopping イベント ハンドラーをトリガーします。これにより、シャットダウン プロセスが開始される前にアプリがロジックを実行できるようになります。
• サーバーを停止し、新しい接続を無効にします。 サーバーは、シャットダウンのタイムアウトに達するまで、既存の接続での要求が完了するのを待機します。 サーバーは、既存の接続でのその後の要求に対し、接続終了ヘッダーを送信します。
• ApplicationStopped イベント ハンドラーをトリガーします。これにより、アプリケーションがシャットダウンされた後に、アプリがロジックを実行できるようになります。

次の例は、IHostApplicationLifetime イベント ハンドラーを登録する IHostedService の実装です。

public class HostApplicationLifetimeEventsHostedService : IHostedService
{
    private readonly IHostApplicationLifetime _hostApplicationLifetime;

    public HostApplicationLifetimeEventsHostedService(
        IHostApplicationLifetime hostApplicationLifetime)
        => _hostApplicationLifetime = hostApplicationLifetime;

    public Task StartAsync(CancellationToken cancellationToken)
    {
        _hostApplicationLifetime.ApplicationStarted.Register(OnStarted);
        _hostApplicationLifetime.ApplicationStopping.Register(OnStopping);
        _hostApplicationLifetime.ApplicationStopped.Register(OnStopped);

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
        => Task.CompletedTask;

    private void OnStarted()
    {
        // ...
    }

    private void OnStopping()
    {
        // ...
    }

    private void OnStopped()
    {
        // ...
    }
}

IHostLifetime

IHostLifetime 実装では、ホストを開始および停止するタイミングが制御されます。 登録されている最後の実装が使用されます。

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

• Ctrl+C/SIGINT (Windows)、⌘+C (macOS)、または SIGTERM をリッスンし、StopApplication を呼び出して、シャットダウン プロセスを開始します。
• RunAsync や WaitForShutdownAsync などの拡張機能のブロックを解除します。

IHostEnvironment

次の設定に関する情報を取得するため、クラスに IHostEnvironment サービスを注入します。

• ApplicationName
• EnvironmentName
• ContentRootPath

Web アプリで IWebHostEnvironment インターフェイスを実装します。これにより、IHostEnvironment が継承され、IWebHostEnvironment が追加されます。

ホストの構成

ホストの構成は、IHostEnvironment 実装のプロパティで使用されます。

ホスト構成は、ConfigureAppConfiguration 内の HostBuilderContext.Configuration から使用できます。 ConfigureAppConfiguration の後、HostBuilderContext.Configuration はアプリの構成に置き換えられます。

ホストの構成を追加するには、IHostBuilder 上で ConfigureHostConfiguration を呼び出します。 ConfigureHostConfiguration を複数回呼び出して結果を追加できます。 ホストは、指定されたキーで最後に値を設定したオプションを使用します。

プレフィックス DOTNET_ を持つ環境変数プロバイダーとコマンドライン引数が、CreateDefaultBuilder によって組み込まれます。 Web アプリの場合は、プレフィックス ASPNETCORE_ を持つ環境変数プロバイダーが追加されます。 環境変数が読み取られると、プレフィックスは削除されます。 たとえば、ASPNETCORE_ENVIRONMENT の環境変数の値が environment キーのホスト構成値になります。

次の例では、ホストの構成を作成します。

Host.CreateDefaultBuilder(args)
    .ConfigureHostConfiguration(hostConfig =>
    {
        hostConfig.SetBasePath(Directory.GetCurrentDirectory());
        hostConfig.AddJsonFile("hostsettings.json", optional: true);
        hostConfig.AddEnvironmentVariables(prefix: "PREFIX_");
        hostConfig.AddCommandLine(args);
    });

アプリの構成

アプリの構成は、IHostBuilder 上で ConfigureAppConfiguration を呼び出すことで作成されます。 ConfigureAppConfiguration を複数回呼び出して結果を追加できます。 アプリは、指定されたキーで最後に値を設定したオプションを使用します。

ConfigureAppConfiguration によって作成された構成は、HostBuilderContext.Configuration で、以降の操作のために、かつ DI からのサービスとして利用できます。 ホストの構成はアプリの構成にも追加されます。

詳細については、「ASP.NET Core の構成」を参照してください。

すべての種類のアプリの設定

このセクションでは、HTTP のワークロードと HTTP 以外のワークロードの両方に適用されるホストの設定を一覧します。 既定では、これらの設定を構成するのに使用する環境変数には、プレフィックスとして DOTNET_ または ASPNETCORE_ を付けることができます。これらは、以下の設定の一覧で、{PREFIX_} プレースホルダーとして示されています。 詳細については、「既定の builder 設定」および「構成: 環境変数」を参照してください。

ApplicationName

IHostEnvironment.ApplicationName プロパティは、ホストの構築時にホストの構成から設定されます。

キー: applicationName
型: string
既定: アプリのエントリ ポイントを含むアセンブリの名前。
環境変数: {PREFIX_}APPLICATIONNAME

この値を設定するには、環境変数を使用します。

ContentRoot

IHostEnvironment.ContentRootPath プロパティでは、ホストがコンテンツ ファイルの検索を開始する場所を決定します。 パスが存在しない場合は、ホストを起動できません。

キー: contentRoot
型: string
既定: アプリ アセンブリが存在するフォルダー。
環境変数: {PREFIX_}CONTENTROOT

この値を設定するには、環境変数を使用するか、または IHostBuilder 上で UseContentRoot を呼び出します。

Host.CreateDefaultBuilder(args)
    .UseContentRoot("/path/to/content/root")
    // ...

詳細については次を参照してください:

• 基礎: コンテンツ ルート
• WebRoot

EnvironmentName

IHostEnvironment.EnvironmentName プロパティは、任意の値に設定できます。 フレームワークで定義された値には Development、Staging、Production が含まれます。 値は大文字と小文字が区別されません。

キー: environment
型: string
規定: Production
環境変数: {PREFIX_}ENVIRONMENT

この値を設定するには、環境変数を使用するか、または IHostBuilder 上で UseEnvironment を呼び出します。

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

ShutdownTimeout

HostOptions.ShutdownTimeout によって StopAsync のタイムアウトが設定されます。 既定値は 30 秒です。 タイムアウト期間中、ホストでは次のことが行われます。

• IHostApplicationLifetime.ApplicationStopping をトリガーします。
• ホステッド サービスの停止を試み、停止に失敗したサービスのエラーをログに記録します。

すべてのホステッド サービスが停止する前にタイムアウト時間が切れた場合、残っているアクティブなサービスはアプリのシャットダウン時に停止します。 処理が完了していない場合でも、サービスは停止します。 サービスが停止するまでにさらに時間が必要な場合は、タイムアウト値を増やします。

キー: shutdownTimeoutSeconds
型: int
既定値: 30 秒
環境変数: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

この値を設定するには、環境変数を使用するか、または HostOptions を構成します。 次の例では、タイムアウトを 20 秒に設定します。

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

変更時にアプリ構成の再度読み込みを無効にする

既定では、appsettings.json と appsettings.{Environment}.json は、ファイルの変更時に再度読み込まれます。 ASP.NET Core 5.0 以降でこの再度読み込み動作を無効にするには、hostBuilder:reloadConfigOnChange キーを false に設定します。

キー: hostBuilder:reloadConfigOnChange
型: bool (true または false)
規定: true
コマンドライン引数: hostBuilder:reloadConfigOnChange
環境変数: {PREFIX_}hostBuilder:reloadConfigOnChange

警告

コロン (:) の区切り記号は、すべてのプラットフォームの環境変数階層キーには対応していません。 詳細については、「環境変数」を参照してください。

Web アプリの設定

一部のホスト設定は、HTTP のワークロードにのみに適用されます。 既定では、これらの設定を構成するのに使用する環境変数には、プレフィックスとして DOTNET_ または ASPNETCORE_ を付けることができます。これらは、以下の設定の一覧で、{PREFIX_} プレースホルダーとして示されています。

IWebHostBuilder 上の拡張メソッドはこれらの設定で使用できます。 次の例に示すように、拡張メソッドを呼び出す方法を示すコード サンプルでは webBuilder が IWebHostBuilder のインスタンスであると想定しています。

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

CaptureStartupErrors

false の場合、起動時にエラーが発生するとホストが終了します。 true の場合、ホストは起動時に例外をキャプチャして、サーバーを起動しようとします。

キー: captureStartupErrors
型: bool (true/1 または false/0)
既定値: アプリが IIS の背後で Kestrel を使用して実行されている場合 (既定値は true) を除き、既定では false に設定されます。
環境変数: {PREFIX_}CAPTURESTARTUPERRORS

この値を設定するには、構成を使用するか、または CaptureStartupErrors を呼び出します。

webBuilder.CaptureStartupErrors(true);

DetailedErrors

有効にされている場合、または環境が Development である場合、アプリによって詳細なエラーがキャプチャされます。

キー: detailedErrors
型: bool (true/1 または false/0)
規定: false
環境変数: {PREFIX_}DETAILEDERRORS

この値を設定するには、構成を使用するか、または UseSetting を呼び出します。

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

HostingStartupAssemblies

起動時に読み込むホスティング スタートアップ アセンブリのセミコロンで区切られた文字列。 構成値は既定で空の文字列に設定されますが、ホスティング スタートアップ アセンブリには常にアプリのアセンブリが含まれます。 ホスティング スタートアップ アセンブリが提供されている場合、アプリが起動中に共通サービスをビルドしたときに読み込むためにアプリのアセンブリに追加されます。

キー: hostingStartupAssemblies
型: string
既定:空の文字列
環境変数: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

この値を設定するには、構成を使用するか、または UseSetting を呼び出します。

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

HostingStartupExcludeAssemblies

起動時に除外するホスティング スタートアップ アセンブリのセミコロン区切り文字列。

キー: hostingStartupExcludeAssemblies
型: string
既定:空の文字列
環境変数: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

この値を設定するには、構成を使用するか、または UseSetting を呼び出します。

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

HTTPS_Port

HTTPS 以外の接続を取得する場合は、リダイレクト先の HTTPS ポートを設定します。 HTTPS の適用に使用されます。 この設定では、指定したポートでサーバーがリッスンすることはありません。 つまり、誤って未使用のポートにリクエストをリダイレクトする可能性があります。

キー: https_port型: string
既定:既定値は設定されていません。
環境変数: {PREFIX_}HTTPS_PORT

この値を設定するには、構成を使用するか、または UseSetting を呼び出します。

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

HTTPS_Ports

HTTPS 接続をリッスンするポート。

キー: https_ports
型: string
既定:既定値は設定されていません。
環境変数: {PREFIX_}HTTPS_PORTS

この値を設定するには、構成を使用するか、または UseSetting を呼び出します。

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

PreferHostingUrls

IServer の実装で構成されている URL ではなく、IWebHostBuilder で構成されている URL でホストがリッスンするかどうかを示します。

キー: preferHostingUrls
型: bool (true/1 または false/0)
規定: false
環境変数: {PREFIX_}PREFERHOSTINGURLS

この値を設定するには、環境変数を使用するか、または PreferHostingUrls を呼び出します。

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

アプリのアセンブリで構成されているホスティング スタートアップ アセンブリを含む、ホスティング スタートアップ アセンブリの自動読み込みを回避します。 詳細については、「ASP.NET Core でホスティング スタートアップ アセンブリを使用する」を参照してください。

キー: preventHostingStartup
型: bool (true/1 または false/0)
規定: false
環境変数: {PREFIX_}PREVENTHOSTINGSTARTUP

この値を設定するには、環境変数を使用するか、または UseSetting を呼び出します。

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

StartupAssembly

Startup クラスを検索するアセンブリ。

キー: startupAssembly
型: string
既定:アプリのアセンブリ
環境変数: {PREFIX_}STARTUPASSEMBLY

この値を設定するには、環境変数を使用するか、または UseStartup を呼び出します。 UseStartup は、アセンブリ名 (string) または型 (TStartup) を取ることができます。 複数の UseStartup メソッドが呼び出された場合は、最後のメソッドが優先されます。

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

SuppressStatusMessages

有効にすると、スタートアップ ステータス メッセージのホスティングが抑制されます。

キー: suppressStatusMessages
型: bool (true/1 または false/0)
規定: false
環境変数: {PREFIX_}SUPPRESSSTATUSMESSAGES

この値を設定するには、構成を使用するか、または UseSetting を呼び出します。

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

URL

サーバーが要求をリッスンする必要があるポートとプロトコルを含む IP アドレスまたはホスト アドレスを示すセミコロンで区切られたリスト。 たとえば、http://localhost:123 のようにします。 "*" を使用し、サーバーが指定されたポートとプロトコル (http://*:5000 など) を使用して IP アドレスまたはホスト名に関する要求をリッスンする必要があることを示します。 プロトコル (http:// または https://) は各 URL に含める必要があります。 サポートされている形式はサーバー間で異なります。

キー: urls
型: string
既定値: http://localhost:5000 および https://localhost:5001
環境変数: {PREFIX_}URLS

この値を設定するには、環境変数を使用するか、または UseUrls を呼び出します。

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

Kestrel には独自のエンドポイント構成 API があります。 詳しくは、「ASP.NET Core Kestrel Web サーバーのエンドポイントを構成する」をご覧ください。

WebRoot

IWebHostEnvironment.WebRootPath プロパティでは、アプリの静的アセットへの相対パスが決定されます。 パスが存在しない場合は、no-op ファイル プロバイダーが使用されます。

キー: webroot
型: string
既定:既定値は、wwwroot です。 {content root}/wwwroot へのパスが存在する必要があります。
環境変数: {PREFIX_}WEBROOT

この値を設定するには、環境変数を使用するか、または IWebHostBuilder 上で UseWebRoot を呼び出します。

webBuilder.UseWebRoot("public");

詳細については次を参照してください:

• 基礎: Web ルート
• ContentRoot

ホストの有効期間を管理する

組み込みの IHost 実装でメソッドを呼び出して、アプリの開始および停止を行います。 これらのメソッドは、サービス コンテナーに登録されているすべての IHostedService 実装に影響を与えます。

Run* メソッドと Start* メソッドの違いは、Run* メソッドでは終了する前にホストが完了するのを待機するのに対し、Start* メソッドの方は即座に終了する点です。 通常、Run* メソッドはコンソール アプリで使用されますが、Start* メソッドは実行時間の長いサービスで使用されます。

[ファイル名を指定して実行]

Run はアプリを実行し、ホストがシャットダウンされるまで呼び出し元のスレッドをブロックします。

RunAsync

RunAsync はアプリを実行し、キャンセル トークンまたはシャットダウンがトリガーされると完了する Task を返します。

RunConsoleAsync

RunConsoleAsync は、コンソールのサポートを有効にし、ホストをビルドして開始した後、Ctrl+C/SIGINT (Windows)、⌘+C (macOS)、または SIGTERM がシャットダウンするのを待機します。

[開始]

Start は、ホストを同期的に開始します。

StartAsync

StartAsync ではホストが開始され、キャンセル トークンまたはシャットダウンがトリガーされると完了する Task が返されます。

WaitForStartAsync は StartAsync の開始時に呼び出され、これが完了するまで待機してから続行します。 このメソッドを使って、外部イベントによって通知されるまで開始を遅らせることができます。

StopAsync

StopAsync は、指定されたタイムアウト内でホストの停止を試みます。

WaitForShutdown

Ctrl+C/SIGINT (Windows)、⌘+C (macOS)、または SIGTERM を介するなどして IHostLifetime によってシャットダウンがトリガーされるまで、WaitForShutdown では呼び出し側スレッドがブロックされます。

WaitForShutdownAsync

WaitForShutdownAsync が返す Task は、提供されたトークンによってシャットダウンがトリガーされると完了し、StopAsync を呼び出します。

その他の技術情報

• ASP.NET Core でホステッド サービスを使用するバックグラウンド タスク
• 汎用ホスト ソースへの GitHub リンク

  Note

  通常、.NET 参照ソースへのドキュメント リンクを使用すると、リポジトリの既定のブランチが読み込まれます。このブランチは、.NET の次回リリースに向けて行われている現在の開発を表します。 特定のリリースのタグを選択するには、[Switch branches or tags](ブランチまたはタグの切り替え) ドロップダウン リストを使います。 詳細については、「ASP.NET Core ソース コードのバージョン タグを選択する方法」 (dotnet/AspNetCore.Docs #26205) を参照してください。