ASP.NET Core Blazor の起動

2025-04-10

注

これは、この記事の最新バージョンではありません。現在のリリースについては、この記事の .NET 9 バージョンを参照してください。

警告

このバージョンの ASP.NET Core はサポート対象から除外されました。詳細については、 .NET および .NET Core サポートポリシーを参照してください。現在のリリースについては、この記事の .NET 9 バージョンを参照してください。

重要

この情報はリリース前の製品に関する事項であり、正式版がリリースされるまでに大幅に変更される可能性があります。 Microsoft はここに示されている情報について、明示か黙示かを問わず、一切保証しません。

現在のリリースについては、この記事の .NET 9 バージョンを参照してください。

この記事では、Blazor アプリの起動構成について説明します。

サーバー側開発用の ASP.NET Core アプリの構成に関する一般的なガイダンスについては、「ASP.NET Core の構成」をご覧ください。

スタートアッププロセスと構成

Blazor 起動プロセスは、Blazor スクリプト (blazor.*.js) を介して自動かつ非同期に行われます。ここで、* プレースホルダーは次を示します。

web (Blazor Web App の場合)
server (Blazor Server アプリの場合)
webassembly (Blazor WebAssembly アプリの場合)

Blazor 起動プロセスは、Blazor スクリプト (blazor.*.js) を介して自動かつ非同期に行われます。ここで、* プレースホルダーは次を示します。

server (Blazor Server アプリの場合)
webassembly (Blazor WebAssembly アプリの場合)

スクリプトの場所については、「ASP.NET Core Blazor プロジェクトの構造」を参照してください。

Blazor を手動で開始するには:

Blazor Web App:

autostart="false" 属性と値を Blazor<script> タグに追加します。
Blazor.start() を呼び出すスクリプトを、Blazor<script> タグの後の終了 </body> タグ内に配置します。
静的サーバー側レンダリング (静的 SSR) オプションを ssr プロパティに配置します。
サーバー側 Blazor-SignalR 回線オプションを circuit プロパティに配置してください。
クライアント側の WebAssembly オプションを webAssembly プロパティに配置してください。

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  ...
  Blazor.start({
    ssr: {
      ...
    },
    circuit: {
      ...
    },
    webAssembly: {
      ...
    }
  });
  ...
</script>

スタンドアロンの Blazor WebAssembly と Blazor Server:

autostart="false" 属性と値を Blazor<script> タグに追加します。
Blazor.start() を呼び出すスクリプトを、Blazor<script> タグの後の終了 </body> タグ内に配置します。
Blazor.start() パラメータには追加のオプションを指定できます。

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  ...
  Blazor.start({
    ...
  });
  ...
</script>

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

JavaScript イニシャライザー

JavaScript (JS) イニシャライザーによって、Blazor アプリの読み込みの前後にロジックが実行されます。 JS イニシャライザーは、次のシナリオで役に立ちます。

Blazor アプリの読み込み方法のカスタマイズ。
Blazor 開始前のライブラリの初期化。
Blazor の設定を構成中です。

JS イニシャライザーは、ビルドプロセスの一部として検出されて、自動的にインポートされます。多くの場合、JS イニシャライザーを使用すると、を使用するときにRazor必要がなくなります。

JS イニシャライザーを定義するには、JS モジュールを {NAME}.lib.module.js という名前のプロジェクトに追加します。{NAME} プレースホルダーは、アセンブリ名、ライブラリ名、またはパッケージ識別子です。ファイルをプロジェクトの Web ルートに配置します。通常、これは wwwroot フォルダーです。

Blazor Web App の場合:

beforeWebStart(options): Blazor Web App が開始する前に呼び出されます。たとえば、beforeWebStart は、読み込みプロセスやログレベルなどのオプションをカスタマイズするのに使用されます。 Blazor Web オプション (options) を受け取ります。
afterWebStarted(blazor): すべての beforeWebStart プロミスが解決された後に呼び出されます。たとえば、afterWebStarted を使用すれば、Blazor のイベントリスナーやカスタムイベントの種類を登録できます。 Blazor インスタンスは、afterWebStarted に引数 (blazor) として渡されます。
beforeServerStart(options, extensions): 最初のサーバーランタイムが開始される前に呼び出されます。 SignalR 回線開始オプション (options) と、発行時に追加された拡張機能 (extensions) を受け取ります。
afterServerStarted(blazor): 最初の対話型サーバーランタイムが開始された後に呼び出されます。
beforeWebAssemblyStart(options, extensions): 対話型 WebAssembly ランタイムが開始される前に呼び出されます。発行時に追加された Blazor オプション (options) と拡張機能 (extensions) を受け取ります。たとえば、オプションによってカスタムのブートリソースローダーの使用を指定できます。
afterWebAssemblyStarted(blazor): 対話型 WebAssembly ランタイムが開始された後に呼び出されます。

注

レガシ JS 初期化子 (beforeStart、afterStarted) は、Blazor Web App では既定で呼び出されません。 enableClassicInitializers オプションを使用すれば、レガシ初期化子を実行できます。ただし、レガシ初期化子の実行は予測できません。

<script>
  Blazor.start({ enableClassicInitializers: true });
</script>

.NET 8 および 9 (dotnet/aspnetcore #54049) のフレームワークのバグにより、BlazorまたはbeforeWebAssemblyStart(options, extensions)が呼び出されたときに、afterWebAssemblyStarted(blazor) スクリプトを手動で開始する必要があります。サーバーアプリが WebAssembly (Blazor) 構成で手動でwebAssembly: {...}をまだ開始していない場合は、サーバープロジェクトのApp コンポーネントを次のように更新します。

Components/App.razorで、既存のBlazor<script> タグを削除します。

- <script src="_framework/blazor.web.js"></script>

<script> タグを、WebAssembly (Blazor) 構成を使用して webAssembly: {...} を手動で起動する以下のマークアップに置き換えます。

<script src="_framework/blazor.web.js" autostart="false"></script>
<script>
    Blazor.start({
        webAssembly: {}
    });
</script>

Blazor Server、Blazor WebAssembly、および Blazor Hybrid アプリの場合:

beforeStart(options, extensions): Blazor が開始する前に呼び出されます。たとえば、beforeStart は、読み込みプロセス、ログレベル、およびホスティングモデルに固有のその他のオプションをカスタマイズするために使用されます。
- クライアント側の beforeStart は、発行時に追加された Blazor のオプション (options) と拡張機能 (extensions) を受け取ります。たとえば、オプションによってカスタムのブートリソースローダーの使用を指定できます。
- サーバー側の beforeStart は、SignalR 回線開始オプション (options) を受け取ります。
- BlazorWebView では、オプションは渡されません。
afterStarted(blazor): Blazor が JS からの呼び出しを受け取れる状態になった後で呼び出されます。たとえば、afterStarted は、JS 相互運用呼び出しを行い、カスタム要素を登録することによって、ライブラリを初期化するために使用されます。 Blazor インスタンスは、afterStarted に引数 (blazor) として渡されます。

その他の .NET WebAssembly ランタイムコールバック:

onRuntimeConfigLoaded(config): ブート構成のダウンロード時に呼び出されます。ランタイムの開始前に、アプリでパラメーター (構成) を変更できます (パラメーターは MonoConfig の dotnet.d.ts です)。

export function onRuntimeConfigLoaded(config) {
  // Sample: Enable startup diagnostic logging when the URL contains 
  // parameter debug=1
  const params = new URLSearchParams(location.search);
  if (params.get("debug") == "1") {
    config.diagnosticTracing = true;
  }
}

onRuntimeReady({ getAssemblyExports, getConfig }): .NET WebAssembly ランタイムの開始後に呼び出されます (パラメーターは RuntimeAPI の dotnet.d.ts です)。

export function onRuntimeReady({ getAssemblyExports, getConfig }) {
  // Sample: After the runtime starts, but before Main method is called, 
  // call [JSExport]ed method.
  const config = getConfig();
  const exports = await getAssemblyExports(config.mainAssemblyName);
  exports.Sample.Greet();
}

どちらのコールバックも Promise を返すことができ、プロミスを待機してからスタートアップが続行されます。

ファイル名については、次のようにします。

JS イニシャライザーがプロジェクトの静的アセットとして使われる場合は、{ASSEMBLY NAME}.lib.module.js という形式を使います。{ASSEMBLY NAME} プレースホルダーはアプリのアセンブリ名です。たとえば、プロジェクトのアセンブリ名が BlazorSample.lib.module.js である場合は、ファイルを BlazorSample という名前にします。ファイルをアプリの wwwroot フォルダーに配置します。
JS イニシャライザーが RCL から使われる場合は、{LIBRARY NAME/PACKAGE ID}.lib.module.js という形式を使います。{LIBRARY NAME/PACKAGE ID} プレースホルダーは、プロジェクトのライブラリ名またはパッケージ識別子です。たとえば、RCL のパッケージ識別子が RazorClassLibrary1.lib.module.js である場合は、ファイルを RazorClassLibrary1 という名前にします。ファイルをライブラリの wwwroot フォルダーに配置します。

Blazor Web App の場合:

次に示すのは、JS と Blazor Web App の <head> に追加することで、beforeWebStart の起動前と後にカスタムスクリプトを読み込む afterWebStarted イニシャライザーの例です。

export function beforeWebStart() {
  var customScript = document.createElement('script');
  customScript.setAttribute('src', 'beforeStartScripts.js');
  document.head.appendChild(customScript);
}

export function afterWebStarted() {
  var customScript = document.createElement('script');
  customScript.setAttribute('src', 'afterStartedScripts.js');
  document.head.appendChild(customScript);
}

前述の beforeWebStart の例では、Blazor の開始前にカスタムスクリプトが読み込まれることのみが保証されています。スクリプトで待機中の Promise の実行が Blazor の開始前に完了することは保証されません。

Blazor Server、Blazor WebAssembly、および Blazor Hybrid アプリの場合:

次に示すのは、JS と Blazor の <head> に追加することで、beforeStart が開始される前と後にカスタムスクリプトが読み込まれる afterStarted イニシャライザーの例です。

export function beforeStart(options, extensions) {
  var customScript = document.createElement('script');
  customScript.setAttribute('src', 'beforeStartScripts.js');
  document.head.appendChild(customScript);
}

export function afterStarted(blazor) {
  var customScript = document.createElement('script');
  customScript.setAttribute('src', 'afterStartedScripts.js');
  document.head.appendChild(customScript);
}

前述の beforeStart の例では、Blazor の開始前にカスタムスクリプトが読み込まれることのみが保証されています。スクリプトで待機中の Promise の実行が Blazor の開始前に完了することは保証されません。

注

MVC および Razor Pages アプリでは、JS イニシャライザーは自動的に読み込まれません。ただし、アプリのマニフェストをフェッチして、JS イニシャライザーの読み込みをトリガーするスクリプトを、開発者コードに含めることができます。

JS イニシャライザーの例については、次のリソースを参照してください。

Blazor Web App 読み込みインジケーター (プリレンダリングなしのグローバル対話型 WebAssembly レンダリングの例)
ASP.NET Core Blazor JavaScript と静的サーバー側レンダリング (静的 SSR)
JavaScript アプリと SPA フレームワークで Razor コンポーネントを使用する ("quoteContainer2 の例")
ASP.NET Core の Blazor イベントの処理 ("カスタムクリップボード貼り付けイベントの例")
ASP.NET Core Blazor Web App で TOTP 認証アプリ用の QR コードを生成できるようにする
ASP.NET Core GitHub リポジトリ内の基本的なテストアプリ (BasicTestApp.lib.module.js)

JavaScript アプリと SPA フレームワークで Razor コンポーネントを使用する ("quoteContainer2 の例")
ASP.NET Core の Blazor イベントの処理 ("カスタムクリップボード貼り付けイベントの例")
ASP.NET Core でホストされる Blazor WebAssembly アプリの展開レイアウト
ASP.NET Core GitHub リポジトリ内の基本的なテストアプリ (BasicTestApp.lib.module.js)

注

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

ライブラリが特定の順序で読み込まれるようにする

カスタムスクリプトを、読み込む必要がある順序で <head> と beforeStart の afterStarted に追加します。

次の例では、script1.js の前に script2.js、script3.js の前に script4.js を読み込みます。

export function beforeStart(options, extensions) {
    var customScript1 = document.createElement('script');
    customScript1.setAttribute('src', 'script1.js');
    document.head.appendChild(customScript1);

    var customScript2 = document.createElement('script');
    customScript2.setAttribute('src', 'script2.js');
    document.head.appendChild(customScript2);
}

export function afterStarted(blazor) {
    var customScript1 = document.createElement('script');
    customScript1.setAttribute('src', 'script3.js');
    document.head.appendChild(customScript1);

    var customScript2 = document.createElement('script');
    customScript2.setAttribute('src', 'script4.js');
    document.head.appendChild(customScript2);
}

追加のモジュールをインポートする

import の初期化子ファイルで最上位の JS ステートメントを使用して、追加のモジュールをインポートします。

additionalModule.js:

export function logMessage() {
  console.log('logMessage is logging');
}

JS の初期化子ファイル (.lib.module.js) において：

import { logMessage } from "/additionalModule.js";

export function beforeStart(options, extensions) {
  ...

  logMessage();
}

マップをインポートする

マップのインポートは、ASP.NET Core と Blazor でサポートされています。

ドキュメントの準備完了時に Blazor を初期化する

次の例では、ドキュメントの準備が整うと Blazor が起動されます。

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  document.addEventListener("DOMContentLoaded", function() {
    Blazor.start();
  });
</script>

手動で起動した結果として得た `Promise` に連結する

JS 相互運用の初期化など、追加のタスクを実行するには、then を使用して、手動で Promise アプリを起動させた結果として得た Blazor に連結します。

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start().then(function () {
    ...
  });
</script>

注

Blazor の開始後にライブラリで追加のタスクを自動的に実行するには、JavaScript イニシャライザーを使います。 JS イニシャライザーを使う場合は、ライブラリのコンシューマーが JS の呼び出しを Blazor の手動起動にチェーンする必要はありません。

クライアント側のブートリソースを読み込む

アプリがブラウザーに読み込まれると、アプリによってサーバーから次のブートリソースがダウンロードされます。

アプリをブートストラップする JavaScript コード
.NET ランタイムとアセンブリ
ロケール固有のデータ

loadBootResource API を使用して、これらのブートリソースの読み込み方法をカスタマイズします。 loadBootResource 関数によって、組み込みのブートリソース読み込みメカニズムをオーバーライドします。次のシナリオで loadBootResource を使用します。

タイムゾーンデータや dotnet.wasm などの静的なリソースを、CDN から読み込む。
HTTP 要求を使用して圧縮されたアセンブリを読み込み、サーバーからの圧縮コンテンツのフェッチをサポートしていないホストのクライアントに展開する。
各 fetch 要求を新しい名前にリダイレクトして、リソースを別の名前に設定する。

注

外部ソースは、ブラウザーがクロスオリジンのリソースの読み込みを許可するために必要なクロスオリジンリソース共有 (CORS) ヘッダーを返す必要があります。通常、必要なヘッダーが CDN によって提供されます。

loadBootResource パラメーターは次の表に表示されます。

パラメーター	説明
`type`	リソースの型。許容される型としては、`assembly`、`pdb`、`dotnetjs`、`dotnetwasm`、および `timezonedata` があります。カスタム動作の型のみ指定する必要があります。 `loadBootResource` に指定されていない型は、既定の読み込み動作に従ってフレームワークによって読み込まれます。 `dotnetjs` ブートリソース (`dotnet.*.js`) は、既定の読み込み動作を表す `null`、または `dotnetjs` ブートリソースのソースの URI を返す必要があります。
`name`	リソースの名前。
`defaultUri`	リソースの相対 URI または絶対 URI。
`integrity`	応答で予想されるコンテンツを表す整合性文字列。

loadBootResource 関数では、URI 文字列を返して、読み込みプロセスをオーバーライドできます。次の例では、bin/Release/{TARGET FRAMEWORK}/wwwroot/_framework からの次のファイルは https://cdn.example.com/blazorwebassembly/{VERSION}/ の CDN から提供されます。

dotnet.*.js
dotnet.wasm
タイムゾーンデータ

{TARGET FRAMEWORK} プレースホルダーはターゲットフレームワークモニカー (たとえば、net7.0) です。 {VERSION} プレースホルダーは共有フレームワークバージョン (たとえば、7.0.0) です。

Blazor Web App:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    webAssembly: {
      loadBootResource: function (type, name, defaultUri, integrity) {
        console.log(`Loading: '${type}', '${name}', '${defaultUri}', '${integrity}'`);
        switch (type) {
          case 'dotnetjs':
          case 'dotnetwasm':
          case 'timezonedata':
            return `https://cdn.example.com/blazorwebassembly/{VERSION}/${name}`;
        }
      }
    }
  });
</script>

スタンドアロン Blazor WebAssembly:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    loadBootResource: function (type, name, defaultUri, integrity) {
      console.log(`Loading: '${type}', '${name}', '${defaultUri}', '${integrity}'`);
      switch (type) {
        case 'dotnetjs':
        case 'dotnetwasm':
        case 'timezonedata':
          return `https://cdn.example.com/blazorwebassembly/{VERSION}/${name}`;
      }
    }
  });
</script>

ブートリソースの URL 以外のものをカスタマイズするには、loadBootResource 関数から fetch を直接呼び出して、結果を返すことができます。次の例では、カスタム HTTP ヘッダーを送信要求に追加します。既定の整合性チェックの動作を保持するため、integrity パラメーターを渡します。

Blazor Web App:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    webAssembly: {
      loadBootResource: function (type, name, defaultUri, integrity) {
        if (type == 'dotnetjs') {
          return null;
        } else {
          return fetch(defaultUri, {
            cache: 'no-cache',
            integrity: integrity,
            headers: { 'Custom-Header': 'Custom Value' }
          });
        }
      }
    }
  });
</script>

スタンドアロン Blazor WebAssembly:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    loadBootResource: function (type, name, defaultUri, integrity) {
      if (type == 'dotnetjs') {
        return null;
      } else {
        return fetch(defaultUri, {
          cache: 'no-cache',
          integrity: integrity,
          headers: { 'Custom-Header': 'Custom Value' }
        });
      }
    }
  });
</script>

loadBootResource 関数が null を返す場合、Blazor ではリソースの既定の読み込み動作が使用されます。たとえば、null ブートリソースは既定の読み込み動作を表す dotnetjs または dotnet.*.js ブートリソースのソースの URI を返す必要があるため、上記のコードは dotnetjs ブートリソース (null) に対して dotnetjs を返します。

loadBootResource 関数では、Response Promise を返すこともできます。例については、「ASP.NET Core Blazor WebAssembly のホストと展開」をご覧ください。

詳細については、「 ASP.NET Core Blazor WebAssembly .NET バンドルのキャッシュと整合性チェックの失敗」を参照してください。

C# コードでヘッダーを制御する

C# コードで起動時にヘッダーを制御するには、次の方法を使用します。

次の例では、コンテンツセキュリティポリシー (CSP) ヘッダーによって CSP がアプリに適用されます。 {POLICY STRING} プレースホルダーは、CSP ポリシーの文字列です。 CSP について詳しくは、「ASP.NET Core Blazor のコンテンツセキュリティポリシーを適用する」をご覧ください。

注

応答の開始後にヘッダーを設定することはできません。このセクションのアプローチでは、応答が開始される前にヘッダーのみを設定するため、ここで説明する方法は安全です。詳細については、core Blazor アプリの IHttpContextAccessor/HttpContext ASP.NETを参照してください。

サーバー側のシナリオとプリレンダリングされたクライアント側のシナリオ

ASP.NET Core ミドルウェアを使用してヘッダーコレクションを制御します。

Program ファイルで:

Startup.Configure の Startup.cs で:

app.Use(async (context, next) =>
{
    context.Response.Headers.Append("Content-Security-Policy", "{POLICY STRING}");
    await next();
});

前の例ではインラインミドルウェアを使用していますが、カスタムミドルウェアクラスを作成し、Program ファイルで拡張メソッドを使用してミドルウェアを呼び出すこともできます。詳細については、「カスタム ASP.NET Core ミドルウェアを記述する」を参照してください。

プリレンダリングなしのクライアント側の開発

StaticFileOptions ステージでの応答ヘッダーを指定する MapFallbackToFile を OnPrepareResponse に渡します。

サーバー側の Program ファイル:

Startup.Configure の Startup.cs で:

var staticFileOptions = new StaticFileOptions
{
    OnPrepareResponse = context =>
    {
        context.Context.Response.Headers.Append("Content-Security-Policy", 
            "{POLICY STRING}");
    }
};

...

app.MapFallbackToFile("index.html", staticFileOptions);

クライアント側のロードインジケーター

読み込みインジケーターは、アプリが正常に読み込まれており、読み込みが完了するまでユーザーが待機する必要があることを示します。

Blazor Web App 読み込みインジケーター

Blazor WebAssembly アプリで使用される読み込みインジケーターは、Blazor Web App プロジェクトテンプレートから作成されたアプリには存在しません。通常、読み込みインジケーターは対話型の WebAssembly コンポーネントでは望ましくありません。 Blazor Web Appは、初期読み込み時間が短いため、サーバー上のクライアント側コンポーネントをプリレンダリングするためです。混合レンダリングモードの状況では、フレームワークまたは開発者コードで次の問題を回避することに注意する必要もあります。

レンダリングされた同じページに複数の読み込みインジケーターを表示する。
.NET WebAssembly ランタイムの読み込み中に、プリレンダリングされたコンテンツを誤って破棄する。

.NET の将来のリリースでは、フレームワークベースの読み込みインジケーターが提供される可能性があります。それまでの間は、カスタム読み込みインジケーターを Blazor Web Appに追加できます。

プリレンダリングを使用したコンポーネントごとの対話型 WebAssembly レンダリング

このシナリオは、コンポーネントごとの対話型 WebAssembly レンダリングに適用されます (@rendermode InteractiveWebAssembly 個々のコンポーネントに適用されます)。

ContentLoadingを呼び出すLayout アプリの.Client フォルダーにOperatingSystem.IsBrowser コンポーネントを作成します。

false時には、読み込みインジケーターを表示します。
true の場合、要求されたコンポーネントのコンテンツをレンダリングします。

インジケーターの CSS スタイルを読み込むには、<head> コンテンツにHeadContent コンポーネントを使ってスタイルを追加します。詳しくは、「ASP.NET Core Blazor アプリでコンテンツを制御する」をご覧ください。

Layout/ContentLoading.razor:

@if (!RendererInfo.IsInteractive)
{
    <!-- OPTIONAL ...
    <HeadContent>
        <style>
            ...
        </style>
    </HeadContent>
    -->
    <progress id="loadingIndicator" aria-label="Content loading…"></progress>
}
else
{
    @ChildContent
}

@code {
    [Parameter]
    public RenderFragment? ChildContent { get; set; }
}

@if (!OperatingSystem.IsBrowser())
{
    <!-- OPTIONAL ...
    <HeadContent>
        <style>
            ...
        </style>
    </HeadContent>
    -->
    <progress id="loadingIndicator" aria-label="Content loading…"></progress>
}
else
{
    @ChildContent
}

@code {
    [Parameter]
    public RenderFragment? ChildContent { get; set; }
}

Layout プロジェクトに .Client フォルダーがまだない場合は、Layout フォルダーの名前空間を_Imports.razor ファイルに追加します。次の例では、プロジェクトの名前空間が BlazorSample.Clientされています。

@using BlazorSample.Client.Layout

対話型 WebAssembly レンダリングを採用するコンポーネントで、コンポーネントの Razor マークアップを ContentLoading コンポーネントでラップします。次の例は、Counter プロジェクトテンプレートから作成されたアプリの Blazor Web App コンポーネントを使用したアプローチを示しています。

Pages/Counter.razor:

@page "/counter"
@rendermode InteractiveWebAssembly

<PageTitle>Counter</PageTitle>

<ContentLoading>
    <h1>Counter</h1>

    <p role="status">Current count: @currentCount</p>

    <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
</ContentLoading>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

プリレンダリングを活用した世界規模のインタラクティブなWebAssemblyレンダリング

このシナリオは、@rendermode="InteractiveWebAssembly" コンポーネント内の HeadOutlet コンポーネントおよび Routes コンポーネント上の App を使用してプリレンダリングするグローバルな対話型 WebAssembly レンダリングに適用されます。

ContentLoadingを呼び出すLayout アプリの.Client フォルダーにRendererInfo.IsInteractive コンポーネントを作成します。

false時には、読み込みインジケーターを表示します。
true の場合、要求されたコンポーネントのコンテンツをレンダリングします。

Layout/ContentLoading.razor:

@if (!RendererInfo.IsInteractive)
{
    <!-- OPTIONAL ...
    <HeadContent>
        <style>
            ...
        </style>
    </HeadContent>
    -->
    <progress id="loadingIndicator" aria-label="Content loading…"></progress>
}
else
{
    @ChildContent
}

@code {
    [Parameter]
    public RenderFragment? ChildContent { get; set; }
}

@if (!OperatingSystem.IsBrowser())
{
    <!-- OPTIONAL ...
    <HeadContent>
        <style>
            ...
        </style>
    </HeadContent>
    -->
    <progress id="loadingIndicator" aria-label="Content loading…"></progress>
}
else
{
    @ChildContent
}

@code {
    [Parameter]
    public RenderFragment? ChildContent { get; set; }
}

@using BlazorSample.Client.Layout

MainLayout プロジェクトのLayout/MainLayout.razor コンポーネント (.Client) で、Body プロパティ (@Body) をContentLoading コンポーネントでラップします。

Layout/MainLayout.razorの場合:

+ <ContentLoading>
    @Body
+ </ContentLoading>

プリレンダリングを使用しないグローバル対話型 WebAssembly レンダリング

このシナリオは、プリレンダリングなしのグローバル Interactive WebAssembly レンダリングに適用されます (@rendermode="new InteractiveWebAssemblyRenderMode(prerender: false)" コンポーネントの HeadOutlet および Routes コンポーネントでは App)。

JavaScript 初期化子をアプリに追加します。次の JavaScript モジュールファイル名の例では、 {ASSEMBLY NAME} プレースホルダーはサーバープロジェクトのアセンブリ名です (たとえば、 BlazorSample)。モジュールが配置されているwwwroot フォルダーは、wwwroot プロジェクトではなく、サーバー側プロジェクトの.Client フォルダーです。

次の例では、実際のprogress進行状況を示さないインジケーターを使用していますが、アプリのブートリソースの読み込みの進行状況を示す進行状況インジケーターを開発したい場合は、さらに開発するための一般的なアプローチとなります。

wwwroot/{ASSEMBLY NAME}.lib.module.js:

export function beforeWebStart(options) {
  var progress = document.createElement("progress");
  progress.id = 'loadingIndicator';
  progress.ariaLabel = 'Blazor loading…';
  progress.style = 'position:absolute;top:50%;left:50%;margin-right:-50%;' +
    'transform:translate(-50%,-50%);';
  document.body.appendChild(progress);
}

export function afterWebAssemblyStarted(blazor) {
  var progress = document.getElementById('loadingIndicator');
  progress.remove();
}

.NET 8 および 9 (dotnet/aspnetcore #54049) のフレームワークのバグにより、Blazor スクリプトを手動で開始する必要があります。サーバーアプリが WebAssembly (Blazor) 構成で手動でwebAssembly: {...}をまだ開始していない場合は、サーバープロジェクトのApp コンポーネントを次のように更新します。

Components/App.razorで、既存のBlazor<script> タグを削除します。

- <script src="_framework/blazor.web.js"></script>

<script> タグを、WebAssembly (Blazor) 構成を使用して webAssembly: {...} を手動で起動する以下のマークアップに置き換えます。

<script src="_framework/blazor.web.js" autostart="false"></script>
<script>
    Blazor.start({
        webAssembly: {}
    });
</script>

読み込みインジケーターの削除と最初のページのレンダリングの間に短い遅延が発生した場合は、OnAfterRenderAsync またはコンポーネントの MainLayoutでインジケーターの削除を呼び出すことで、レンダリング後にインジケーターの削除を保証できます。詳細とコード例については、「プリレンダリングなしでグローバルな Interactive WebAssembly で動作する読み込みインジケーターのアプローチを文書化する (dotnet/AspNetCore.Docs #35111)」を参照してください。

Blazor WebAssembly アプリ読み込みの進行状況

プロジェクトテンプレートには、スケーラブルベクターグラフィックス (SVG) と、アプリの読み込みの進行状況を示すテキストインジケーターが含まれています。

進行状況インジケーターは、Blazor で指定された次の 2 つの CSS カスタムプロパティ (変数) を使用して、HTML と CSS で実装されます。

--blazor-load-percentage: 読み込まれたアプリファイルの割合。
--blazor-load-percentage-text: 読み込まれたアプリファイルの割合。最も近い整数に四捨五入されます。

上記の CSS 変数を使用して、アプリのスタイルに一致するカスタム進行状況インジケーターを作成できます。

次に例を示します。

resourcesLoaded は、アプリ起動時に読み込まれたリソースの瞬間的なカウントです。
totalResources は、読み込むリソースの合計数です。

const percentage = resourcesLoaded / totalResources * 100;
document.documentElement.style.setProperty(
  '--blazor-load-percentage', `${percentage}%`);
document.documentElement.style.setProperty(
  '--blazor-load-percentage-text', `"${Math.floor(percentage)}%"`);

既定の円形進行状況インジケーターは、wwwroot/index.html ファイル内の HTML に実装されます。

<div id="app">
    <svg class="loading-progress">
        <circle r="40%" cx="50%" cy="50%" />
        <circle r="40%" cx="50%" cy="50%" />
    </svg>
    <div class="loading-progress-text"></div>
</div>

プロジェクトテンプレートのマークアップと既定の進行状況インジケーターのスタイルを確認するには、ASP.NET Core 参照ソースをご覧ください。

注

既定の円形進行状況インジケーターを使用する代わりに、次の例では線形進行状況インジケーターを実装する方法を示します。

wwwroot/css/app.css に次のスタイルを追加します。

.linear-progress {
    background: silver;
    width: 50vw;
    margin: 20% auto;
    height: 1rem;
    border-radius: 10rem;
    overflow: hidden;
    position: relative;
}

.linear-progress:after {
    content: '';
    position: absolute;
    inset: 0;
    background: blue;
    scale: var(--blazor-load-percentage, 0%) 100%;
    transform-origin: left top;
    transition: scale ease-out 0.5s;
}

CSS 変数 (var(...)) を使用して、--blazor-load-percentage の値を、アプリのファイルの読み込みの進行状況を示す青い擬似要素の scale プロパティに渡します。アプリが読み込まれると、--blazor-load-percentage が自動的に更新され、進行状況インジケーターの視覚的表現が動的に変更されます。

wwwroot/index.html で、<div id="app">...</div> の既定の SVG 円形インジケーターを削除し、次のマークアップに置き換えます。

<div class="linear-progress"></div>

.NET WebAssembly ランタイムの構成

高度なプログラミングシナリオでは、 configureRuntime 関数を dotnet ランタイムホストビルダーと共に使用して、.NET WebAssembly ランタイムを構成します。たとえば、dotnet.withEnvironmentVariable は次の環境変数を設定します:

.NET WebAssembly ランタイムを構成します。
C ライブラリの動作を変更します。

注

.NET WebAssembly ランタイムを構成したり、C ライブラリの動作に影響を与えたりする環境変数の詳細については、dotnet/runtime GitHub リポジトリでドキュメント要求が保留中です。ドキュメント要求は保留中ですが、要求の中で追加のリソースに関する詳細情報とクロスリンクが利用可能です。.NET WASM ランタイム環境変数に関するドキュメントの要求 (dotnet/runtime #98225)。

configureRuntime 関数は、ブラウザプロファイルとの統合を有効にするのにもしようできます。

環境変数を設定する次のプレースホルダーの例:

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

Blazor Web App:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    webAssembly: {
      configureRuntime: dotnet => {
        dotnet.withEnvironmentVariable("{NAME}", "{VALUE}");
      }
    }
  });
</script>

スタンドアロン Blazor WebAssembly:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    configureRuntime: dotnet => {
      dotnet.withEnvironmentVariable("{NAME}", "{VALUE}");
    }
  });
</script>

注

.NET ランタイムインスタンスには、.NET WebAssembly ランタイム API (Blazor.runtime) を使用してアクセスできます。たとえば、アプリのビルド構成は、Blazor.runtime.runtimeBuildInfo.buildConfiguration を使用して取得できます。

.NET WebAssembly ランタイム構成の詳細については、「dotnet.d.ts GitHub リポジトリのランタイムの TypeScript 定義ファイル (dotnet/runtime)」を参照してください。

注

このセクションは Blazor Web App に適用されます。

拡張ナビゲーションとフォーム処理を無効にするには、disableDomPreservation に対して true を Blazor.start に設定してください。

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    ssr: { disableDomPreservation: true }
  });
</script>

次の方法で共有

ASP.NET Core Blazor の起動

スタートアップ プロセスと構成

JavaScript イニシャライザー

ライブラリが特定の順序で読み込まれるようにする

追加のモジュールをインポートする

マップをインポートする

ドキュメントの準備完了時に Blazor を初期化する

手動で起動した結果として得た Promise に連結する

クライアント側のブート リソースを読み込む

C# コードでヘッダーを制御する

サーバー側のシナリオとプリレンダリングされたクライアント側のシナリオ

プリレンダリングなしのクライアント側の開発

クライアント側のロードインジケーター

Blazor Web App 読み込みインジケーター

プリレンダリングを使用したコンポーネントごとの対話型 WebAssembly レンダリング

プリレンダリングを活用した世界規模のインタラクティブなWebAssemblyレンダリング

プリレンダリングを使用しないグローバル対話型 WebAssembly レンダリング

Blazor WebAssembly アプリ読み込みの進行状況

.NET WebAssembly ランタイムの構成

拡張ナビゲーションとフォーム処理を無効にする

その他のリソース

その他のリソース

スタートアッププロセスと構成

手動で起動した結果として得た `Promise` に連結する

クライアント側のブートリソースを読み込む