Microsoft.TypeScript.MSBuild を含む Blazor プロジェクトを GitHub Actions 上でビルドしたらエラー

TypeScript を含む .NET Core 3.1 な Blazor プロジェクト

.NET Core 3.1 の頃から構築・保守してきたとある Blazor アプリ開発における話。

その Blazor アプリでは、若干ながら JavaScript を必要とする場面があり、少量の JavaScript ファイルを含むプロジェクト構成となっていた。

なお、生の JavaScript で記述するのは習慣的にも気が引けるため、TypeScript で記述してこれを JavaScript にトランスパイルするようにプロジェクトを構成しておいた。

とは言っても、Visual Studio IDE の使用を前提としたプロジェクトであり、且つ、Blazor からの JavaScript 相互運用を経由した軽量の利用に過ぎないため、やれ webpack がーみたいな面倒な準備作業はない。

プロジェクトに Microsoft.TypeScript.MSBuild NuGet パッケージを追加しておき、tsconfig.json さえ用意すれば、Visual Studio 上で .ts ファイルを編集して保存すれば、それだけで .js が自動生成されてくれる。

GitHub リポジトリでソース管理、プッシュしたら自動でビルド確認

また、この Blazor アプリプロジェクトは、GitHub 上でソース管理してある。

加えて GitHub Actions を利用し、GitHub 上でのプッシュが発生する毎に GitHub 上でビルドを実行し、ビルドが壊れていないことを機械的にチェックできるようにしてある。

.js ファイルを .razor と同じフォルダに配置

さて、この Blazor アプリ開発、前述のとおり、.NET Core 3.1 時代から保守してきた経緯もあり、.NET 6 から利用できるようになった、「Razor コンポーネントファイル (.razor) と同じフォルダに JavaScript ファルを配置できる」機能というか仕様 (下記リンク先参照) を利用していなかった。

しかしとある機会を得て、当該 Blazor アプリの対象フレームワークを、.NET Core 3.1 から .NET 6 に引き上げることとなった。

そこで、これに乗じて、プロジェクトに含まれる JavaScript (TypeScript) ファイルの配置構造も整理しよう、ということになった。

つまり「Index.razor でのみ使う JavaScript (TypeScript) は、Index.razor.js (Index.razor.ts) として配置」ということである。

お察しの通り、大した変更作業でもなく、予想どおり難なく移行は完了。
手元の開発環境 (Windows OS) 上でのビルドや軽い動作確認も問題なく済ませ、変更をコミット、そして GitHub へプッシュした。

GitHub にプッシュしたら、ビルドエラー!

これで一仕事終わった... と思っていたところ、予想外にも、GitHub Actions による自動ビルド確認でエラーが通知されてきた。

エラー内容を要約すると下記のような感じ。

$ dotnet build

/usr/share/dotnet/sdk/6.0.200/Sdks/Microsoft.NET.Sdk.Razor/targets/Microsoft.NET.Sdk.Razor.JSModules.targets(95,5):

Two assets found targeting the same path with incompatible asset kinds:  

 'Index.razor.js' with kind 'All'

 'Index.razor.js' with kind 'All'

 for path 'Index.razor.js'

どういう訳か、Index.razor.js が 2回、静的 Web アセットとして登録・認識されてしまい、それで重複エラーとなっているようである。

さらに興味深いのは、同じコマンド処理 (dotnet build) を、手元の Windows OS 上で実行しても、上記のようなエラーはでずに、ビルド成功するのである。

なお、上記 GitHub Actions は、Ubuntu Linux 20.04 LTS で実行するように構成してある。

そこで、まさかとは思いつつも、手元の Windows OS 上で WSL2 を有効化し、Ubuntu Linux 20.04 LTS を Microsoft Store アプリ経由でインストール、同じバージョンの .NET SDK と Node.js を WSL2 上の Ubuntu 環境にインストールし、それで同じく dotnet build を実行したところ、なんと、エラーが再現された。

確証はないものの、これらの状況証拠からは、どうやら上記 "incompatible asset kinds" エラーは、Linux 環境でのみ発生するようである。

TypeScript からのトランスパイルと関係している...!?

さてこの謎のビルドエラーを解消すべく、この WSL2 環境上でいろいろ試行錯誤を繰り返した。

そうして四苦八苦しているうちに、偶然にも、TypeScript からのトランスパイルをしなければ ― つまり、Index.razor.ts は作らず、Index.razor.js のみ配置している状況ならば ― 上記 "incompatible asset kinds" エラーが発生しないことを発見した。

この現象から、ひとつの仮説が思いついた。

どうも、Microsoft.TypeScript.MSBuild が .ts を .js にトランスパイルしたときに、二重に静的 Web アセットに登録しているのではないだろうか。

つまり、以下のようなシナリオである。

まず前提条件の補足だが、このリポジトリでは、トランスパイル後の .js もソース管理に登録していた。

さてこの Git リポジトリからチェックアウトし、ビルド開始すると、まずはチェックアウトによってファイルシステム上に既に存在する Index.razor.js がビルドシステムに発見され、静的 Web アセットとして認識・登録される。

続けて Microsoft.TypeScript.MSBuild パッケージによる Index.razor.ts から Index.razor..js へのトランスパイルが実行されるが、このときに、何かしらの事情によって、トランスパイル後の Index.razor.js が、再度、重ねて、静的 Web アセットに重複登録されるのではないだろうか。

Windows 上ではなく、Linux 上で発生する理由はこれだけでは説明が付かないが、何かしらのプラットフォーム依存があるのかもしれない。

とりあえずやっつける方法

さて、仮説は立ったが、ではどう対処したものか。

仮に、特定のプラットフォームにおける .NET SDK ないしは Microsoft.TypeScript.MSBuild パッケージの相性問題であるならば、GitHub 上で Issue 登録し、修正・改善を待つというのがひとつの方法である。

いっぽうで、それら Issue 登録しても、すぐに修正されるとは期待できない。

そこで、Issue 登録も大事なことながら、当座の目前のビルドエラーをやっつけるために、暫定的ながら回避策を打ち出すことにした。

何の事はない、.razor.js をソース管理から削除することにしたのである。

そうすれば、Git リポジトリからチェックアウトした直後のファイルシステム上には Index.razor.js は存在せず、ビルド開始直後の時点では、Index.razor.js が静的 Web アセットとして発見されることもない。

その上で、Microsoft.TypeScript.MSBuild パッケージによる Index.razor.ts から Index.razor..js へのトランスパイルが実行され、このときにようやくトランスパイル後の Index.razor.js が初めて静的 Web アセットに登録されることとなる。

そもそもこのプロジェクトにおける .razor.js は、.razor.ts から生成される "成果物" である。
.cs に対する .dll をソース管理に登録しないのと同じ理由で、.razor.js をソース管理に登録する必要性はまったくないのである、

以上、当方の仮説によれば、以上のようなシナリオでビルドが進み、ビルドは成功するはずだ。

ということで、実際に .razor.js をソース管理から削除し、コミット、GitHub にプッシュしたところ、当方の期待どおりビルドが成功するようになった。

おわりに

もちろん、Linux 環境における二度目以降のビルド実行では、(前回のビルドで、Index.razor.js がファイルシステム上に存在しているため) 結局 "incompatible asset kinds" エラーが発生することになる。
根本的な解決になっていない。

しかし今回当座のしのぎで回避したいのは、あくまでも、GitHub Actions 上での自動ビルド確認でのエラーである。
この Blazor プロジェクトにおける GitHub Actions によるプッシュ時のビルド確認では、毎回、空のフォルダ上にチェックアウトするところからビルド処理が始まるので、ソース管理にさえ Index.razor.js がいなければ、それで充分、という訳だ。

目標設定がそこなので、上記のとおり「.razor.js をソース管理から削除」で、とりあえず満足した次第。

[2022/03/10 追記]
.NET SDK 6.0.201 で状況再確認の上、下記のとおり Issue を立ててみた。