ASP.NET Core Blazor の起動

この記事では、Blazor 起動を構成する方法について説明します。

wwwroot/index.html ファイル (Blazor WebAssembly) または Pages/_Layout.cshtml ファイル (Blazor Server) で手動での起動を構成します。

  • Blazor スクリプトの <script> タグに autostart="false" 属性と値を追加します。
  • Blazor.start を呼び出すスクリプトを、Blazor<script> タグの後の終了 </body> タグ内に配置します。

JavaScript イニシャライザー

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

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

JS イニシャライザーは、ビルド処理の一部として検出されて、Blazor アプリに自動的にインポートされます。 多くの場合、JS イニシャライザーを使用すると、Razor クラス ライブラリ (RCL) を使用するときにアプリからスクリプト関数を手動でトリガーする必要がなくなります。

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

そのモジュールで、次の従来の関数のいずれかまたは両方をエクスポートします。

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

次の例では、beforeStartafterStarted に対する JS イニシャライザーが示されています。 以下の例のファイル名は次のとおりです。

  • JS イニシャライザーがプロジェクトで静的資産として使用される場合は、ファイル名にアプリのアセンブリ名を使用します。 たとえば、プロジェクトのアセンブリ名が BlazorSample である場合は、ファイルを BlazorSample.lib.module.js という名前にします。 ファイルをアプリの wwwroot フォルダーに配置します。
  • JS イニシャライザーが RCL から使用される場合は、プロジェクトのライブラリ名またはパッケージ識別子を使用します。 たとえば、RCL のパッケージ識別子が RazorClassLibrary1 である場合は、ファイルを RazorClassLibrary1.lib.module.js という名前にします。 ファイルをライブラリの wwwroot フォルダーに配置します。
export function beforeStart(options, extensions) {
    console.log("beforeStart");
}

export function afterStarted(blazor) {
    console.log("afterStarted");
}

Note

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

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

注意

ASP.NET Core 参照ソースへのドキュメント リンクを使用すると、リポジトリの main ブランチが読み込まれます。このブランチは、ASP.NET Core の次回リリースに向けて行われている製品単位の現在の開発を表します。 別のリリースのブランチを選択するには、 [Switch branches or tags](ブランチまたはタグの切り替え) ドロップダウン リストを使用して、そのブランチを選択します。 たとえば、ASP.NET Core 6.0 リリースの場合は、release/6.0 ブランチを選択します。

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

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

<body>
    ...

    <script src="_framework/blazor.{webassembly|server}.js" autostart="false"></script>
    <script>
      document.addEventListener("DOMContentLoaded", function() {
        Blazor.start();
      });
    </script>
</body>

前記のマークアップの {webassembly|server} プレースホルダーは、Blazor WebAssembly アプリ (blazor.webassembly.js) の場合は webassembly、Blazor Server アプリ (blazor.server.js) の場合は server です。

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

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

<body>
    ...

    <script src="_framework/blazor.{webassembly|server}.js" autostart="false"></script>
    <script>
      Blazor.start().then(function () {
        ...
      });
    </script>
</body>

前記のマークアップの {webassembly|server} プレースホルダーは、Blazor WebAssembly アプリ (blazor.webassembly.js) の場合は webassembly、Blazor Server アプリ (blazor.server.js) の場合は server です。

ブート リソースを読み込む

"このセクションは Blazor WebAssembly アプリにのみ適用されます。 "

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

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

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

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

Note

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

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

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

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

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

wwwroot/index.html の終了 </body> タグ内:

<script src="_framework/blazor.webassembly.js" 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/5.0.0/${name}`;
      }
    }
  });
</script>

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

wwwroot/index.html の終了 </body> タグ内:

<script src="_framework/blazor.webassembly.js" autostart="false"></script>
<script>
  Blazor.start({
    loadBootResource: function (type, name, defaultUri, integrity) {
      return fetch(defaultUri, { 
        cache: 'no-cache',
        integrity: integrity,
        headers: { 'Custom-Header': 'Custom Value' }
      });
    }
  });
</script>

loadBootResource 関数では、次を返すこともできます。

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

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

次の例では、コンテンツ セキュリティ ポリシー (CSP) ヘッダーによって CSP がアプリに適用されます。 {POLICY STRING} プレースホルダーは、CSP ポリシーの文字列です。

  • Blazor Server アプリとプリレンダリング済み Blazor WebAssembly アプリでは、ASP.NET Core ミドルウェアがヘッダー コレクションの制御に使用されます。

    Program.cs:

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

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

  • プリレンダリングされていないホストされた Blazor WebAssembly アプリでは、OnPrepareResponse ステージでの応答ヘッダーを指定する StaticFileOptionsMapFallbackToFile に渡します。

    Server プロジェクトの Program.cs:

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

CSP について詳しくは、「ASP.NET Core Blazor のコンテンツ セキュリティ ポリシーを適用する」をご覧ください。

その他の技術情報

wwwroot/index.html ファイル (Blazor WebAssembly) または Pages/_Host.cshtml ファイル (Blazor Server) で手動での起動を構成します。

  • Blazor スクリプトの <script> タグに autostart="false" 属性と値を追加します。
  • Blazor.start を呼び出すスクリプトを、Blazor<script> タグの後の終了 </body> タグ内に配置します。

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

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

<body>
    ...

    <script src="_framework/blazor.{webassembly|server}.js" autostart="false"></script>
    <script>
      document.addEventListener("DOMContentLoaded", function() {
        Blazor.start();
      });
    </script>
</body>

前記のマークアップの {webassembly|server} プレースホルダーは、Blazor WebAssembly アプリ (blazor.webassembly.js) の場合は webassembly、Blazor Server アプリ (blazor.server.js) の場合は server です。

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

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

<body>
    ...

    <script src="_framework/blazor.{webassembly|server}.js" autostart="false"></script>
    <script>
      Blazor.start().then(function () {
        ...
      });
    </script>
</body>

前記のマークアップの {webassembly|server} プレースホルダーは、Blazor WebAssembly アプリ (blazor.webassembly.js) の場合は webassembly、Blazor Server アプリ (blazor.server.js) の場合は server です。

ブート リソースを読み込む

"このセクションは Blazor WebAssembly アプリにのみ適用されます。 "

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

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

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

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

Note

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

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

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

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

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

wwwroot/index.html の終了 </body> タグ内:

<script src="_framework/blazor.webassembly.js" 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/5.0.0/${name}`;
      }
    }
  });
</script>

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

wwwroot/index.html の終了 </body> タグ内:

<script src="_framework/blazor.webassembly.js" autostart="false"></script>
<script>
  Blazor.start({
    loadBootResource: function (type, name, defaultUri, integrity) {
      return fetch(defaultUri, { 
        cache: 'no-cache',
        integrity: integrity,
        headers: { 'Custom-Header': 'Custom Value' }
      });
    }
  });
</script>

loadBootResource 関数では、次を返すこともできます。

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

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

次の例では、コンテンツ セキュリティ ポリシー (CSP) ヘッダーによって CSP がアプリに適用されます。 {POLICY STRING} プレースホルダーは、CSP ポリシーの文字列です。

  • Blazor Server アプリとプリレンダリング済み Blazor WebAssembly アプリでは、ASP.NET Core ミドルウェアがヘッダー コレクションの制御に使用されます。

    Startup.csStartup.Configure で:

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

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

  • プリレンダリングされていないホストされた Blazor WebAssembly アプリでは、OnPrepareResponse ステージでの応答ヘッダーを指定する StaticFileOptionsMapFallbackToFile に渡します。

    Server プロジェクトの Startup.Configure (Startup.cs):

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

CSP について詳しくは、「ASP.NET Core Blazor のコンテンツ セキュリティ ポリシーを適用する」をご覧ください。

その他の技術情報

wwwroot/index.html ファイル (Blazor WebAssembly) または Pages/_Host.cshtml ファイル (Blazor Server) で手動での起動を構成します。

  • Blazor スクリプトの <script> タグに autostart="false" 属性と値を追加します。
  • Blazor.start を呼び出すスクリプトを、Blazor<script> タグの後の終了 </body> タグ内に配置します。

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

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

<body>
    ...

    <script src="_framework/blazor.{webassembly|server}.js" autostart="false"></script>
    <script>
      document.addEventListener("DOMContentLoaded", function() {
        Blazor.start();
      });
    </script>
</body>

前記のマークアップの {webassembly|server} プレースホルダーは、Blazor WebAssembly アプリ (blazor.webassembly.js) の場合は webassembly、Blazor Server アプリ (blazor.server.js) の場合は server です。

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

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

<body>
    ...

    <script src="_framework/blazor.{webassembly|server}.js" autostart="false"></script>
    <script>
      Blazor.start().then(function () {
        ...
      });
    </script>
</body>

前記のマークアップの {webassembly|server} プレースホルダーは、Blazor WebAssembly アプリ (blazor.webassembly.js) の場合は webassembly、Blazor Server アプリ (blazor.server.js) の場合は server です。

ブート リソースを読み込む

"このセクションは Blazor WebAssembly アプリにのみ適用されます。 "

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

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

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

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

Note

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

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

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

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

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

wwwroot/index.html の終了 </body> タグ内:

<script src="_framework/blazor.webassembly.js" 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/3.1.0/${name}`;
      }
    }
  });
</script>

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

wwwroot/index.html の終了 </body> タグ内:

<script src="_framework/blazor.webassembly.js" autostart="false"></script>
<script>
  Blazor.start({
    loadBootResource: function (type, name, defaultUri, integrity) {
      return fetch(defaultUri, { 
        cache: 'no-cache',
        integrity: integrity,
        headers: { 'Custom-Header': 'Custom Value' }
      });
    }
  });
</script>

loadBootResource 関数では、次を返すこともできます。

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

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

次の例では、コンテンツ セキュリティ ポリシー (CSP) ヘッダーによって CSP がアプリに適用されます。 {POLICY STRING} プレースホルダーは、CSP ポリシーの文字列です。

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

    Startup.csStartup.Configure で:

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

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

  • ホストされた Blazor WebAssembly アプリでは、OnPrepareResponse ステージでの応答ヘッダーを指定する StaticFileOptionsMapFallbackToFile に渡します。

    Server プロジェクトの Startup.Configure (Startup.cs):

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

CSP について詳しくは、「ASP.NET Core Blazor のコンテンツ セキュリティ ポリシーを適用する」をご覧ください。

その他のリソース