ASP.NET Core ランタイム環境

ASP.NET Core は、ランタイム 環境に基づいてアプリの動作を構成します。これは通常、アプリが実行されている場所を反映します。

アプリは 通常、ローカル 開発時および開発者のコンピューターでのテスト中に開発環境で実行され、1 セットの動作が構成されています。 これに対し、構成された動作のセットが異なるサーバーにデプロイされると、 運用環境 で実行されます。 ライブ デプロイの前にアプリをステージングするためのフレームワークによって提供される ステージング 環境や、開発者が作成する他の環境など、任意の数の追加環境を使用できます。

この記事では、アプリ ランタイム環境、環境を使用してアプリの動作を制御する方法、環境を設定する方法について説明します。

この記事のガイダンスに追加されるまたは優先する Blazor 環境のガイダンスについては、「ASP.NET Core Blazor の環境」をご覧ください。

Environments

環境には任意の文字列値を指定できますが、フレームワークによって次の環境値が提供されます。

• Development
• Staging
• Production

運用環境は、セキュリティ、パフォーマンス、アプリの信頼性を最大化するように構成されています。 開発環境とは異なる一般的な開発者設定と構成は次のとおりです。

• キャッシュの有効化。
• クライアント側リソースをバンドルおよび縮小し、CDN から提供する可能性があります。
• 診断エラー ページを無効にし、わかりやすいエラー ページを有効にします。
• 運用環境のログ記録と監視を有効にする。 たとえば、 Azure Application Insights ではログ記録が有効になっています。

アプリによって最後に読み取られた環境設定によって、アプリの環境が決まります。 アプリの実行中にアプリの環境を変更することはできません。

ロギング（記録）

起動時に実行中のアプリのコマンド シェルでの出力は、アプリの環境を示します。 次の例では、アプリはステージング環境で実行されています。

info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Staging

ランタイム環境を決定する環境変数

ランタイム環境を決定するために、ASP.NET Core では次の環境変数が読み取られます。

DOTNET_ENVIRONMENT環境変数とASPNETCORE_ENVIRONMENT環境変数が設定されていない場合、運用環境が既定の環境になります。

Windows と macOS では、環境変数の名前では大文字と小文字は区別されません。 Linux 環境変数では、大文字と小文字が区別されます。

環境によるコード実行の制御

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    if (env.IsProduction() || env.IsStaging() || env.IsEnvironment("Testing"))
    {
        app.UseExceptionHandler("/Error");
    }

    ...
}

アプリ内では、 IHostEnvironment はアプリのホスティング環境に関する一般的な情報を提供し、 IHostEnvironment.EnvironmentName プロパティはアプリの現在の環境を示します。

レンダリングされたコンテンツを制御する

サーバーでレンダリングされたIHostEnvironment コンポーネントにRazorを挿入し、サービスの拡張メソッドとEnvironmentName プロパティを使用して、コンテンツをレンダリングする環境を決定します。

@inject IHostEnvironment Env

@if (Env.IsDevelopment())
{
    <div>The environment is Development.</div>
}

@if (!Env.IsDevelopment())
{
    <div>The environment isn't Development.</div>
}

@if (Env.IsStaging() || Env.EnvironmentName == "Testing")
{
    <div>The environment is either Staging or Testing.</div>
}

環境でクライアント側のレンダリングを制御する必要がある Blazor Web Appについては、「 Prerender ASP.NET Core Razor コンポーネント」を参照してください。

アプリの実行時にコマンド シェルで環境を設定する (dotnet run)

-e|--environment オプションを使用して、環境を設定します。

dotnet run -e Staging

起動設定ファイルを使用して環境を設定する (launchSettings.json)

ローカル開発の環境は、プロジェクトの Properties\launchSettings.json ファイルで設定できます。 launchSettings.jsonに設定された環境値は、システム環境によって設定された値をオーバーライドします。

launchSettings.json ファイルは以下の通りです。

• ローカルの開発用コンピューターでのみ使用されます。
• アプリが発行されるときにデプロイされません。
• 複数のプロファイルを含め、それぞれ異なる環境を構成できます。

次の例では、https環境変数を使用して、ASPNETCORE_ENVIRONMENT起動プロファイルのステージング環境を設定します。

"https": {
  "commandName": "Project",
  "dotnetRunMessages": true,
  "launchBrowser": true,
  "applicationUrl": "https://localhost:7205",
  "environmentVariables": {
    "ASPNETCORE_ENVIRONMENT": "Staging"
  }
}

Visual Studio では、起動プロファイルを使用して環境を設定するための 2 つの方法があります。

• Alt キー+Enter キーを押すか、ソリューション エクスプローラーでプロジェクトを右クリックした後で [プロパティ] を選択します。 [デバッグ>General] を選択し、[デバッグ起動プロファイルを開く] UI リンクを選択します。

• ソリューション エクスプローラーでプロジェクトを選択した状態で、[デバッグ] メニューの {PROJECT NAME} [デバッグ プロパティ] を選択します。ここで、 プレースホルダーはプロジェクト名です。{PROJECT NAME}

上記の方法では、[ プロファイルの起動 ] ダイアログが開き、 launchSettings.json ファイル内の環境変数の設定を編集できます。 プロジェクト プロファイルを変更した場合、Web サーバーを再起動するまで変更は適用されません。 Kestrel がその環境に行われた変更を検出するには、先に再起動する必要があります。

[スタート] ボタン (►) の横にある Visual Studio UI でプロファイルを選択できます。

ソリューションに複数のプロジェクトが含まれている場合は、スタートアップ プロジェクトの環境のみを設定します。

それ以外の場合は、 オプションをプロファイルの名前に設定して、 コマンドを使用します。 この方法では、 Project コマンドに基づく起動プロファイルのみがサポートされます。

dotnet run -lp "https"

Visual Studio Code用 C# 開発キットで Visual Studio Code を使用する場合 (VS Code での C# の概要)、起動プロファイルはアプリのlaunchSettings.json ファイルから取得されます。

C# 開発キットが使用されていない場合は、ASPNETCORE_ENVIRONMENT セクションの.vscode/launch.jsonのenv環境変数と、セクションで設定したその他の環境変数を設定します。

"env": {
    "ASPNETCORE_ENVIRONMENT": "Staging",
    ...
},

.vscode/launch.json ファイルは Visual Studio Code によってのみ使用されます。

環境変数を使用して環境を設定する

環境変数またはプラットフォームの設定を使用してテスト用の特定の環境を設定すると、便利な場合がよくあります。 環境が設定されていない場合は、既定で運用環境に設定され、ほとんどのデバッグ機能が無効になります。 環境を設定する手法は、オペレーティング システムによって異なります。

Azure App Service

Azure App Service にデプロイされたアプリは、既定で運用環境を採用します。

ASPNETCORE_ENVIRONMENT環境変数を設定するには、Azure ドキュメントの次のリソースを参照してください。

• App Service アプリを構成する
• Azure App Service でステージング環境を設定する

アプリ設定が追加、変更、または削除された後、Azure App Service によってアプリが自動的に再起動されます。

プロセスの環境変数を設定する

ASPNETCORE_ENVIRONMENTを使用してアプリを起動するときに、現在のセッション (コマンド シェル) のdotnet run環境変数を設定するには、次のコマンドを使用します。 環境変数が設定されると、 --no-launch-profile オプションを使用して起動プロファイルなしでアプリが開始されます。

1. コマンド シェルで、オペレーティング システムに適した方法を使用して環境変数を設定します。

2. 起動プロファイルを使用せずに dotnet run コマンドを実行します。

   dotnet run --no-launch-profile
   

PowerShell を使用する場合は、上記の手順を次の 2 つのコマンドで組み合わせることができます。 次の例では、ステージング環境を設定します。

$Env:ASPNETCORE_ENVIRONMENT = "Staging"
dotnet run --no-launch-profile

環境変数をグローバルに設定する

オペレーティング システムに適切なガイダンスを使用して、 ASPNETCORE_ENVIRONMENT 環境変数を設定します。

ASPNETCORE_ENVIRONMENT環境変数がグローバルに設定されると、値の設定後に開かれたコマンド シェルの dotnet run コマンドに対して有効になります。 launchSettings.json ファイル内の起動プロファイルによって設定された環境値は、システム環境に設定された値をオーバーライドします。

IIS に展開されるアプリの環境を設定する

ASPNETCORE_ENVIRONMENT ファイルでweb.config環境変数を設定するには、web.config ファイルを参照してください。

デプロイ時に環境変数を IIS に設定するには、<EnvironmentName> またはプロジェクト ファイルに プロパティを含めます。 次の例では、プロジェクトの発行時に、 web.config 内の環境をステージング環境に設定します。

<PropertyGroup>
  <EnvironmentName>Staging</EnvironmentName>
</PropertyGroup>

分離されたアプリケーション プール (IIS 10.0 以降でサポートされている) で実行されているアプリの ASPNETCORE_ENVIRONMENT 環境変数を設定するには、「 環境変数 <environmentVariables>を参照してください。 ASPNETCORE_ENVIRONMENT環境変数がアプリケーション プールに設定されている場合、その値はシステム レベルの設定をオーバーライドします。

IIS でアプリをホストし、 ASPNETCORE_ENVIRONMENT 環境変数を追加または変更する場合は、次 のいずれかの 方法を使用して、アプリの実行に新しい値を有効にします。

• net stop was /y実行し、コマンド シェルでnet start w3svcを実行します。
• サーバーを再起動します。

Docker

このセクションのいずれかの方法を使用して、アプリの環境を設定します。

Dockerfile を使用する

ASPNETCORE_ENVIRONMENT命令を使用して、Dockerfile 内でENV環境変数を設定します。

ENV ASPNETCORE_ENVIRONMENT=Staging

Docker Compose を使用する

Docker Compose で管理されるマルチサービス アプリの場合は、ASPNETCORE_ENVIRONMENT ファイル内docker-compose.yml環境変数を定義します。

version: "3.9"
services:
  web:
    build: .
    ports:
      - "8000:5000"
    environment:
      - ASPNETCORE_ENVIRONMENT=Staging
      - API_KEY=...

実行時に Docker Compose で設定された環境は、Dockerfile によって設定された環境をオーバーライドします。

docker run コマンドを使用する

docker run コマンドを使用して Docker コンテナーを実行する場合は、ASPNETCORE_ENVIRONMENT オプションを使用して-e|--env環境変数を設定します。

docker run -e ASPNETCORE_ENVIRONMENT=Staging aspnet_core_image

docker runを使用して実行時に設定された環境は、Dockerfile によって設定された環境をオーバーライドします。

Docker 環境ファイル

Docker 環境ファイル (ASPNETCORE_ENVIRONMENT) を使用して、.env環境変数を設定します。

env_variables.env:

ASPNETCORE_ENVIRONMENT=Staging

docker run コマンドを実行する際に、--env-file オプションを使用してファイルを読み込みます。

docker run --env-file ./env_variables.env aspnet_core_image

docker runを使用して実行時に設定された環境は、Dockerfile によって設定された環境をオーバーライドします。

アプリのスタートアップ コードで環境を設定する

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    EnvironmentName = Environments.Staging
}); 

環境別に構成を読み込む

環境別の構成を読み込むには、「ASP.NET Core の構成」を参照してください。

Startup クラスから環境にアクセスする

.NET 6 のリリース前は、Startup メソッドとStartup.cs メソッドを使用したConfigure クラス (ConfigureServices) の使用が必要であり、サポートされたままです。

コードの実行を制御するために、 IWebHostEnvironment を Startup コンストラクターに挿入します。 この方法は、アプリで、環境ごとのコードの違いが最小限の少数の環境に対してのみスタートアップ コードを構成する必要がある場合に便利です。

次の例では、環境は _env フィールドに保持され、アプリの環境に基づいてコードの実行を制御します。

public class Startup
{
    private readonly IWebHostEnvironment _env;

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

    public void ConfigureServices(IServiceCollection services)
    {
        if (_env.IsDevelopment())
        {
            ...
        }
        else if (_env.IsStaging())
        {
            ...
        }
        else
        {
            ...
        }
    }

    public void Configure(IApplicationBuilder app)
    {
        if (_env.IsDevelopment())
        {
            ...
        }
        else
        {
            ...
        }

        ...
    }
}

環境固有の Startup クラス

アプリでは、Startup プレースホルダーが環境名である名前付け規則Startup{EnvironmentName}クラスを使用して、さまざまな環境に対して複数の{ENVIRONMENT NAME} クラスを定義できます。

名前のサフィックスが現在の環境と一致するクラスが優先されます。 一致する Startup{EnvironmentName} クラスが見つからない場合、Startup クラスが使用されます。

環境ベースの Startup クラスを実装するには、必要な数の Startup{EnvironmentName} クラスとフォールバック Startup クラスを作成します。

public class StartupDevelopment
{
    ...
}

public class StartupProduction
{
    ...
}

public class Startup
{
    ...
}

ホスト ビルダーが作成されたら、アセンブリ名を受け入れる HostingAbstractionsWebHostBuilderExtensions.UseStartup を呼び出して、適切な Startup クラスを読み込みます。

public static IHostBuilder CreateHostBuilder(string[] args)
{
    var assemblyName = typeof(Startup).GetTypeInfo().Assembly.FullName;

    return Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup(assemblyName);
        });
}

環境固有の Startup クラス メソッド

ConfigureメソッドとConfigureServices メソッドは、環境固有のバージョンのフォーム Configure{ENVIRONMENT NAME}とConfigure{ENVIRONMENT NAME}Servicesをサポートします。ここで、{ENVIRONMENT NAME}プレースホルダーは環境名です。 名前付きメソッドに一致する環境名が見つからない場合は、 ConfigureServices または Configure メソッドがそれぞれ使用されます。

public void ConfigureDevelopmentServices(IServiceCollection services)
{
    ...
}

public void ConfigureStagingServices(IServiceCollection services)
{
    ...
}

public void ConfigureProductionServices(IServiceCollection services)
{
    ...
}

public void ConfigureServices(IServiceCollection services)
{
    ...
}

その他のリソース

• サンプル コードを表示またはダウンロードします (ダウンロード方法)。
• ASP.NET Core でのアプリケーションのスタートアップ
• ASP.NET Core での構成
• ASP.NET Core Blazor の環境