静的アセットのフィンガープリント

.NET 9 を対象フレームワークとして実装された Blazor WebAssembly スタンドアローンプロジェクトがありました。これを .NET 10 に移行しました。移行にあたっては、C#/Razor ソースコードの変更は発生しませんでしたが、せっかく .NET 10 に移行するので、.NET 10 での新機能のひとつ、"静的アセットのフィンガープリント" を有効にすることにしました。

"静的アセットのフィンガープリント" を有効にすることで、Blazor WebAssembly のランタイム JavaScript ファイルなどのファイル名に "フィンガープリント" (ある種のハッシュ値) が追加され、"キャッシュに残っていた古い JavaScript コードが使用されてしまった" といった事故を回避し、代わりにキャッシュを積極的に使用できるようになります。

プロジェクトを変更し動作確認

ということで、プロジェクトファイル (.csproj) を編集し、OverrideHtmlAssetPlaceholders MSBuild プロパティを true に設定します。

*.csproj

<Project Sdk="Microsoft.NET.Sdk.BlazorWebAssembly">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>

    <!-- 👇この1行を追加 -->
+   <OverrideHtmlAssetPlaceholders>true</OverrideHtmlAssetPlaceholders>
  
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly" Version="10.0.0" />
    <PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly.DevServer" Version="10.0.0" PrivateAssets="all" />
  </ItemGroup>

</Project>

続けて、wwwroot/index.html を編集し、blazor.webassembl.js ファイルの読み込みの箇所に、フィンガープリントに置換されるプレースホルダーを書き加えます。

wwwroot/index.html

    ...
-   <script src="_framework/blazor.webassembly.js"></script>
+   <script src="_framework/blazor.webassembly#[.{fingerprint}].js"></script>
    <!--                                      ~~~~~~~~~~~~~~~~~ -->
    <!-- プレースホルダ "#[.{fingerprint}]" を書き足す 👆 -->
</body>
</html>

以上の処置を済ませて、dotnet run してみると、たしかにフィンガープリントが付け足されたファイル名にフォールバックページが置換されており、そのフィンガープリント付きのファイル名で blazor.webassembl.js ファイルが読み込まれていることも確認できました。

発行すると動作しない!

動作を確認できたので、dotnet publish で発行し、念のため発効後のコンテンツで動作確認してみました。すると、予期しなかったことに、dotnet.js の読み込みで 404 Not Found エラーが発生し、起動が停止してしまいました。

ちなみに、フィンガープリント付きの blazor.webassembl.js ファイルの読み込みは正しく機能しています。

調べてみたところ OverrideHtmlAssetPlaceholders MSBuild プロパティを true で発行したときは、発行先出力フォルダには、dotnet.js はそのままのファイル名のファイルは存在せず、フィンガープリント付きのファイル名 ("dotnet.8ciuo1cb4v.js" のような) でしか配置されていませんでした。

Import Map を追加

ではどうするかというと、wwwroot/index.html に import map のプレースホルダも追加します。

wwwroot/index.html

<!DOCTYPE html>
<html lang="en">
<head>
    ...
    
    <!-- 👇この1行を追加 -->
+   <script type="importmap"></script>
</head>
...

改めてプロジェクトを発行しなおし、動作を確認してみると、今度はうまくいきました。

フォールバックページに書き足した <script type="importmap"></script> の部分に、import map が書き加えられており、結果、import("_framework/dotnet.js") は "_framework/dotnet.fa04pep6r3.js" に振り替えられて読み込みに成功するようになりました。

まとめ

プロジェクトテンプレートから新規に .NET 10 の Balzor WebAssembly スタンドアローンプロジェクトを作成した場合は、このような失敗は起こりませんが、古いバージョンの .NET から .NET 10 に移行して、手動で "静的アセットのフィンガープリント" を有効にしようとしたときにやらかしてしまいました。公式のドキュメントには、ちゃんと Import Map の追加もあわせて書き足すように説明されていますので、落ち着いてちゃんと読むべきでした。

なお、上記では Blazor フレームワークのプリロードを有効にしていませんが、問題に焦点を当てるために言及を割愛しておりました。なので、.NET 10 への移行でフィンガープリント対応するのであれば、当然、プリロードも有効にするべきです (具体的には下記参照)。

wwwroot/index.html

<!DOCTYPE html>
<html lang="en">
<head>
    ...
    <base href="/" />
    <!-- 👇この1行を追加 -->
+   <link rel="preload" id="webassembly" />
    ...