ASP.NET Core Blazor 環境

この記事では、Blazor アプリで環境を構成して読み取る方法について説明します。

アプリをローカルで実行すると、環境は既定で Developmentされます。 アプリが発行されると、環境は既定で Productionされます。

次の規則をお勧めします。

• ローカル開発には常に "Development" 環境名を使用します。 これは、ASP.NET Core フレームワークは、アプリのローカル開発実行用にアプリとツールを構成するときに、その名前を正確に想定しているためです。

• テスト、ステージング、運用環境の場合は、常にアプリを発行してデプロイします。 発行されたアプリに必要な任意の環境名前付けスキームを使用できますが、常に、環境名と完全に一致する環境セグメントの大文字と小文字を区別してアプリ設定ファイル名を使用します。 ステージングの場合は、環境名として "Staging" (大文字の "S") を使用し、一致するアプリ設定ファイルに名前を付けます (appsettings.Staging.json)。 運用環境では、環境名として "Production" (大文字の "P") を使用し、一致するアプリ設定ファイルに名前を付けます (appsettings.Production.json)。

環境を設定する

環境は、次のいずれかの方法を使用して設定されます。

• Blazor Web App または Blazor Server: 一般的な ASP.NET Core アプリの場合は、「 ASP.NET Core で複数の環境を使用 する」で説明されている方法のいずれかを使用します。
• 任意の Blazor アプリ:
  • Blazor 構成の開始
  • Azure App Service
• Blazor WebAssembly: ヘッダーBlazor-Environment

Blazor Web Appのクライアントでは、環境は、Blazor-Environmentという名前のヘッダーを介してブラウザーに環境を通信するミドルウェアを介してサーバーから決定されます。 ヘッダーは、クライアント側のProgram ファイル (WebAssemblyHostBuilder.CreateDefault) にWebAssemblyHostが作成されるときに環境を設定します。

ローカルで実行されているスタンドアロン Blazor WebAssembly アプリの場合、開発サーバーは、ホスティング環境から取得した環境名を持つ Blazor-Environment ヘッダーを追加します。 ホスティング環境は、プロジェクトのProperties/launchSettings.json ファイルによって確立されたASPNETCORE_ENVIRONMENT環境変数から環境を設定します。 Blazor WebAssembly プロジェクト テンプレートから作成されたプロジェクトの環境変数の既定値はDevelopment。 詳細については、「 ヘッダーを使用してクライアント側環境を設定する 」セクションを参照してください。

開発中にアプリがローカルで実行されている場合、アプリは既定で Development 環境に設定されます。 アプリを発行すると、既定で環境が Productionされます。

スタートアップ構成を使用してクライアント側環境 Blazor 設定する

次の例では、ホスト名にlocalhostが含まれている場合、Staging環境でBlazorを開始します。 それ以外の場合、環境は既定値に設定されます。

Blazor Web App:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  if (window.location.hostname.includes("localhost")) {
    Blazor.start({
      webAssembly: {
        environment: "Staging"
      }
    });
  } else {
    Blazor.start();
  }
</script>

前の例の {BLAZOR SCRIPT} プレースホルダーは、Blazor スクリプトのパスとファイル名です。 スクリプトの場所については、「ASP.NET Core Blazor プロジェクトの構造」を参照してください。

注

Blazor.start構成で webAssembly>environment プロパティを設定するBlazor Web Appの場合は、サーバー側環境を environment プロパティに設定された環境と一致させるのが賢明です。 それ以外の場合、サーバーでのプリレンダリングは、クライアントでのレンダリングとは異なる環境で動作し、結果として任意の効果が得られます。 Blazor Web Appの環境の設定に関する一般的なガイダンスについては、「ASP.NET Core で複数の環境を使用する」を参照してください。

スタンドアロン Blazor WebAssembly:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  if (window.location.hostname.includes("localhost")) {
    Blazor.start({
      environment: "Staging"
    });
  } else {
    Blazor.start();
  }
</script>

前の例の {BLAZOR SCRIPT} プレースホルダーは、Blazor スクリプトのパスとファイル名です。 スクリプトの場所については、「ASP.NET Core Blazor プロジェクトの構造」を参照してください。

environment プロパティを使用すると、Blazor-Environment ヘッダーによって設定された環境がオーバーライドされます。

上記の方法では、 Blazor-Environment ヘッダーの値を変更せずにクライアントの環境を設定し、グローバルな Interactive WebAssembly レンダリングを採用した Blazor Web App のスタートアップ環境のサーバー プロジェクトのコンソール ログも変更しません。

スタンドアロン Blazor WebAssembly アプリまたはBlazor Web Appの.Client プロジェクトのいずれかで環境をコンソールに記録するには、WebAssemblyHostBuilder.CreateDefaultでWebAssemblyHostが作成された後、プロジェクトをビルドして実行する行の前に次の C# コードをProgram ファイルに配置します (await builder.Build().RunAsync();)。

Console.WriteLine(
    $"Client Hosting Environment: {builder.HostEnvironment.Environment}");

Blazor の起動の詳細については、「ASP.NET Core Blazor の起動」をご覧ください。

ヘッダーを使用してクライアント側環境を設定する

Blazor WebAssembly アプリは、 Blazor-Environment ヘッダーを使用して環境を設定できます。 具体的には、 _framework/blazor.boot.json ファイルに応答ヘッダーを設定する必要がありますが、他の Blazor ファイル要求または Blazor 展開全体に対するファイル サーバーの応答にヘッダーを設定しても問題はありません。

Blazor フレームワークでは、大文字と小文字が混合するケバブ ケース (Blazor-Environment)で、ヘッダー名を発行しますが、すべて大文字またはすべて小文字のケバブ ケース (blazor-environment、BLAZOR-ENVIRONMENT) を使用することもできます。

Blazorの組み込み開発サーバーを使用してローカル開発を実行する場合は、プロジェクトのProperties/launchSettings.json ファイルでASPNETCORE_ENVIRONMENT環境変数の値を設定することで、Blazor-Environment ヘッダーの値を制御できます。 開発サーバーでローカルに実行する場合、アプリの環境を決定するための優先順位は、構成 (environment キー) >Blazor-Environment応答ヘッダー (blazor.boot.json ファイル) >ASPNETCORE_ENVIRONMENT環境変数 (launchSettings.json) Blazor.startです。 デプロイされたBlazor WebAssembly アプリには、ASPNETCORE_ENVIRONMENT環境変数 (launchSettings.json) アプローチを使用することはできません。 この手法は、アプリのローカル実行時に開発サーバーでのみ機能します。

IIS

IIS の次の例では、カスタム ヘッダー (Blazor-Environment) が発行された web.config ファイルに追加されます。 web.config ファイルは bin/Release/{TARGET FRAMEWORK}/publish フォルダーにあり、{TARGET FRAMEWORK} プレースホルダーはターゲット フレームワークです。

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    ...
    <httpProtocol>
      <customHeaders>
        <add name="Blazor-Environment" value="Staging" />
      </customHeaders>
    </httpProtocol>
  </system.webServer>
</configuration>

注

アプリが publish フォルダーに発行されたときに上書きされない IIS 用のカスタム web.config ファイルを使用するには、「IIS で Core Blazor WebAssemblyASP.NET ホストして展開する」を参照してください。

Nginx

Nginx サーバーの場合は、ngx_http_headers_moduleの add_header ディレクティブを使用します。

http {
    server {
        ...
        location / {
            ...
            add_header Blazor-Environment "Staging";
        }
    }
}

詳細については、次のリソースを参照してください。

• Nginx のドキュメント
• Nginx を使用 ASP.NET Core Blazor WebAssembly をホストしてデプロイする

Apache

Apache サーバーの場合は、mod_headers モジュールの Header ディレクティブを使用します。

<VirtualHost *:80>
    ...
    Header set Blazor-Environment "Staging"
    ...
</VirtualHost>

詳細については、次のリソースを参照してください。

• Apache ドキュメント (最新リリースで "mod_headers" を検索)
• Apache を使用 ASP.NET Core Blazor WebAssembly をホストしてデプロイする

Azure App Service の環境を設定する

スタンドアロン Blazor WebAssembly アプリの場合は、 開始構成 または Blazor-Environment ヘッダーを使用して環境を手動で設定できます。

サーバー側アプリの場合は、Azure の ASPNETCORE_ENVIRONMENT アプリ設定を使用して環境を設定します。

1. アプリ設定ファイル名内の環境セグメントの大文字と小文字が、その環境名の大文字と小文字と完全に一致することを確認します。 たとえば、 Staging 環境の一致するアプリ設定ファイル名は appsettings.Staging.json。 ファイル名が appsettings.staging.json (小文字の "s") の場合、ファイルは見つからないので、ファイル内の設定は Staging 環境では使用されません。

2. Visual Studio のデプロイの場合は、アプリが正しいデプロイ スロットにデプロイされていることを確認します。 BlazorAzureAppSampleという名前のアプリの場合、アプリは Staging デプロイ スロットにデプロイされます。

3. 環境のデプロイ スロットの Azure portal で、 ASPNETCORE_ENVIRONMENT アプリ設定を使用して環境を設定します。 BlazorAzureAppSampleという名前のアプリの場合、ステージング App Service スロットには BlazorAzureAppSample/Staging という名前が付けられます。 Staging スロットの構成では、ASPNETCORE_ENVIRONMENT のアプリ設定を Staging の値で作成します。 デプロイ スロットの設定 は、この設定に対して有効になっています。

ブラウザーで要求されると、BlazorAzureAppSample/Staging アプリはhttps://blazorazureappsample-staging.azurewebsites.netのStaging環境に読み込まれます。

アプリがブラウザーに読み込まれると、 blazor.boot.json の応答ヘッダー コレクションは、 Blazor-Environment ヘッダー値が Stagingされていることを示します。

appsettings.{ENVIRONMENT}.json ファイルのアプリ設定はアプリによって読み込まれます。ここで、{ENVIRONMENT} プレースホルダーはアプリの環境です。 前の例では、 appsettings.Staging.json ファイルの設定が読み込まれます。

Blazor WebAssembly アプリで環境を読み取る

IWebAssemblyHostEnvironmentを挿入し、Environment プロパティを読み取って、コンポーネント内のアプリの環境を取得します。

ReadEnvironment.razor:

@page "/read-environment"
@using Microsoft.AspNetCore.Components.WebAssembly.Hosting
@inject IWebAssemblyHostEnvironment Env

<h1>Environment example</h1>

<p>Environment: @Env.Environment</p>

Blazor Web App で、環境クライアント側を読み取ります。

コンポーネントまたはアプリに対してプリレンダリングが無効になっていないと仮定すると、 .Client プロジェクト内のコンポーネントがサーバー上でプリレンダリングされます。 サーバーには登録済みの IWebAssemblyHostEnvironment サービスがないため、サーバーのプリレンダリング中にサービスを挿入し、サービス実装のホスト環境拡張メソッドとプロパティを使用することはできません。 対話型 WebAssembly または対話型自動コンポーネントにサービスを挿入すると、次のランタイム エラーが発生します。

There is no registered service of type 'Microsoft.AspNetCore.Components.WebAssembly.Hosting.IWebAssemblyHostEnvironment'.

これに対処するには、サーバー上の IWebAssemblyHostEnvironment 用のカスタム サービス実装を作成します。 サーバー プロジェクトに次のクラスを追加します。

ServerHostEnvironment.cs:

using Microsoft.AspNetCore.Components.WebAssembly.Hosting;
using Microsoft.AspNetCore.Components;

public class ServerHostEnvironment(IWebHostEnvironment env, NavigationManager nav) : 
    IWebAssemblyHostEnvironment
{
    public string Environment => env.EnvironmentName;
    public string BaseAddress => nav.BaseUri;
}

サーバー プロジェクトの Program ファイルで、サービスを登録します。

builder.Services.TryAddScoped<IWebAssemblyHostEnvironment, ServerHostEnvironment>();

この時点で、IWebAssemblyHostEnvironment サービスを対話型の WebAssembly または対話型の自動コンポーネントに挿入し、「Blazor WebAssembly アプリの環境の読み取り」セクションに示すように使用できます。

前の例では、クライアント環境とは異なるサーバー環境を使用できる可能性があることを示しています。これは推奨されておらず、任意の結果につながる可能性があります。 Blazor Web Appで環境を設定する場合は、サーバー環境と.Clientプロジェクト環境を照合することをお勧めします。 テスト アプリで次のシナリオを考えてみましょう。

• Blazor.startを使用して、Staging環境でクライアント側 (webassembly) 環境プロパティを実装します。 例については、「 スタートアップ構成を使用してクライアント側環境を設定 する」セクションを参照してください。
• サーバー側の Properties/launchSettings.json ファイルは変更しないでください。 environmentVariablesセクションは、ASPNETCORE_ENVIRONMENT環境変数をDevelopmentに設定したままにします。

UI では、 IWebAssemblyHostEnvironment.Environment プロパティの値の変更を確認できます。

サーバーでプリレンダリングが行われると、コンポーネントは Development 環境にレンダリングされます。

Environment:Development

コンポーネントが 1 秒または 2 秒後に再レンダリングされると、 Blazor バンドルがダウンロードされ、.NET WebAssembly ランタイムがアクティブになると、クライアントがクライアントの Staging 環境で動作していることを反映するように値が変更されます。

Environment:Staging

前の例では、開発、テスト、運用の展開でクライアント環境と一致するようにサーバー環境を設定することをお勧めする理由を示します。

詳細については、レンダー モードに関する記事の「プリレンダリング中にクライアント側サービスの解決に失敗する」を参照してください。詳細については、Blazorドキュメントの後半で説明します。

起動時にクライアント側環境を読み取る

起動時に、WebAssemblyHostBuilderは HostEnvironment プロパティを介してIWebAssemblyHostEnvironmentを公開します。これにより、ホスト ビルダー コードで環境固有のロジックが有効になります。

Program ファイルで次の操作を行います。

if (builder.HostEnvironment.Environment == "Custom")
{
    ...
};

WebAssemblyHostEnvironmentExtensionsによって提供される次の便利な拡張メソッドでは、現在の環境でDevelopment、Production、Staging、カスタム環境の名前を確認できます。

• IsDevelopment
• IsProduction
• IsStaging
• IsEnvironment

Program ファイルで次の操作を行います。

if (builder.HostEnvironment.IsStaging())
{
    ...
};

if (builder.HostEnvironment.IsEnvironment("Custom"))
{
    ...
};

IWebAssemblyHostEnvironment.BaseAddress プロパティは、NavigationManager サービスが使用できない場合に起動時に使用できます。

その他のリソース

• ASP.NET Core Blazor の起動
• ASP.NET Core で複数の環境を使用する
• Blazor サンプル GitHub リポジトリ (dotnet/blazor-samples) (ダウンロード方法)