ASP.NET Core の .NET 汎用ホスト
Note
これは、この記事の最新バージョンではありません。 現在のリリースについては、この記事の .NET 8 バージョンを参照してください。
警告
このバージョンの ASP.NET Core はサポート対象から除外されました。 詳細については、「.NET および .NET Core サポート ポリシー」を参照してください。 現在のリリースについては、この記事の .NET 8 バージョンを参照してください。
重要
この情報はリリース前の製品に関する事項であり、正式版がリリースされるまでに大幅に変更される可能性があります。 Microsoft はここに示されている情報について、明示か黙示かを問わず、一切保証しません。
現在のリリースについては、この記事の .NET 8 バージョンを参照してください。
この記事では、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 アプリの設定」セクションに、既定のビルダー設定をオーバーライドする方法を示します。
フレームワークが提供するサービス
以下のサービスは、自動的に登録されます。
フレームワークによって提供されるサービスの詳細については、「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 サービスを注入します。
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")
// ...
詳細については次を参照してください:
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_port
型: string
既定:既定値は設定されていません。
環境変数: {PREFIX_}HTTPS_PORT
この値を設定するには、構成を使用するか、または UseSetting
を呼び出します。
webBuilder.UseSetting("https_port", "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");
詳細については次を参照してください:
ホストの有効期間を管理する
組み込みの 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 テンプレートでは、.NET Core の汎用ホスト (HostBuilder) が作成されます。
この記事では、ASP.NET Core での .NET 汎用ホストの使用方法について説明します。 コンソール アプリで .NET 汎用ホストを使用する方法の詳細については、「.NET 汎用ホスト」を参照してください。
ホストの定義
"ホスト" とは、以下のようなアプリのリソースをカプセル化するオブジェクトです:
- 依存関係の挿入 (DI)
- ログの記録
- 構成
IHostedService
の実装
ホストが起動すると、サービス コンテナーのホステッド サービスのコレクションに登録されている IHostedService の各実装で IHostedService.StartAsync が呼び出されます。 Web アプリでは、IHostedService
実装の 1 つが IHostedService
を起動する Web サービスとなります。
アプリの相互依存するすべてのリソースを 1 つのオブジェクトに含める主な理由は、アプリの起動と正常なシャットダウンの制御の有効期間の管理のためです。
ホストを設定する
ホストは通常、Program
クラス内のコードによって構成、ビルド、および実行されます。 Main
メソッド:
CreateHostBuilder
メソッドを呼び出して、builder オブジェクトを作成および構成します。- builder オブジェクト上で
Build
メソッドとRun
メソッドを呼び出します。
ASP.NET Core の web テンプレートでは、ホストを作成するために、次のコードが生成されます。
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}
次のコードを実行すると、DI コンテナーに追加された IHostedService
の実装を使用して、非 HTTP ワークロードが作成されます。
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureServices((hostContext, services) =>
{
services.AddHostedService<Worker>();
});
}
HTTP ワークロードの場合、Main
メソッドは同じですが、CreateHostBuilder
によって ConfigureWebHostDefaults
が呼び出されます。
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
Entity Framework Core がアプリで使用されている場合は、CreateHostBuilder
メソッドの名前またはシグネチャを変更しないでください。 Entity Framework Core ツール では、アプリを実行することなくホストを構成する CreateHostBuilder
メソッドを検出することが想定されています。 詳細については、「デザイン時 DbContext 作成」をご覧ください。
既定の 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 アプリの設定」セクションに、既定のビルダー設定をオーバーライドする方法を示します。
フレームワークが提供するサービス
以下のサービスは、自動的に登録されます。
フレームワークによって提供されるサービスの詳細については、「ASP.NET Core での依存関係の挿入」を参照してください。
IHostApplicationLifetime
起動後タスクとグレースフル シャットダウン タスクを処理するために IHostApplicationLifetime (旧称 IApplicationLifetime
) サービスを任意のクラスに注入します。 インターフェイス上の 3 つのプロパティは、アプリの起動およびアプリの停止のイベント ハンドラー メソッドを登録するために使用されるキャンセル トークンです。 インターフェイスには StopApplication
メソッドも含まれています。
次の例は、IHostApplicationLifetime
イベントを登録する IHostedService
の実装です。
internal class LifetimeEventsHostedService : IHostedService
{
private readonly ILogger _logger;
private readonly IHostApplicationLifetime _appLifetime;
public LifetimeEventsHostedService(
ILogger<LifetimeEventsHostedService> logger,
IHostApplicationLifetime appLifetime)
{
_logger = logger;
_appLifetime = appLifetime;
}
public Task StartAsync(CancellationToken cancellationToken)
{
_appLifetime.ApplicationStarted.Register(OnStarted);
_appLifetime.ApplicationStopping.Register(OnStopping);
_appLifetime.ApplicationStopped.Register(OnStopped);
return Task.CompletedTask;
}
public Task StopAsync(CancellationToken cancellationToken)
{
return Task.CompletedTask;
}
private void OnStarted()
{
_logger.LogInformation("OnStarted has been called.");
// Perform post-startup activities here
}
private void OnStopping()
{
_logger.LogInformation("OnStopping has been called.");
// Perform on-stopping activities here
}
private void OnStopped()
{
_logger.LogInformation("OnStopped has been called.");
// Perform post-stopped activities here
}
}
IHostLifetime
IHostLifetime 実装では、ホストを開始および停止するタイミングが制御されます。 登録されている最後の実装が使用されます。
Microsoft.Extensions.Hosting.Internal.ConsoleLifetime
は、既定の IHostLifetime
実装です。 ConsoleLifetime
:
- Ctrl+C/SIGINT (Windows)、⌘+C (macOS)、または SIGTERM をリッスンし、StopApplication を呼び出して、シャットダウン プロセスを開始します。
- RunAsync や WaitForShutdownAsync などの拡張機能のブロックを解除します。
IHostEnvironment
次の設定に関する情報を取得するため、クラスに IHostEnvironment サービスを注入します。
Web アプリで IWebHostEnvironment
インターフェイスを実装します。これにより、IHostEnvironment
が継承され、IWebHostEnvironment
が追加されます。
ホストの構成
ホストの構成は、IHostEnvironment 実装のプロパティで使用されます。
ホスト構成は、ConfigureAppConfiguration 内の HostBuilderContext.Configuration から使用できます。 ConfigureAppConfiguration
の後、HostBuilderContext.Configuration
はアプリの構成に置き換えられます。
ホストの構成を追加するには、IHostBuilder
上で ConfigureHostConfiguration を呼び出します。 ConfigureHostConfiguration
を複数回呼び出して結果を追加できます。 ホストは、指定されたキーで最後に値を設定したオプションを使用します。
プレフィックス DOTNET_
を持つ環境変数プロバイダーとコマンドライン引数が、CreateDefaultBuilder
によって組み込まれます。 Web アプリの場合は、プレフィックス ASPNETCORE_
を持つ環境変数プロバイダーが追加されます。 環境変数が読み取られると、プレフィックスは削除されます。 たとえば、ASPNETCORE_ENVIRONMENT
の環境変数の値が environment
キーのホスト構成値になります。
次の例では、ホストの構成を作成します。
// using Microsoft.Extensions.Configuration;
Host.CreateDefaultBuilder(args)
.ConfigureHostConfiguration(configHost =>
{
configHost.SetBasePath(Directory.GetCurrentDirectory());
configHost.AddJsonFile("hostsettings.json", optional: true);
configHost.AddEnvironmentVariables(prefix: "PREFIX_");
configHost.AddCommandLine(args);
});
アプリの構成
アプリの構成は、IHostBuilder
上で 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("c:\\content-root")
//...
詳細については次を参照してください:
EnvironmentName
IHostEnvironment.EnvironmentName プロパティは、任意の値に設定できます。 フレームワークで定義された値には Development
、Staging
、Production
が含まれます。 値は大文字と小文字が区別されません。
キー: environment
型: string
規定: Production
環境変数: {PREFIX_}ENVIRONMENT
この値を設定するには、環境変数を使用するか、または IHostBuilder
上で UseEnvironment
を呼び出します。
Host.CreateDefaultBuilder(args)
.UseEnvironment("Development")
//...
ShutdownTimeout
HostOptions.ShutdownTimeout によって StopAsync のタイムアウトが設定されます。 既定値は 5 秒です。 タイムアウト期間中、ホストでは次のことが行われます。
- IHostApplicationLifetime.ApplicationStopping をトリガーします。
- ホステッド サービスの停止を試み、停止に失敗したサービスのエラーをログに記録します。
すべてのホステッド サービスが停止する前にタイムアウト時間が切れた場合、残っているアクティブなサービスはアプリのシャットダウン時に停止します。 処理が完了していない場合でも、サービスは停止します。 サービスが停止するまでにさらに時間が必要な場合は、タイムアウト値を増やします。
キー: shutdownTimeoutSeconds
型: int
既定:5 秒
環境変数: {PREFIX_}SHUTDOWNTIMEOUTSECONDS
この値を設定するには、環境変数を使用するか、または HostOptions
を構成します。 次の例では、タイムアウトを 20 秒に設定します。
Host.CreateDefaultBuilder(args)
.ConfigureServices((hostContext, services) =>
{
services.Configure<HostOptions>(option =>
{
option.ShutdownTimeout = System.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
のインスタンスであると想定しています。
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.CaptureStartupErrors(true);
webBuilder.UseStartup<Startup>();
});
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_port
型: string
既定:既定値は設定されていません。
環境変数: {PREFIX_}HTTPS_PORT
この値を設定するには、構成を使用するか、または UseSetting
を呼び出します。
webBuilder.UseSetting("https_port", "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");
詳細については次を参照してください:
ホストの有効期間を管理する
組み込みの 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 を呼び出します。
外部コントロール
ホストの有効期間の直接コントロールは、外部から呼び出すことができるメソッドを使って実現できます。
public class Program
{
private IHost _host;
public Program()
{
_host = new HostBuilder()
.Build();
}
public async Task StartAsync()
{
_host.StartAsync();
}
public async Task StopAsync()
{
using (_host)
{
await _host.StopAsync(TimeSpan.FromSeconds(5));
}
}
}
ASP.NET Core テンプレートでは、.NET Core の汎用ホスト (HostBuilder) が作成されます。
この記事では、ASP.NET Core での .NET 汎用ホストの使用方法について説明します。 コンソール アプリで .NET 汎用ホストを使用する方法の詳細については、「.NET 汎用ホスト」を参照してください。
ホストの定義
"ホスト" とは、以下のようなアプリのリソースをカプセル化するオブジェクトです:
- 依存関係の挿入 (DI)
- ログの記録
- 構成
IHostedService
の実装
ホストが起動すると、サービス コンテナーのホステッド サービスのコレクションに登録されている IHostedService の各実装で IHostedService.StartAsync が呼び出されます。 Web アプリでは、IHostedService
実装の 1 つが IHostedService
を起動する Web サービスとなります。
アプリの相互依存するすべてのリソースを 1 つのオブジェクトに含める主な理由は、アプリの起動と正常なシャットダウンの制御の有効期間の管理のためです。
ホストを設定する
ホストは通常、Program
クラス内のコードによって構成、ビルド、および実行されます。 Main
メソッド:
CreateHostBuilder
メソッドを呼び出して、builder オブジェクトを作成および構成します。- builder オブジェクト上で
Build
メソッドとRun
メソッドを呼び出します。
ASP.NET Core の web テンプレートでは、汎用ホストを作成するために次のコードが生成されます。
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}
次のコードでは、HTTP 以外のワークロードを使用して、汎用ホストを作成します。 次のコードでは、IHostedService
の実装が DI コンテナーに追加されます。
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureServices((hostContext, services) =>
{
services.AddHostedService<Worker>();
});
}
HTTP ワークロードの場合、Main
メソッドは同じですが、CreateHostBuilder
によって ConfigureWebHostDefaults
が呼び出されます。
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
上記のコードは、ASP.NET Core テンプレートによって生成されます。
Entity Framework Core がアプリで使用されている場合は、CreateHostBuilder
メソッドの名前またはシグネチャを変更しないでください。 Entity Framework Core ツール では、アプリを実行することなくホストを構成する CreateHostBuilder
メソッドを検出することが想定されています。 詳細については、「デザイン時 DbContext 作成」をご覧ください。
既定の builder 設定
CreateDefaultBuilder メソッド:
- コンテンツ ルートを、GetCurrentDirectory によって返されるパスに設定します。
- 次から ホスト構成を読み込みます。
- プレフィックス
DOTNET_
が付いた環境変数。 - コマンド ライン引数。
- プレフィックス
- 次からアプリの構成を読み込みます。
appsettings.json
。appsettings.{Environment}.json
。Development
環境でアプリが実行される場合に使用されるユーザー シークレット。- 環境変数。
- コマンド ライン引数。
- 次のログ プロバイダーを追加します。
- コンソール
- デバッグ
- EventSource
- イベント ログ (Windows で実行されている場合のみ)
- 環境が [開発] になっている場合は、スコープの検証と依存関係の検証を有効にします。
ConfigureWebHostDefaults
メソッド:
- プレフィックス
ASPNETCORE_
が付いた環境変数からホスト構成を読み込みます。 - Kestrel サーバーを Web サーバーとして設定し、アプリのホスティング構成プロバイダーを使用してそれを構成します。 Kestrel サーバーの既定のオプションについては、「ASP.NET Core の Kestrel Web サーバー」を参照してください。
- Host Filtering middleware を追加します。
ASPNETCORE_FORWARDEDHEADERS_ENABLED
がtrue
の場合、Forwarded Headers Middleware を追加します。- IIS 統合を有効にします。 IIS の既定のオプションについては、「IIS を使用した Windows での ASP.NET Core のホスト」を参照してください。
この記事で後述する「すべての種類のアプリの設定」および「Web アプリの設定」セクションに、既定のビルダー設定をオーバーライドする方法を示します。
フレームワークが提供するサービス
以下のサービスは、自動的に登録されます。
フレームワークによって提供されるサービスの詳細については、「ASP.NET Core での依存関係の挿入」を参照してください。
IHostApplicationLifetime
起動後タスクとグレースフル シャットダウン タスクを処理するために IHostApplicationLifetime (旧称 IApplicationLifetime
) サービスを任意のクラスに注入します。 インターフェイス上の 3 つのプロパティは、アプリの起動およびアプリの停止のイベント ハンドラー メソッドを登録するために使用されるキャンセル トークンです。 インターフェイスには StopApplication
メソッドも含まれています。
次の例は、IHostApplicationLifetime
イベントを登録する IHostedService
の実装です。
internal class LifetimeEventsHostedService : IHostedService
{
private readonly ILogger _logger;
private readonly IHostApplicationLifetime _appLifetime;
public LifetimeEventsHostedService(
ILogger<LifetimeEventsHostedService> logger,
IHostApplicationLifetime appLifetime)
{
_logger = logger;
_appLifetime = appLifetime;
}
public Task StartAsync(CancellationToken cancellationToken)
{
_appLifetime.ApplicationStarted.Register(OnStarted);
_appLifetime.ApplicationStopping.Register(OnStopping);
_appLifetime.ApplicationStopped.Register(OnStopped);
return Task.CompletedTask;
}
public Task StopAsync(CancellationToken cancellationToken)
{
return Task.CompletedTask;
}
private void OnStarted()
{
_logger.LogInformation("OnStarted has been called.");
// Perform post-startup activities here
}
private void OnStopping()
{
_logger.LogInformation("OnStopping has been called.");
// Perform on-stopping activities here
}
private void OnStopped()
{
_logger.LogInformation("OnStopped has been called.");
// Perform post-stopped activities here
}
}
IHostLifetime
IHostLifetime 実装では、ホストを開始および停止するタイミングが制御されます。 登録されている最後の実装が使用されます。
Microsoft.Extensions.Hosting.Internal.ConsoleLifetime
は、既定の IHostLifetime
実装です。 ConsoleLifetime
:
- Ctrl+C/SIGINT (Windows)、⌘+C (macOS)、または SIGTERM をリッスンし、StopApplication を呼び出して、シャットダウン プロセスを開始します。
- RunAsync や WaitForShutdownAsync などの拡張機能のブロックを解除します。
IHostEnvironment
次の設定に関する情報を取得するため、クラスに IHostEnvironment サービスを注入します。
Web アプリで IWebHostEnvironment
インターフェイスを実装します。これにより、IHostEnvironment
が継承され、IWebHostEnvironment
が追加されます。
ホストの構成
ホストの構成は、IHostEnvironment 実装のプロパティで使用されます。
ホスト構成は、ConfigureAppConfiguration 内の HostBuilderContext.Configuration から使用できます。 ConfigureAppConfiguration
の後、HostBuilderContext.Configuration
はアプリの構成に置き換えられます。
ホストの構成を追加するには、IHostBuilder
上で ConfigureHostConfiguration を呼び出します。 ConfigureHostConfiguration
を複数回呼び出して結果を追加できます。 ホストは、指定されたキーで最後に値を設定したオプションを使用します。
プレフィックス DOTNET_
を持つ環境変数プロバイダーとコマンドライン引数が、CreateDefaultBuilder
によって組み込まれます。 Web アプリの場合は、プレフィックス ASPNETCORE_
を持つ環境変数プロバイダーが追加されます。 環境変数が読み取られると、プレフィックスは削除されます。 たとえば、ASPNETCORE_ENVIRONMENT
の環境変数の値が environment
キーのホスト構成値になります。
次の例では、ホストの構成を作成します。
// using Microsoft.Extensions.Configuration;
Host.CreateDefaultBuilder(args)
.ConfigureHostConfiguration(configHost =>
{
configHost.SetBasePath(Directory.GetCurrentDirectory());
configHost.AddJsonFile("hostsettings.json", optional: true);
configHost.AddEnvironmentVariables(prefix: "PREFIX_");
configHost.AddCommandLine(args);
});
アプリの構成
アプリの構成は、IHostBuilder
上で ConfigureAppConfiguration を呼び出すことで作成されます。 ConfigureAppConfiguration
を複数回呼び出して結果を追加できます。 アプリは、指定されたキーで最後に値を設定したオプションを使用します。
ConfigureAppConfiguration
によって作成された構成は、HostBuilderContext.Configuration で、以降の操作のために、かつ DI からのサービスとして利用できます。 ホストの構成はアプリの構成にも追加されます。
詳細については、「ASP.NET Core の構成」を参照してください。
すべての種類のアプリの設定
このセクションでは、HTTP のワークロードと HTTP 以外のワークロードの両方に適用されるホストの設定を一覧します。 既定では、これらの設定を構成するのに使用する環境変数には、プレフィックスとして DOTNET_
または ASPNETCORE_
を付けることができます。これらは、以下の構成で、{PREFIX_}
プレースホルダーの箇所に示されます。
ApplicationName
IHostEnvironment.ApplicationName プロパティは、ホストの構築時にホストの構成から設定されます。
キー: applicationName
型: string
既定: アプリのエントリ ポイントを含むアセンブリの名前。
環境変数: {PREFIX_}APPLICATIONNAME
この値を設定するには、環境変数を使用します。
ContentRoot
IHostEnvironment.ContentRootPath プロパティでは、ホストがコンテンツ ファイルの検索を開始する場所を決定します。 パスが存在しない場合は、ホストを起動できません。
キー: contentRoot
型: string
既定: アプリ アセンブリが存在するフォルダー。
環境変数: {PREFIX_}CONTENTROOT
この値を設定するには、環境変数を使用するか、または IHostBuilder
上で UseContentRoot
を呼び出します。
Host.CreateDefaultBuilder(args)
.UseContentRoot("c:\\content-root")
//...
詳細については次を参照してください:
EnvironmentName
IHostEnvironment.EnvironmentName プロパティは、任意の値に設定できます。 フレームワークで定義された値には Development
、Staging
、Production
が含まれます。 値は大文字と小文字が区別されません。
キー: environment
型: string
規定: Production
環境変数: {PREFIX_}ENVIRONMENT
この値を設定するには、環境変数を使用するか、または IHostBuilder
上で UseEnvironment
を呼び出します。
Host.CreateDefaultBuilder(args)
.UseEnvironment("Development")
//...
ShutdownTimeout
HostOptions.ShutdownTimeout によって StopAsync のタイムアウトが設定されます。 既定値は 5 秒です。 タイムアウト期間中、ホストでは次のことが行われます。
- IHostApplicationLifetime.ApplicationStopping をトリガーします。
- ホステッド サービスの停止を試み、停止に失敗したサービスのエラーをログに記録します。
すべてのホステッド サービスが停止する前にタイムアウト時間が切れた場合、残っているアクティブなサービスはアプリのシャットダウン時に停止します。 処理が完了していない場合でも、サービスは停止します。 サービスが停止するまでにさらに時間が必要な場合は、タイムアウト値を増やします。
キー: shutdownTimeoutSeconds
型: int
既定:5 秒
環境変数: {PREFIX_}SHUTDOWNTIMEOUTSECONDS
この値を設定するには、環境変数を使用するか、または HostOptions
を構成します。 次の例では、タイムアウトを 20 秒に設定します。
Host.CreateDefaultBuilder(args)
.ConfigureServices((hostContext, services) =>
{
services.Configure<HostOptions>(option =>
{
option.ShutdownTimeout = System.TimeSpan.FromSeconds(20);
});
});
Web アプリの設定
一部のホスト設定は、HTTP のワークロードにのみに適用されます。 既定では、これらの設定を構成するのに使用する環境変数には、プレフィックスとして DOTNET_
または ASPNETCORE_
を付けることができます。
IWebHostBuilder
上の拡張メソッドはこれらの設定で使用できます。 次の例に示すように、拡張メソッドを呼び出す方法を示すコード サンプルでは webBuilder
が IWebHostBuilder
のインスタンスであると想定しています。
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.CaptureStartupErrors(true);
webBuilder.UseStartup<Startup>();
});
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_port
型: string
既定:既定値は設定されていません。
環境変数: {PREFIX_}HTTPS_PORT
この値を設定するには、構成を使用するか、または UseSetting
を呼び出します。
webBuilder.UseSetting("https_port", "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");
詳細については次を参照してください:
ホストの有効期間を管理する
組み込みの 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 を呼び出します。
外部コントロール
ホストの有効期間の直接コントロールは、外部から呼び出すことができるメソッドを使って実現できます。
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 でホステッド サービスを使用するバックグラウンド タスク
- 汎用ホスト ソースへの GitHub リンク
Note
通常、.NET 参照ソースへのドキュメント リンクを使用すると、リポジトリの既定のブランチが読み込まれます。このブランチは、.NET の次回リリースに向けて行われている現在の開発を表します。 特定のリリースのタグを選択するには、[Switch branches or tags](ブランチまたはタグの切り替え) ドロップダウン リストを使います。 詳細については、「ASP.NET Core ソース コードのバージョン タグを選択する方法」 (dotnet/AspNetCore.Docs #26205) を参照してください。
ASP.NET Core