ASP.NET Core の Web ホスト

ASP.NET Core アプリはホストを構成して起動します。 ホストはアプリの起動と有効期間の管理を担当します。 少なくとも、ホストはサーバーおよび要求処理パイプラインを構成します。 ホストでは、ログ記録、依存関係挿入、構成を設定することもできます。

この記事では、Web ホストについて説明します。これは、下位互換性のためだけに引き続き使用可能となっています。 ASP.NET Core テンプレートにより、Web アプリに推奨されている WebApplicationBuilderWebApplication が作成されます。 WebApplicationBuilderWebApplication の詳細については、「ASP.NET Core 5.0 から 6.0 への移行」を参照してください

ホストを設定する

IWebHostBuilder のインスタンスを使用して、ホストを作成します。 通常、これはアプリのエントリ ポイントである、Program.csMain メソッドで実行されます。 一般的なアプリでは、CreateDefaultBuilder を呼び出してホストの設定を開始します。

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>();
}

CreateDefaultBuilder を呼び出すコードは、CreateWebHostBuilder という名前のメソッドに含まれ、ビルダー オブジェクトで Run を呼び出す Main のコードから分離されています。 Entity Framework Core ツールを使用する場合は、このような分離が必要です。 ツールでは、アプリを実行することなくホストを構成するために、デザイン時に呼び出すことができる CreateWebHostBuilder メソッドの検出が想定されます。 別の方法は、IDesignTimeDbContextFactory を実装することです。 詳細については、「デザイン時 DbContext 作成」をご覧ください。

CreateDefaultBuilder では次のタスクを実行します。

CreateDefaultBuilder によって定義された構成は、ConfigureAppConfigurationConfigureLogging、および IWebHostBuilder の他のメソッドと拡張メソッドによって、オーバーライドおよび拡張できます。 以下に、いくつかの例を示します。

  • ConfigureAppConfiguration は、アプリの追加の IConfiguration を指定するために使用されます。 次の ConfigureAppConfiguration の呼び出しによりデリゲートが追加され、appsettings.xml ファイルにアプリの構成が含まれます。 ConfigureAppConfiguration は複数回呼び出すことができます。 この構成はホスト (たとえば、サーバーの URL や環境など) には適用されないことに注意してください。 「ホストの構成値」のセクションを参照してください。

    WebHost.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
        })
        ...
    
  • 次の ConfigureLogging の呼び出しによりデリゲートが追加され、最小ログ記録レベル (SetMinimumLevel) が LogLevel.Warning に構成されます。 この設定により、CreateDefaultBuilder で構成された appsettings.Development.json (LogLevel.Debug) および appsettings.Production.json (LogLevel.Error) の設定がオーバーライドされます。 ConfigureLogging は複数回呼び出すことができます。

    WebHost.CreateDefaultBuilder(args)
        .ConfigureLogging(logging => 
        {
            logging.SetMinimumLevel(LogLevel.Warning);
        })
        ...
    
  • 次の ConfigureKestrel の呼び出しにより、Kestrel が CreateDefaultBuilder によって構成されたときに確立された既定の Limits.MaxRequestBodySize サイズである 30,000,000 バイトがオーバーライドされます。

    WebHost.CreateDefaultBuilder(args)
        .ConfigureKestrel((context, options) =>
        {
            options.Limits.MaxRequestBodySize = 20000000;
        });
    

コンテンツ ルートで、ホストが MVC ビュー ファイルなどのコンテンツ ファイルを検索する場所を決定します。 プロジェクトのルート フォルダーからアプリが開始された場合は、そのプロジェクトのルート フォルダーがコンテンツ ルートとして使用されます。 これは、Visual Studiodotnet の新しいテンプレートで使用される既定です。

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

Note

静的な CreateDefaultBuilder メソッドを使用する代わりに、WebHostBuilder からホストを作成する方法が ASP.NET Core 2.x でサポートされています。

ホストの構成時に、Configure および ConfigureServices メソッドを指摘することができます。 Startup クラスが指定されている場合は、Configure メソッドを定義する必要があります。 詳細については、「ASP.NET Core でのアプリケーションのスタートアップ」をご覧ください。 ConfigureServices の複数回の呼び出しでは、互いに追加されます。 WebHostBuilder での Configure または UseStartup の複数回の呼び出しでは、以前の設定が置き換えられます。

ホストの構成値

WebHostBuilder では、ホストの構成値を設定する場合に以下の方法に依存します。

  • ASPNETCORE_{configurationKey} 形式の環境変数を含む、ホスト ビルダー構成。 たとえば、ASPNETCORE_ENVIRONMENT のようにします。
  • UseContentRootUseConfiguration などの拡張機能 (「構成をオーバーライドする」セクションを参照)。
  • UseSetting および関連付けられているキー。 UseSetting で値を設定すると、値はその型に関係なく、文字列として設定されます。

ホストは、最後に値を設定したオプションを使用します。 詳しくは、次のセクション「構成をオーバーライドする」をご覧ください。

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

ホストの構築時に UseStartup または Configure が呼び出されると、IWebHostEnvironment.ApplicationName プロパティが自動的に設定されます。 この値はアプリのエントリ ポイントを含むアセンブリの名前に設定されます。 値を明示的に設定するには、WebHostDefaults.ApplicationKey を使用します。

キー: applicationName
: 文字列
既定値:アプリのエントリ ポイントを含むアセンブリの名前。
次を使用して設定: UseSetting
環境変数: ASPNETCORE_APPLICATIONNAME

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")

スタートアップ エラーをキャプチャする

この設定では、スタートアップ エラーのキャプチャを制御します。

キー: captureStartupErrors
: ブール (true または 1)
既定値: アプリが IIS の背後で Kestrel を使用して実行されている場合 (既定値は true) を除き、既定では false に設定されます。
次を使用して設定: CaptureStartupErrors
環境変数: ASPNETCORE_CAPTURESTARTUPERRORS

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

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

コンテンツ ルート

この設定により、ASP.NET Core でコンテンツ ファイルの検索が開始される場所が決まります。

キー: contentRoot
: 文字列
既定:既定でアプリ アセンブリが存在するフォルダーに設定されます。
次を使用して設定: UseContentRoot
環境変数: ASPNETCORE_CONTENTROOT

コンテンツ ルートは、Web ルートの基本パスとしても使用されます。 コンテンツ ルート パスが存在しない場合は、ホストを起動できません。

WebHost.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\<content-root>")

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

詳細なエラー

詳細なエラーをキャプチャするかどうかを判断します。

キー: detailedErrors
: ブール (true または 1)
既定値: false
次を使用して設定: UseSetting
環境変数: ASPNETCORE_DETAILEDERRORS

有効な場合 (または環境Development に設定されている場合)、アプリは詳細な例外をキャプチャします。

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.DetailedErrorsKey, "true")

環境

アプリの環境を設定します。

キー: 環境
: 文字列
既定:実稼働
次を使用して設定: UseEnvironment
環境変数: ASPNETCORE_ENVIRONMENT

環境は任意の値に設定することができます。 フレームワークで定義された値には DevelopmentStagingProduction が含まれます。 値は大文字と小文字が区別されません。 既定では、環境ASPNETCORE_ENVIRONMENT 環境変数から読み取られます。 Visual Studio を使用する場合、環境変数は launchSettings.json ファイルで設定できます。 詳細については、「ASP.NET Core で複数の環境を使用する」を参照してください。

WebHost.CreateDefaultBuilder(args)
    .UseEnvironment(EnvironmentName.Development)

ホスティング スタートアップ アセンブリ

アプリのホスティング スタートアップ アセンブリを設定します。

キー: hostingStartupAssemblies
: 文字列
既定:空の文字列
次を使用して設定: UseSetting
環境変数: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

起動時に読み込むホスティング スタートアップ アセンブリのセミコロンで区切られた文字列。

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

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2")

HTTPS Port

HTTPS リダイレクト ポートを設定します。 HTTPS の適用に使用されます。

キー: https_port
: 文字列
既定:既定値は設定されていません。
次を使用して設定: UseSetting
環境変数: ASPNETCORE_HTTPS_PORTS

WebHost.CreateDefaultBuilder(args)
    .UseSetting("https_port", "8080")

除外するホスティング スタートアップ アセンブリ

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

キー: hostingStartupExcludeAssemblies
: 文字列
既定:空の文字列
次を使用して設定: UseSetting
環境変数: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2")

ホスティング URL を優先する

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

キー: preferHostingUrls
: ブール (true または 1)
既定値: false
次を使用して設定: PreferHostingUrls
環境変数: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(true)

ホスティング スタートアップを回避する

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

キー: preventHostingStartup
: ブール (true または 1)
既定値: false
次を使用して設定: UseSetting
環境変数: ASPNETCORE_PREVENTHOSTINGSTARTUP

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.PreventHostingStartupKey, "true")

サーバーの URL

サーバーが要求をリッスンする必要があるポートとプロトコルを使用して、IP アドレスまたはホスト アドレスを示します。

キー: urls
: 文字列
規定:http://localhost:5000
次を使用して設定: UseUrls
環境変数: ASPNETCORE_URLS

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

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

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

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

Web ホストがシャットダウンするまで待機する時間を指定します。

キー: shutdownTimeoutSeconds
: int
既定:5
次を使用して設定: UseShutdownTimeout
環境変数: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

キーでは UseSetting が指定された int (.UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10") など) を受け入れますが、UseShutdownTimeout 拡張メソッドでは TimeSpan を受け取ります。

タイムアウト期間中、ホスティングは次のことを行います。

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

WebHost.CreateDefaultBuilder(args)
    .UseShutdownTimeout(TimeSpan.FromSeconds(10))

スタートアップ アセンブリ

Startup クラスを検索するアセンブリを決定します。

キー: startupAssembly
: 文字列
既定:アプリのアセンブリ
次を使用して設定: UseStartup
環境変数: ASPNETCORE_STARTUPASSEMBLY

名前 (string) または型 (TStartup) 別のアセンブリを参照できます。 複数の UseStartup メソッドが呼び出された場合は、最後のメソッドが優先されます。

WebHost.CreateDefaultBuilder(args)
    .UseStartup("StartupAssemblyName")
WebHost.CreateDefaultBuilder(args)
    .UseStartup<TStartup>()

Web ルート

アプリの静的資産への相対パスを設定します。

キー: webroot
: 文字列
既定:既定値は、wwwroot です。 {content root}/wwwroot へのパスが存在する必要があります。 パスが存在しない場合は、no-op ファイル プロバイダーが使用されます。
次を使用して設定: UseWebRoot
環境変数: ASPNETCORE_WEBROOT

WebHost.CreateDefaultBuilder(args)
    .UseWebRoot("public")

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

構成をオーバーライドする

Configuration を使用して、Web ホストを構成します。 次の例では、ホスト構成はオプションで hostsettings.json ファイルに指定されます。 hostsettings.json ファイルから読み込まれた構成は、コマンド ライン引数でオーバーライドされる場合があります。 (config の) ビルド構成は、UseConfiguration でホストを構成する場合に使用されます。 IWebHostBuilder 構成はアプリの構成に追加されますが、その逆は当てはまりません。ConfigureAppConfigurationIWebHostBuilder の構成に影響しません。

次のように、UseUrls で指定された構成をオーバーライドします (最初の構成は hostsettings.json、2 番目の構成はコマンドライン引数です)。

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("hostsettings.json", optional: true)
            .AddCommandLine(args)
            .Build();

        return WebHost.CreateDefaultBuilder(args)
            .UseUrls("http://*:5000")
            .UseConfiguration(config)
            .Configure(app =>
            {
                app.Run(context => 
                    context.Response.WriteAsync("Hello, World!"));
            });
    }
}

hostsettings.json:

{
    urls: "http://*:5005"
}

注意

UseConfiguration は、指定された IConfiguration からホスト ビルダーの構成へのキーのみをコピーします。 そのため、JSON、INI、XML 設定のファイルに reloadOnChange: true を設定しても影響はありません。

特定の URL でホストを実行するように指定する場合、dotnet run の実行時にコマンド プロンプトから必要な値を渡すことができます。 コマンドライン引数は hostsettings.json ファイルからの urls 値をオーバーライドし、サーバーはポート 8080 でリッスンします。

dotnet run --urls "http://*:8080"

ホストを管理する

実行

Run メソッドは Web アプリを起動し、ホストがシャットダウンするまで呼び出し元のスレッドをブロックします。

host.Run();

[開始]

Start メソッドを呼び出して、ブロックせずにホストを実行します。

using (host)
{
    host.Start();
    Console.ReadLine();
}

URL のリストが Start メソッドに渡された場合、指定された URL でリッスンします。

var urls = new List<string>()
{
    "http://*:5000",
    "http://localhost:5001"
};

var host = new WebHostBuilder()
    .UseKestrel()
    .UseStartup<Startup>()
    .Start(urls.ToArray());

using (host)
{
    Console.ReadLine();
}

アプリは、便利な静的メソッドを使用し、CreateDefaultBuilder の構成済みの既定値を使用して、新しいホストを初期化して起動できます。 これらのメソッドは、コンソール出力なしでサーバーを起動します。その場合、WaitForShutdown を指定し、中断される (Ctrl-C/SIGINT または SIGTERM) まで待機します。

Start(RequestDelegate app)

次のように RequestDelegate で始まります。

using (var host = WebHost.Start(app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

"Hello World!" という応答を受け取るには、ブラウザで http://localhost:5000 に対する要求を行います。WaitForShutdown は、中断される (Ctrl-C/SIGINT または SIGTERM) までブロックします。 アプリは Console.WriteLine メッセージを表示し、キー入力が終わるまで待機します。

Start(string url, RequestDelegate app)

次のように、URL と RequestDelegate で始まります。

using (var host = WebHost.Start("http://localhost:8080", app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

アプリが http://localhost:8080 で応答する場合を除き、Start(RequestDelegate app) と同じ結果が生成されます。

Start(Action<IRouteBuilder> routeBuilder)

次のように、IRouteBuilder (Microsoft.AspNetCore.Routing) のインスタンスを使用してルーティング ミドルウェアを使用します。

using (var host = WebHost.Start(router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

この例では、以下のブラウザー要求を使用します。

要求 応答
http://localhost:5000/hello/Martin Hello, Martin!
http://localhost:5000/buenosdias/Catrina Buenos dias, Catrina!
http://localhost:5000/throw/ooops! "ooops!" という文字列がある場合は例外をスローします。
http://localhost:5000/throw "Uh oh!" という文字列がある場合は例外をスローします。
http://localhost:5000/Sante/Kevin Sante, Kevin!
http://localhost:5000 Hello World!

WaitForShutdown は、中断される (Ctrl-C/SIGINT または SIGTERM) までブロックします。 アプリは Console.WriteLine メッセージを表示し、キー入力が終わるまで待機します。

Start(string url, Action<IRouteBuilder> routeBuilder)

次のように、URL と IRouteBuilder のインスタンスを使用します。

using (var host = WebHost.Start("http://localhost:8080", router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

アプリが http://localhost:8080 で応答する場合を除き、Start(Action<IRouteBuilder> routeBuilder) と同じ結果が生成されます。

StartWith(Action<IApplicationBuilder> app)

次のように、デリゲートを指定して IApplicationBuilder を構成します。

using (var host = WebHost.StartWith(app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

"Hello World!" という応答を受け取るには、ブラウザで http://localhost:5000 に対する要求を行います。WaitForShutdown は、中断される (Ctrl-C/SIGINT または SIGTERM) までブロックします。 アプリは Console.WriteLine メッセージを表示し、キー入力が終わるまで待機します。

StartWith(string url, Action<IApplicationBuilder> app)

次のように、URL とデリゲートを指定して IApplicationBuilder を構成します。

using (var host = WebHost.StartWith("http://localhost:8080", app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

アプリが http://localhost:8080 で応答する場合を除き、StartWith(Action<IApplicationBuilder> app) と同じ結果が生成されます。

IWebHostEnvironment インターフェイス

IWebHostEnvironment インターフェイスでは、アプリの Web ホスティング環境に関する情報が提供されます。 プロパティと拡張メソッドを使用するには、コンストラクターの挿入を使用して IWebHostEnvironment を取得します。

public class CustomFileReader
{
    private readonly IWebHostEnvironment _env;

    public CustomFileReader(IWebHostEnvironment env)
    {
        _env = env;
    }

    public string ReadFile(string filePath)
    {
        var fileProvider = _env.WebRootFileProvider;
        // Process the file here
    }
}

規則ベースのアプローチを使用して、環境に基づいて起動時にアプリを構成することができます。 あるいは、次のように ConfigureServices で使用するために IWebHostEnvironmentStartup コンストラクターに挿入します。

public class Startup
{
    public Startup(IWebHostEnvironment env)
    {
        HostingEnvironment = env;
    }

    public IWebHostEnvironment HostingEnvironment { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        if (HostingEnvironment.IsDevelopment())
        {
            // Development configuration
        }
        else
        {
            // Staging/Production configuration
        }

        var contentRootPath = HostingEnvironment.ContentRootPath;
    }
}

Note

IsDevelopment 拡張メソッドに加え、IWebHostEnvironmentIsStagingIsProductionIsEnvironment(string environmentName) メソッドを提供します。 詳細については、「ASP.NET Core で複数の環境を使用する」を参照してください。

処理パイプラインを設定するために、次のように IWebHostEnvironment サービスを Configure メソッドに直接挿入することもできます。

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // In Development, use the Developer Exception Page
        app.UseDeveloperExceptionPage();
    }
    else
    {
        // In Staging/Production, route exceptions to /error
        app.UseExceptionHandler("/error");
    }

    var contentRootPath = env.ContentRootPath;
}

カスタムのミドルウェアを作成する際に、次のように IWebHostEnvironmentInvoke メソッドに挿入することができます。

public async Task Invoke(HttpContext context, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // Configure middleware for Development
    }
    else
    {
        // Configure middleware for Staging/Production
    }

    var contentRootPath = env.ContentRootPath;
}

IHostApplicationLifetime インターフェイス

IHostApplicationLifetime では、起動後とシャットダウンのアクティビティを実行できます。 インターフェイスの 3 つのプロパティは、起動とシャットダウン イベントを定義する Action メソッドを登録するために使用されるキャンセル トークンです。

キャンセル トークン トリガーのタイミング
ApplicationStarted ホストが完全に起動されたとき。
ApplicationStopped ホストが正常なシャットダウンを完了しているとき。 すべての要求を処理する必要があります。 このイベントが完了するまで、シャットダウンはブロックされます。
ApplicationStopping ホストが正常なシャットダウンを行っているとき。 要求がまだ処理されている可能性がある場合。 このイベントが完了するまで、シャットダウンはブロックされます。
public class Startup
{
    public void Configure(IApplicationBuilder app, IHostApplicationLifetime appLifetime)
    {
        appLifetime.ApplicationStarted.Register(OnStarted);
        appLifetime.ApplicationStopping.Register(OnStopping);
        appLifetime.ApplicationStopped.Register(OnStopped);

        Console.CancelKeyPress += (sender, eventArgs) =>
        {
            appLifetime.StopApplication();
            // Don't terminate the process immediately, wait for the Main thread to exit gracefully.
            eventArgs.Cancel = true;
        };
    }

    private void OnStarted()
    {
        // Perform post-startup activities here
    }

    private void OnStopping()
    {
        // Perform on-stopping activities here
    }

    private void OnStopped()
    {
        // Perform post-stopped activities here
    }
}

StopApplication は、アプリの終了を要求します。 以下のクラスは、クラスの Shutdown メソッドが呼び出されると、StopApplication を使ってアプリを正常にシャットダウンします。

public class MyClass
{
    private readonly IHostApplicationLifetime _appLifetime;

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

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

スコープの検証

アプリの環境が開発の場合、CreateDefaultBuilder によって ServiceProviderOptions.ValidateScopestrue に設定されます。

ValidateScopestrue に設定されていると、既定のサービス プロバイダーはチェックを実行して次のことを確認します。

  • スコープ サービスが、ルート サービス プロバイダーによって直接的または間接的に解決されない。
  • スコープ サービスが、シングルトンに直接または間接に挿入されない。

BuildServiceProvider が呼び出されると、ルート サービス プロバイダーが作成されます。 ルート サービス プロバイダーの有効期間は、プロバイダーがアプリで開始されるとアプリとサーバーの有効期間に対応し、アプリのシャットダウンには破棄されます。

スコープ サービスは、それを作成したコンテナーによって破棄されます。 ルート コンテナーにスコープ サービスが作成されると、サービスはアプリ/サーバーのシャットダウン時に、ルート コンテナーによってのみ破棄されるため、サービスの有効期間は実質的にシングルトンに昇格されます。 BuildServiceProvider が呼び出されると、サービス スコープの検証がこれらの状況をキャッチします。

運用環境も含めて、常にスコープを検証するには、ホスト ビルダー上の UseDefaultServiceProviderServiceProviderOptions を構成します。

WebHost.CreateDefaultBuilder(args)
    .UseDefaultServiceProvider((context, options) => {
        options.ValidateScopes = true;
    })

その他の技術情報

ASP.NET Core アプリはホストを構成して起動します。 ホストはアプリの起動と有効期間の管理を担当します。 少なくとも、ホストはサーバーおよび要求処理パイプラインを構成します。 ホストでは、ログ記録、依存関係挿入、構成を設定することもできます。

この記事では、Web ホストについて説明します。これは、下位互換性のためだけに引き続き使用可能となっています。 ASP.NET Core テンプレートを使用すると、すべての種類のアプリに推奨されている .NET での汎用ホストが作成されます。

ホストを設定する

IWebHostBuilder のインスタンスを使用して、ホストを作成します。 通常、これはアプリのエントリ ポイントの Main メソッドで実行されます。

プロジェクト テンプレートでは、MainProgram.cs にあります。 一般的なアプリでは、CreateDefaultBuilder を呼び出してホストの設定を開始します。

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>();
}

CreateDefaultBuilder を呼び出すコードは、CreateWebHostBuilder という名前のメソッドに含まれ、ビルダー オブジェクトで Run を呼び出す Main のコードから分離されています。 Entity Framework Core ツールを使用する場合は、このような分離が必要です。 ツールでは、アプリを実行することなくホストを構成するために、デザイン時に呼び出すことができる CreateWebHostBuilder メソッドの検出が想定されます。 別の方法は、IDesignTimeDbContextFactory を実装することです。 詳細については、「デザイン時 DbContext 作成」をご覧ください。

CreateDefaultBuilder では次のタスクを実行します。

CreateDefaultBuilder によって定義された構成は、ConfigureAppConfigurationConfigureLogging、および IWebHostBuilder の他のメソッドと拡張メソッドによって、オーバーライドおよび拡張できます。 以下に、いくつかの例を示します。

  • ConfigureAppConfiguration は、アプリの追加の IConfiguration を指定するために使用されます。 次の ConfigureAppConfiguration の呼び出しによりデリゲートが追加され、appsettings.xml ファイルにアプリの構成が含まれます。 ConfigureAppConfiguration は複数回呼び出すことができます。 この構成はホスト (たとえば、サーバーの URL や環境など) には適用されないことに注意してください。 「ホストの構成値」のセクションを参照してください。

    WebHost.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
        })
        ...
    
  • 次の ConfigureLogging の呼び出しによりデリゲートが追加され、最小ログ記録レベル (SetMinimumLevel) が LogLevel.Warning に構成されます。 この設定により、CreateDefaultBuilder で構成された appsettings.Development.json (LogLevel.Debug) および appsettings.Production.json (LogLevel.Error) の設定がオーバーライドされます。 ConfigureLogging は複数回呼び出すことができます。

    WebHost.CreateDefaultBuilder(args)
        .ConfigureLogging(logging => 
        {
            logging.SetMinimumLevel(LogLevel.Warning);
        })
        ...
    
  • 次の ConfigureKestrel の呼び出しにより、Kestrel が CreateDefaultBuilder によって構成されたときに確立された既定の Limits.MaxRequestBodySize サイズである 30,000,000 バイトがオーバーライドされます。

    WebHost.CreateDefaultBuilder(args)
        .ConfigureKestrel((context, options) =>
        {
            options.Limits.MaxRequestBodySize = 20000000;
        });
    

コンテンツ ルートで、ホストが MVC ビュー ファイルなどのコンテンツ ファイルを検索する場所を決定します。 プロジェクトのルート フォルダーからアプリが開始された場合は、そのプロジェクトのルート フォルダーがコンテンツ ルートとして使用されます。 これは、Visual Studiodotnet の新しいテンプレートで使用される既定です。

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

Note

静的な CreateDefaultBuilder メソッドを使用する代わりに、WebHostBuilder からホストを作成する方法が ASP.NET Core 2.x でサポートされています。

ホストの構成時に、Configure および ConfigureServices メソッドを指摘することができます。 Startup クラスが指定されている場合は、Configure メソッドを定義する必要があります。 詳細については、「ASP.NET Core でのアプリケーションのスタートアップ」をご覧ください。 ConfigureServices の複数回の呼び出しでは、互いに追加されます。 WebHostBuilder での Configure または UseStartup の複数回の呼び出しでは、以前の設定が置き換えられます。

ホストの構成値

WebHostBuilder では、ホストの構成値を設定する場合に以下の方法に依存します。

  • ASPNETCORE_{configurationKey} 形式の環境変数を含む、ホスト ビルダー構成。 たとえば、ASPNETCORE_ENVIRONMENT のようにします。
  • UseContentRootUseConfiguration などの拡張機能 (「構成をオーバーライドする」セクションを参照)。
  • UseSetting および関連付けられているキー。 UseSetting で値を設定すると、値はその型に関係なく、文字列として設定されます。

ホストは、最後に値を設定したオプションを使用します。 詳しくは、次のセクション「構成をオーバーライドする」をご覧ください。

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

ホストの構築時に UseStartup または Configure が呼び出されると、IWebHostEnvironment.ApplicationName プロパティが自動的に設定されます。 この値はアプリのエントリ ポイントを含むアセンブリの名前に設定されます。 値を明示的に設定するには、WebHostDefaults.ApplicationKey を使用します。

キー: applicationName
: 文字列
既定値:アプリのエントリ ポイントを含むアセンブリの名前。
次を使用して設定: UseSetting
環境変数: ASPNETCORE_APPLICATIONNAME

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")

スタートアップ エラーをキャプチャする

この設定では、スタートアップ エラーのキャプチャを制御します。

キー: captureStartupErrors
: ブール (true または 1)
既定値: アプリが IIS の背後で Kestrel を使用して実行されている場合 (既定値は true) を除き、既定では false に設定されます。
次を使用して設定: CaptureStartupErrors
環境変数: ASPNETCORE_CAPTURESTARTUPERRORS

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

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

コンテンツ ルート

この設定により、ASP.NET Core でコンテンツ ファイルの検索が開始される場所が決まります。

キー: contentRoot
: 文字列
既定:既定でアプリ アセンブリが存在するフォルダーに設定されます。
次を使用して設定: UseContentRoot
環境変数: ASPNETCORE_CONTENTROOT

コンテンツ ルートは、Web ルートの基本パスとしても使用されます。 コンテンツ ルート パスが存在しない場合は、ホストを起動できません。

WebHost.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\<content-root>")

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

詳細なエラー

詳細なエラーをキャプチャするかどうかを判断します。

キー: detailedErrors
: ブール (true または 1)
既定値: false
次を使用して設定: UseSetting
環境変数: ASPNETCORE_DETAILEDERRORS

有効な場合 (または環境Development に設定されている場合)、アプリは詳細な例外をキャプチャします。

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.DetailedErrorsKey, "true")

環境

アプリの環境を設定します。

キー: 環境
: 文字列
既定:実稼働
次を使用して設定: UseEnvironment
環境変数: ASPNETCORE_ENVIRONMENT

環境は任意の値に設定することができます。 フレームワークで定義された値には DevelopmentStagingProduction が含まれます。 値は大文字と小文字が区別されません。 既定では、環境ASPNETCORE_ENVIRONMENT 環境変数から読み取られます。 Visual Studio を使用する場合、環境変数は launchSettings.json ファイルで設定できます。 詳細については、「ASP.NET Core で複数の環境を使用する」を参照してください。

WebHost.CreateDefaultBuilder(args)
    .UseEnvironment(EnvironmentName.Development)

ホスティング スタートアップ アセンブリ

アプリのホスティング スタートアップ アセンブリを設定します。

キー: hostingStartupAssemblies
: 文字列
既定:空の文字列
次を使用して設定: UseSetting
環境変数: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

起動時に読み込むホスティング スタートアップ アセンブリのセミコロンで区切られた文字列。

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

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2")

HTTPS Port

HTTPS リダイレクト ポートを設定します。 HTTPS の適用に使用されます。

キー: https_port
: 文字列
既定:既定値は設定されていません。
次を使用して設定: UseSetting
環境変数: ASPNETCORE_HTTPS_PORTS

WebHost.CreateDefaultBuilder(args)
    .UseSetting("https_port", "8080")

除外するホスティング スタートアップ アセンブリ

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

キー: hostingStartupExcludeAssemblies
: 文字列
既定:空の文字列
次を使用して設定: UseSetting
環境変数: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2")

ホスティング URL を優先する

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

キー: preferHostingUrls
: ブール (true または 1)
既定値: false
次を使用して設定: PreferHostingUrls
環境変数: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(true)

ホスティング スタートアップを回避する

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

キー: preventHostingStartup
: ブール (true または 1)
既定値: false
次を使用して設定: UseSetting
環境変数: ASPNETCORE_PREVENTHOSTINGSTARTUP

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.PreventHostingStartupKey, "true")

サーバーの URL

サーバーが要求をリッスンする必要があるポートとプロトコルを使用して、IP アドレスまたはホスト アドレスを示します。

キー: urls
: 文字列
規定:http://localhost:5000
次を使用して設定: UseUrls
環境変数: ASPNETCORE_URLS

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

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

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

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

Web ホストがシャットダウンするまで待機する時間を指定します。

キー: shutdownTimeoutSeconds
: int
既定:5
次を使用して設定: UseShutdownTimeout
環境変数: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

キーでは UseSetting が指定された int (.UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10") など) を受け入れますが、UseShutdownTimeout 拡張メソッドでは TimeSpan を受け取ります。

タイムアウト期間中、ホスティングは次のことを行います。

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

WebHost.CreateDefaultBuilder(args)
    .UseShutdownTimeout(TimeSpan.FromSeconds(10))

スタートアップ アセンブリ

Startup クラスを検索するアセンブリを決定します。

キー: startupAssembly
: 文字列
既定:アプリのアセンブリ
次を使用して設定: UseStartup
環境変数: ASPNETCORE_STARTUPASSEMBLY

名前 (string) または型 (TStartup) 別のアセンブリを参照できます。 複数の UseStartup メソッドが呼び出された場合は、最後のメソッドが優先されます。

WebHost.CreateDefaultBuilder(args)
    .UseStartup("StartupAssemblyName")
WebHost.CreateDefaultBuilder(args)
    .UseStartup<TStartup>()

Web ルート

アプリの静的資産への相対パスを設定します。

キー: webroot
: 文字列
既定:既定値は、wwwroot です。 {content root}/wwwroot へのパスが存在する必要があります。 パスが存在しない場合は、no-op ファイル プロバイダーが使用されます。
次を使用して設定: UseWebRoot
環境変数: ASPNETCORE_WEBROOT

WebHost.CreateDefaultBuilder(args)
    .UseWebRoot("public")

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

構成をオーバーライドする

Configuration を使用して、Web ホストを構成します。 次の例では、ホスト構成はオプションで hostsettings.json ファイルに指定されます。 hostsettings.json ファイルから読み込まれた構成は、コマンド ライン引数でオーバーライドされる場合があります。 (config の) ビルド構成は、UseConfiguration でホストを構成する場合に使用されます。 IWebHostBuilder 構成はアプリの構成に追加されますが、その逆は当てはまりません。ConfigureAppConfigurationIWebHostBuilder の構成に影響しません。

次のように、UseUrls で指定された構成をオーバーライドします (最初の構成は hostsettings.json、2 番目の構成はコマンドライン引数です)。

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("hostsettings.json", optional: true)
            .AddCommandLine(args)
            .Build();

        return WebHost.CreateDefaultBuilder(args)
            .UseUrls("http://*:5000")
            .UseConfiguration(config)
            .Configure(app =>
            {
                app.Run(context => 
                    context.Response.WriteAsync("Hello, World!"));
            });
    }
}

hostsettings.json:

{
    urls: "http://*:5005"
}

注意

UseConfiguration は、指定された IConfiguration からホスト ビルダーの構成へのキーのみをコピーします。 そのため、JSON、INI、XML 設定のファイルに reloadOnChange: true を設定しても影響はありません。

特定の URL でホストを実行するように指定する場合、dotnet run の実行時にコマンド プロンプトから必要な値を渡すことができます。 コマンドライン引数は hostsettings.json ファイルからの urls 値をオーバーライドし、サーバーはポート 8080 でリッスンします。

dotnet run --urls "http://*:8080"

ホストを管理する

実行

Run メソッドは Web アプリを起動し、ホストがシャットダウンするまで呼び出し元のスレッドをブロックします。

host.Run();

[開始]

Start メソッドを呼び出して、ブロックせずにホストを実行します。

using (host)
{
    host.Start();
    Console.ReadLine();
}

URL のリストが Start メソッドに渡された場合、指定された URL でリッスンします。

var urls = new List<string>()
{
    "http://*:5000",
    "http://localhost:5001"
};

var host = new WebHostBuilder()
    .UseKestrel()
    .UseStartup<Startup>()
    .Start(urls.ToArray());

using (host)
{
    Console.ReadLine();
}

アプリは、便利な静的メソッドを使用し、CreateDefaultBuilder の構成済みの既定値を使用して、新しいホストを初期化して起動できます。 これらのメソッドは、コンソール出力なしでサーバーを起動します。その場合、WaitForShutdown を指定し、中断される (Ctrl-C/SIGINT または SIGTERM) まで待機します。

Start(RequestDelegate app)

次のように RequestDelegate で始まります。

using (var host = WebHost.Start(app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

"Hello World!" という応答を受け取るには、ブラウザで http://localhost:5000 に対する要求を行います。WaitForShutdown は、中断される (Ctrl-C/SIGINT または SIGTERM) までブロックします。 アプリは Console.WriteLine メッセージを表示し、キー入力が終わるまで待機します。

Start(string url, RequestDelegate app)

次のように、URL と RequestDelegate で始まります。

using (var host = WebHost.Start("http://localhost:8080", app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

アプリが http://localhost:8080 で応答する場合を除き、Start(RequestDelegate app) と同じ結果が生成されます。

Start(Action<IRouteBuilder> routeBuilder)

次のように、IRouteBuilder (Microsoft.AspNetCore.Routing) のインスタンスを使用してルーティング ミドルウェアを使用します。

using (var host = WebHost.Start(router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

この例では、以下のブラウザー要求を使用します。

要求 応答
http://localhost:5000/hello/Martin Hello, Martin!
http://localhost:5000/buenosdias/Catrina Buenos dias, Catrina!
http://localhost:5000/throw/ooops! "ooops!" という文字列がある場合は例外をスローします。
http://localhost:5000/throw "Uh oh!" という文字列がある場合は例外をスローします。
http://localhost:5000/Sante/Kevin Sante, Kevin!
http://localhost:5000 Hello World!

WaitForShutdown は、中断される (Ctrl-C/SIGINT または SIGTERM) までブロックします。 アプリは Console.WriteLine メッセージを表示し、キー入力が終わるまで待機します。

Start(string url, Action<IRouteBuilder> routeBuilder)

次のように、URL と IRouteBuilder のインスタンスを使用します。

using (var host = WebHost.Start("http://localhost:8080", router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

アプリが http://localhost:8080 で応答する場合を除き、Start(Action<IRouteBuilder> routeBuilder) と同じ結果が生成されます。

StartWith(Action<IApplicationBuilder> app)

次のように、デリゲートを指定して IApplicationBuilder を構成します。

using (var host = WebHost.StartWith(app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

"Hello World!" という応答を受け取るには、ブラウザで http://localhost:5000 に対する要求を行います。WaitForShutdown は、中断される (Ctrl-C/SIGINT または SIGTERM) までブロックします。 アプリは Console.WriteLine メッセージを表示し、キー入力が終わるまで待機します。

StartWith(string url, Action<IApplicationBuilder> app)

次のように、URL とデリゲートを指定して IApplicationBuilder を構成します。

using (var host = WebHost.StartWith("http://localhost:8080", app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

アプリが http://localhost:8080 で応答する場合を除き、StartWith(Action<IApplicationBuilder> app) と同じ結果が生成されます。

IWebHostEnvironment インターフェイス

IWebHostEnvironment インターフェイスでは、アプリの Web ホスティング環境に関する情報が提供されます。 プロパティと拡張メソッドを使用するには、コンストラクターの挿入を使用して IWebHostEnvironment を取得します。

public class CustomFileReader
{
    private readonly IWebHostEnvironment _env;

    public CustomFileReader(IWebHostEnvironment env)
    {
        _env = env;
    }

    public string ReadFile(string filePath)
    {
        var fileProvider = _env.WebRootFileProvider;
        // Process the file here
    }
}

規則ベースのアプローチを使用して、環境に基づいて起動時にアプリを構成することができます。 あるいは、次のように ConfigureServices で使用するために IWebHostEnvironmentStartup コンストラクターに挿入します。

public class Startup
{
    public Startup(IWebHostEnvironment env)
    {
        HostingEnvironment = env;
    }

    public IWebHostEnvironment HostingEnvironment { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        if (HostingEnvironment.IsDevelopment())
        {
            // Development configuration
        }
        else
        {
            // Staging/Production configuration
        }

        var contentRootPath = HostingEnvironment.ContentRootPath;
    }
}

Note

IsDevelopment 拡張メソッドに加え、IWebHostEnvironmentIsStagingIsProductionIsEnvironment(string environmentName) メソッドを提供します。 詳細については、「ASP.NET Core で複数の環境を使用する」を参照してください。

処理パイプラインを設定するために、次のように IWebHostEnvironment サービスを Configure メソッドに直接挿入することもできます。

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // In Development, use the Developer Exception Page
        app.UseDeveloperExceptionPage();
    }
    else
    {
        // In Staging/Production, route exceptions to /error
        app.UseExceptionHandler("/error");
    }

    var contentRootPath = env.ContentRootPath;
}

カスタムのミドルウェアを作成する際に、次のように IWebHostEnvironmentInvoke メソッドに挿入することができます。

public async Task Invoke(HttpContext context, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // Configure middleware for Development
    }
    else
    {
        // Configure middleware for Staging/Production
    }

    var contentRootPath = env.ContentRootPath;
}

IHostApplicationLifetime インターフェイス

IHostApplicationLifetime では、起動後とシャットダウンのアクティビティを実行できます。 インターフェイスの 3 つのプロパティは、起動とシャットダウン イベントを定義する Action メソッドを登録するために使用されるキャンセル トークンです。

キャンセル トークン トリガーのタイミング
ApplicationStarted ホストが完全に起動されたとき。
ApplicationStopped ホストが正常なシャットダウンを完了しているとき。 すべての要求を処理する必要があります。 このイベントが完了するまで、シャットダウンはブロックされます。
ApplicationStopping ホストが正常なシャットダウンを行っているとき。 要求がまだ処理されている可能性がある場合。 このイベントが完了するまで、シャットダウンはブロックされます。
public class Startup
{
    public void Configure(IApplicationBuilder app, IHostApplicationLifetime appLifetime)
    {
        appLifetime.ApplicationStarted.Register(OnStarted);
        appLifetime.ApplicationStopping.Register(OnStopping);
        appLifetime.ApplicationStopped.Register(OnStopped);

        Console.CancelKeyPress += (sender, eventArgs) =>
        {
            appLifetime.StopApplication();
            // Don't terminate the process immediately, wait for the Main thread to exit gracefully.
            eventArgs.Cancel = true;
        };
    }

    private void OnStarted()
    {
        // Perform post-startup activities here
    }

    private void OnStopping()
    {
        // Perform on-stopping activities here
    }

    private void OnStopped()
    {
        // Perform post-stopped activities here
    }
}

StopApplication は、アプリの終了を要求します。 以下のクラスは、クラスの Shutdown メソッドが呼び出されると、StopApplication を使ってアプリを正常にシャットダウンします。

public class MyClass
{
    private readonly IHostApplicationLifetime _appLifetime;

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

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

スコープの検証

アプリの環境が開発の場合、CreateDefaultBuilder によって ServiceProviderOptions.ValidateScopestrue に設定されます。

ValidateScopestrue に設定されていると、既定のサービス プロバイダーはチェックを実行して次のことを確認します。

  • スコープ サービスが、ルート サービス プロバイダーによって直接的または間接的に解決されない。
  • スコープ サービスが、シングルトンに直接または間接に挿入されない。

BuildServiceProvider が呼び出されると、ルート サービス プロバイダーが作成されます。 ルート サービス プロバイダーの有効期間は、プロバイダーがアプリで開始されるとアプリとサーバーの有効期間に対応し、アプリのシャットダウンには破棄されます。

スコープ サービスは、それを作成したコンテナーによって破棄されます。 ルート コンテナーにスコープ サービスが作成されると、サービスはアプリ/サーバーのシャットダウン時に、ルート コンテナーによってのみ破棄されるため、サービスの有効期間は実質的にシングルトンに昇格されます。 BuildServiceProvider が呼び出されると、サービス スコープの検証がこれらの状況をキャッチします。

運用環境も含めて、常にスコープを検証するには、ホスト ビルダー上の UseDefaultServiceProviderServiceProviderOptions を構成します。

WebHost.CreateDefaultBuilder(args)
    .UseDefaultServiceProvider((context, options) => {
        options.ValidateScopes = true;
    })

その他の技術情報

ASP.NET Core アプリはホストを構成して起動します。 ホストはアプリの起動と有効期間の管理を担当します。 少なくとも、ホストはサーバーおよび要求処理パイプラインを構成します。 ホストでは、ログ記録、依存関係挿入、構成を設定することもできます。

この記事では、Web ホストについて説明します。これは、下位互換性のためだけに引き続き使用可能となっています。 ASP.NET Core テンプレートを使用すると、すべての種類のアプリに推奨されている .NET での汎用ホストが作成されます。

ホストを設定する

IWebHostBuilder のインスタンスを使用して、ホストを作成します。 通常、これはアプリのエントリ ポイントの Main メソッドで実行されます。

プロジェクト テンプレートでは、MainProgram.cs にあります。 一般的なアプリでは、CreateDefaultBuilder を呼び出してホストの設定を開始します。

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>();
}

CreateDefaultBuilder を呼び出すコードは、CreateWebHostBuilder という名前のメソッドに含まれ、ビルダー オブジェクトで Run を呼び出す Main のコードから分離されています。 Entity Framework Core ツールを使用する場合は、このような分離が必要です。 ツールでは、アプリを実行することなくホストを構成するために、デザイン時に呼び出すことができる CreateWebHostBuilder メソッドの検出が想定されます。 別の方法は、IDesignTimeDbContextFactory を実装することです。 詳細については、「デザイン時 DbContext 作成」をご覧ください。

CreateDefaultBuilder では次のタスクを実行します。

CreateDefaultBuilder によって定義された構成は、ConfigureAppConfigurationConfigureLogging、および IWebHostBuilder の他のメソッドと拡張メソッドによって、オーバーライドおよび拡張できます。 以下に、いくつかの例を示します。

  • ConfigureAppConfiguration は、アプリの追加の IConfiguration を指定するために使用されます。 次の ConfigureAppConfiguration の呼び出しによりデリゲートが追加され、appsettings.xml ファイルにアプリの構成が含まれます。 ConfigureAppConfiguration は複数回呼び出すことができます。 この構成はホスト (たとえば、サーバーの URL や環境など) には適用されないことに注意してください。 「ホストの構成値」のセクションを参照してください。

    WebHost.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
        })
        ...
    
  • 次の ConfigureLogging の呼び出しによりデリゲートが追加され、最小ログ記録レベル (SetMinimumLevel) が LogLevel.Warning に構成されます。 この設定により、CreateDefaultBuilder で構成された appsettings.Development.json (LogLevel.Debug) および appsettings.Production.json (LogLevel.Error) の設定がオーバーライドされます。 ConfigureLogging は複数回呼び出すことができます。

    WebHost.CreateDefaultBuilder(args)
        .ConfigureLogging(logging => 
        {
            logging.SetMinimumLevel(LogLevel.Warning);
        })
        ...
    
  • 次の ConfigureKestrel の呼び出しにより、Kestrel が CreateDefaultBuilder によって構成されたときに確立された既定の Limits.MaxRequestBodySize サイズである 30,000,000 バイトがオーバーライドされます。

    WebHost.CreateDefaultBuilder(args)
        .ConfigureKestrel((context, options) =>
        {
            options.Limits.MaxRequestBodySize = 20000000;
        });
    

コンテンツ ルートで、ホストが MVC ビュー ファイルなどのコンテンツ ファイルを検索する場所を決定します。 プロジェクトのルート フォルダーからアプリが開始された場合は、そのプロジェクトのルート フォルダーがコンテンツ ルートとして使用されます。 これは、Visual Studiodotnet の新しいテンプレートで使用される既定です。

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

Note

静的な CreateDefaultBuilder メソッドを使用する代わりに、WebHostBuilder からホストを作成する方法が ASP.NET Core 2.x でサポートされています。

ホストの構成時に、Configure および ConfigureServices メソッドを指摘することができます。 Startup クラスが指定されている場合は、Configure メソッドを定義する必要があります。 詳細については、「ASP.NET Core でのアプリケーションのスタートアップ」をご覧ください。 ConfigureServices の複数回の呼び出しでは、互いに追加されます。 WebHostBuilder での Configure または UseStartup の複数回の呼び出しでは、以前の設定が置き換えられます。

ホストの構成値

WebHostBuilder では、ホストの構成値を設定する場合に以下の方法に依存します。

  • ASPNETCORE_{configurationKey} 形式の環境変数を含む、ホスト ビルダー構成。 たとえば、ASPNETCORE_ENVIRONMENT のようにします。
  • UseContentRootUseConfiguration などの拡張機能 (「構成をオーバーライドする」セクションを参照)。
  • UseSetting および関連付けられているキー。 UseSetting で値を設定すると、値はその型に関係なく、文字列として設定されます。

ホストは、最後に値を設定したオプションを使用します。 詳しくは、次のセクション「構成をオーバーライドする」をご覧ください。

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

ホストの構築時に UseStartup または Configure が呼び出されると、IWebHostEnvironment.ApplicationName プロパティが自動的に設定されます。 この値はアプリのエントリ ポイントを含むアセンブリの名前に設定されます。 値を明示的に設定するには、WebHostDefaults.ApplicationKey を使用します。

キー: applicationName
: 文字列
既定値:アプリのエントリ ポイントを含むアセンブリの名前。
次を使用して設定: UseSetting
環境変数: ASPNETCORE_APPLICATIONNAME

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")

スタートアップ エラーをキャプチャする

この設定では、スタートアップ エラーのキャプチャを制御します。

キー: captureStartupErrors
: ブール (true または 1)
既定値: アプリが IIS の背後で Kestrel を使用して実行されている場合 (既定値は true) を除き、既定では false に設定されます。
次を使用して設定: CaptureStartupErrors
環境変数: ASPNETCORE_CAPTURESTARTUPERRORS

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

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

コンテンツ ルート

この設定により、ASP.NET Core でコンテンツ ファイルの検索が開始される場所が決まります。

キー: contentRoot
: 文字列
既定:既定でアプリ アセンブリが存在するフォルダーに設定されます。
次を使用して設定: UseContentRoot
環境変数: ASPNETCORE_CONTENTROOT

コンテンツ ルートは、Web ルートの基本パスとしても使用されます。 コンテンツ ルート パスが存在しない場合は、ホストを起動できません。

WebHost.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\<content-root>")

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

詳細なエラー

詳細なエラーをキャプチャするかどうかを判断します。

キー: detailedErrors
: ブール (true または 1)
既定値: false
次を使用して設定: UseSetting
環境変数: ASPNETCORE_DETAILEDERRORS

有効な場合 (または環境Development に設定されている場合)、アプリは詳細な例外をキャプチャします。

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.DetailedErrorsKey, "true")

環境

アプリの環境を設定します。

キー: 環境
: 文字列
既定:実稼働
次を使用して設定: UseEnvironment
環境変数: ASPNETCORE_ENVIRONMENT

環境は任意の値に設定することができます。 フレームワークで定義された値には DevelopmentStagingProduction が含まれます。 値は大文字と小文字が区別されません。 既定では、環境ASPNETCORE_ENVIRONMENT 環境変数から読み取られます。 Visual Studio を使用する場合、環境変数は launchSettings.json ファイルで設定できます。 詳細については、「ASP.NET Core で複数の環境を使用する」を参照してください。

WebHost.CreateDefaultBuilder(args)
    .UseEnvironment(EnvironmentName.Development)

ホスティング スタートアップ アセンブリ

アプリのホスティング スタートアップ アセンブリを設定します。

キー: hostingStartupAssemblies
: 文字列
既定:空の文字列
次を使用して設定: UseSetting
環境変数: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

起動時に読み込むホスティング スタートアップ アセンブリのセミコロンで区切られた文字列。

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

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2")

HTTPS Port

HTTPS リダイレクト ポートを設定します。 HTTPS の適用に使用されます。

キー: https_port
: 文字列
既定:既定値は設定されていません。
次を使用して設定: UseSetting
環境変数: ASPNETCORE_HTTPS_PORTS

WebHost.CreateDefaultBuilder(args)
    .UseSetting("https_port", "8080")

除外するホスティング スタートアップ アセンブリ

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

キー: hostingStartupExcludeAssemblies
: 文字列
既定:空の文字列
次を使用して設定: UseSetting
環境変数: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2")

ホスティング URL を優先する

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

キー: preferHostingUrls
: ブール (true または 1)
既定値: false
次を使用して設定: PreferHostingUrls
環境変数: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(true)

ホスティング スタートアップを回避する

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

キー: preventHostingStartup
: ブール (true または 1)
既定値: false
次を使用して設定: UseSetting
環境変数: ASPNETCORE_PREVENTHOSTINGSTARTUP

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.PreventHostingStartupKey, "true")

サーバーの URL

サーバーが要求をリッスンする必要があるポートとプロトコルを使用して、IP アドレスまたはホスト アドレスを示します。

キー: urls
: 文字列
規定:http://localhost:5000
次を使用して設定: UseUrls
環境変数: ASPNETCORE_URLS

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

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

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

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

Web ホストがシャットダウンするまで待機する時間を指定します。

キー: shutdownTimeoutSeconds
: int
既定:5
次を使用して設定: UseShutdownTimeout
環境変数: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

キーでは UseSetting が指定された int (.UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10") など) を受け入れますが、UseShutdownTimeout 拡張メソッドでは TimeSpan を受け取ります。

タイムアウト期間中、ホスティングは次のことを行います。

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

WebHost.CreateDefaultBuilder(args)
    .UseShutdownTimeout(TimeSpan.FromSeconds(10))

スタートアップ アセンブリ

Startup クラスを検索するアセンブリを決定します。

キー: startupAssembly
: 文字列
既定:アプリのアセンブリ
次を使用して設定: UseStartup
環境変数: ASPNETCORE_STARTUPASSEMBLY

名前 (string) または型 (TStartup) 別のアセンブリを参照できます。 複数の UseStartup メソッドが呼び出された場合は、最後のメソッドが優先されます。

WebHost.CreateDefaultBuilder(args)
    .UseStartup("StartupAssemblyName")
WebHost.CreateDefaultBuilder(args)
    .UseStartup<TStartup>()

Web ルート

アプリの静的資産への相対パスを設定します。

キー: webroot
: 文字列
既定:既定値は、wwwroot です。 {content root}/wwwroot へのパスが存在する必要があります。 パスが存在しない場合は、no-op ファイル プロバイダーが使用されます。
次を使用して設定: UseWebRoot
環境変数: ASPNETCORE_WEBROOT

WebHost.CreateDefaultBuilder(args)
    .UseWebRoot("public")

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

構成をオーバーライドする

Configuration を使用して、Web ホストを構成します。 次の例では、ホスト構成はオプションで hostsettings.json ファイルに指定されます。 hostsettings.json ファイルから読み込まれた構成は、コマンド ライン引数でオーバーライドされる場合があります。 (config の) ビルド構成は、UseConfiguration でホストを構成する場合に使用されます。 IWebHostBuilder 構成はアプリの構成に追加されますが、その逆は当てはまりません。ConfigureAppConfigurationIWebHostBuilder の構成に影響しません。

次のように、UseUrls で指定された構成をオーバーライドします (最初の構成は hostsettings.json、2 番目の構成はコマンドライン引数です)。

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("hostsettings.json", optional: true)
            .AddCommandLine(args)
            .Build();

        return WebHost.CreateDefaultBuilder(args)
            .UseUrls("http://*:5000")
            .UseConfiguration(config)
            .Configure(app =>
            {
                app.Run(context => 
                    context.Response.WriteAsync("Hello, World!"));
            });
    }
}

hostsettings.json:

{
    urls: "http://*:5005"
}

注意

UseConfiguration は、指定された IConfiguration からホスト ビルダーの構成へのキーのみをコピーします。 そのため、JSON、INI、XML 設定のファイルに reloadOnChange: true を設定しても影響はありません。

特定の URL でホストを実行するように指定する場合、dotnet run の実行時にコマンド プロンプトから必要な値を渡すことができます。 コマンドライン引数は hostsettings.json ファイルからの urls 値をオーバーライドし、サーバーはポート 8080 でリッスンします。

dotnet run --urls "http://*:8080"

ホストを管理する

実行

Run メソッドは Web アプリを起動し、ホストがシャットダウンするまで呼び出し元のスレッドをブロックします。

host.Run();

[開始]

Start メソッドを呼び出して、ブロックせずにホストを実行します。

using (host)
{
    host.Start();
    Console.ReadLine();
}

URL のリストが Start メソッドに渡された場合、指定された URL でリッスンします。

var urls = new List<string>()
{
    "http://*:5000",
    "http://localhost:5001"
};

var host = new WebHostBuilder()
    .UseKestrel()
    .UseStartup<Startup>()
    .Start(urls.ToArray());

using (host)
{
    Console.ReadLine();
}

アプリは、便利な静的メソッドを使用し、CreateDefaultBuilder の構成済みの既定値を使用して、新しいホストを初期化して起動できます。 これらのメソッドは、コンソール出力なしでサーバーを起動します。その場合、WaitForShutdown を指定し、中断される (Ctrl-C/SIGINT または SIGTERM) まで待機します。

Start(RequestDelegate app)

次のように RequestDelegate で始まります。

using (var host = WebHost.Start(app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

"Hello World!" という応答を受け取るには、ブラウザで http://localhost:5000 に対する要求を行います。WaitForShutdown は、中断される (Ctrl-C/SIGINT または SIGTERM) までブロックします。 アプリは Console.WriteLine メッセージを表示し、キー入力が終わるまで待機します。

Start(string url, RequestDelegate app)

次のように、URL と RequestDelegate で始まります。

using (var host = WebHost.Start("http://localhost:8080", app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

アプリが http://localhost:8080 で応答する場合を除き、Start(RequestDelegate app) と同じ結果が生成されます。

Start(Action<IRouteBuilder> routeBuilder)

次のように、IRouteBuilder (Microsoft.AspNetCore.Routing) のインスタンスを使用してルーティング ミドルウェアを使用します。

using (var host = WebHost.Start(router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

この例では、以下のブラウザー要求を使用します。

要求 応答
http://localhost:5000/hello/Martin Hello, Martin!
http://localhost:5000/buenosdias/Catrina Buenos dias, Catrina!
http://localhost:5000/throw/ooops! "ooops!" という文字列がある場合は例外をスローします。
http://localhost:5000/throw "Uh oh!" という文字列がある場合は例外をスローします。
http://localhost:5000/Sante/Kevin Sante, Kevin!
http://localhost:5000 Hello World!

WaitForShutdown は、中断される (Ctrl-C/SIGINT または SIGTERM) までブロックします。 アプリは Console.WriteLine メッセージを表示し、キー入力が終わるまで待機します。

Start(string url, Action<IRouteBuilder> routeBuilder)

次のように、URL と IRouteBuilder のインスタンスを使用します。

using (var host = WebHost.Start("http://localhost:8080", router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

アプリが http://localhost:8080 で応答する場合を除き、Start(Action<IRouteBuilder> routeBuilder) と同じ結果が生成されます。

StartWith(Action<IApplicationBuilder> app)

次のように、デリゲートを指定して IApplicationBuilder を構成します。

using (var host = WebHost.StartWith(app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

"Hello World!" という応答を受け取るには、ブラウザで http://localhost:5000 に対する要求を行います。WaitForShutdown は、中断される (Ctrl-C/SIGINT または SIGTERM) までブロックします。 アプリは Console.WriteLine メッセージを表示し、キー入力が終わるまで待機します。

StartWith(string url, Action<IApplicationBuilder> app)

次のように、URL とデリゲートを指定して IApplicationBuilder を構成します。

using (var host = WebHost.StartWith("http://localhost:8080", app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

アプリが http://localhost:8080 で応答する場合を除き、StartWith(Action<IApplicationBuilder> app) と同じ結果が生成されます。

IWebHostEnvironment インターフェイス

IWebHostEnvironment インターフェイスでは、アプリの Web ホスティング環境に関する情報が提供されます。 プロパティと拡張メソッドを使用するには、コンストラクターの挿入を使用して IWebHostEnvironment を取得します。

public class CustomFileReader
{
    private readonly IWebHostEnvironment _env;

    public CustomFileReader(IWebHostEnvironment env)
    {
        _env = env;
    }

    public string ReadFile(string filePath)
    {
        var fileProvider = _env.WebRootFileProvider;
        // Process the file here
    }
}

規則ベースのアプローチを使用して、環境に基づいて起動時にアプリを構成することができます。 あるいは、次のように ConfigureServices で使用するために IWebHostEnvironmentStartup コンストラクターに挿入します。

public class Startup
{
    public Startup(IWebHostEnvironment env)
    {
        HostingEnvironment = env;
    }

    public IWebHostEnvironment HostingEnvironment { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        if (HostingEnvironment.IsDevelopment())
        {
            // Development configuration
        }
        else
        {
            // Staging/Production configuration
        }

        var contentRootPath = HostingEnvironment.ContentRootPath;
    }
}

Note

IsDevelopment 拡張メソッドに加え、IWebHostEnvironmentIsStagingIsProductionIsEnvironment(string environmentName) メソッドを提供します。 詳細については、「ASP.NET Core で複数の環境を使用する」を参照してください。

処理パイプラインを設定するために、次のように IWebHostEnvironment サービスを Configure メソッドに直接挿入することもできます。

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // In Development, use the Developer Exception Page
        app.UseDeveloperExceptionPage();
    }
    else
    {
        // In Staging/Production, route exceptions to /error
        app.UseExceptionHandler("/error");
    }

    var contentRootPath = env.ContentRootPath;
}

カスタムのミドルウェアを作成する際に、次のように IWebHostEnvironmentInvoke メソッドに挿入することができます。

public async Task Invoke(HttpContext context, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // Configure middleware for Development
    }
    else
    {
        // Configure middleware for Staging/Production
    }

    var contentRootPath = env.ContentRootPath;
}

IHostApplicationLifetime インターフェイス

IHostApplicationLifetime では、起動後とシャットダウンのアクティビティを実行できます。 インターフェイスの 3 つのプロパティは、起動とシャットダウン イベントを定義する Action メソッドを登録するために使用されるキャンセル トークンです。

キャンセル トークン トリガーのタイミング
ApplicationStarted ホストが完全に起動されたとき。
ApplicationStopped ホストが正常なシャットダウンを完了しているとき。 すべての要求を処理する必要があります。 このイベントが完了するまで、シャットダウンはブロックされます。
ApplicationStopping ホストが正常なシャットダウンを行っているとき。 要求がまだ処理されている可能性がある場合。 このイベントが完了するまで、シャットダウンはブロックされます。
public class Startup
{
    public void Configure(IApplicationBuilder app, IHostApplicationLifetime appLifetime)
    {
        appLifetime.ApplicationStarted.Register(OnStarted);
        appLifetime.ApplicationStopping.Register(OnStopping);
        appLifetime.ApplicationStopped.Register(OnStopped);

        Console.CancelKeyPress += (sender, eventArgs) =>
        {
            appLifetime.StopApplication();
            // Don't terminate the process immediately, wait for the Main thread to exit gracefully.
            eventArgs.Cancel = true;
        };
    }

    private void OnStarted()
    {
        // Perform post-startup activities here
    }

    private void OnStopping()
    {
        // Perform on-stopping activities here
    }

    private void OnStopped()
    {
        // Perform post-stopped activities here
    }
}

StopApplication は、アプリの終了を要求します。 以下のクラスは、クラスの Shutdown メソッドが呼び出されると、StopApplication を使ってアプリを正常にシャットダウンします。

public class MyClass
{
    private readonly IHostApplicationLifetime _appLifetime;

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

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

スコープの検証

アプリの環境が開発の場合、CreateDefaultBuilder によって ServiceProviderOptions.ValidateScopestrue に設定されます。

ValidateScopestrue に設定されていると、既定のサービス プロバイダーはチェックを実行して次のことを確認します。

  • スコープ サービスが、ルート サービス プロバイダーによって直接的または間接的に解決されない。
  • スコープ サービスが、シングルトンに直接または間接に挿入されない。

BuildServiceProvider が呼び出されると、ルート サービス プロバイダーが作成されます。 ルート サービス プロバイダーの有効期間は、プロバイダーがアプリで開始されるとアプリとサーバーの有効期間に対応し、アプリのシャットダウンには破棄されます。

スコープ サービスは、それを作成したコンテナーによって破棄されます。 ルート コンテナーにスコープ サービスが作成されると、サービスはアプリ/サーバーのシャットダウン時に、ルート コンテナーによってのみ破棄されるため、サービスの有効期間は実質的にシングルトンに昇格されます。 BuildServiceProvider が呼び出されると、サービス スコープの検証がこれらの状況をキャッチします。

運用環境も含めて、常にスコープを検証するには、ホスト ビルダー上の UseDefaultServiceProviderServiceProviderOptions を構成します。

WebHost.CreateDefaultBuilder(args)
    .UseDefaultServiceProvider((context, options) => {
        options.ValidateScopes = true;
    })

その他の技術情報