ASP.NET Core + Angular の組み合わせの Web アプリで、Angular 側にもアプリ自身のバージョン番号を埋め込む

背景

サーバー側実装に ASP.NET Core、クライアント側実装に Angular (本投稿時点で v8) の組み合わせによる Web アプリ開発の話。

昨今は micro service 化であるとか、サーバー側実装は Server less プラットフォームを使うとかも多いのかもと思う。

しかし今回は上記のとおり、サーバー側実装と Angular 側実装とが、Visual Studio / dotnet CLI 開発における単一プロジェクトファイルで集約され、サーバー側もクライアント側も同時並行で開発を進めるような、モノシリックな種類の Web アプリ開発の話である。

サーバー側実装のアプリケーションバージョン番号

さて、サーバー側実装は ASP.NET Core ということで、アプリケーションのバージョン番号の管理 (?) は簡単だ。

方針としては、当該 ASP.NET Core Web アプリプロジェクトの、主たる出力アセンブリのアセンブリバージョンが、そのアプリのバージョン番号であるとする。

実際のバージョン番号の指定方法は、とりあえずプロジェクトファイル (.csproj) 内の <Version> プロパティで、アプリケーションのバージョン番号を記述しておけば無難だろう。

<!-- これは .csproj ファイル -->

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

  <PropertyGroup>

    ...

    <Version>1.2.3.4</Version>

    ...

  </PropertyGroup>

  ...

</Project>

Visual Studio で開発中であれば、プロジェクトファイル (.csproj) を直接エディタで編集するだけではなく、プロジェクトのプロパティ画面から、"パッケージ" セクションの GUI 経由で、"パッケージバージョン" の欄に記入して <Version> プロパティを設定することも可能だ。

なお、上記 Visual Studio の GUI 経由での編集でもわかるように、<Version> プロパティは厳密にはパッケージ化する際のパッケージのバージョン番号である。

別途明示しなかった場合にアセンブリバージョンもパッケージバージョンに倣うこととなっている。

ちゃんと区別して取り扱う場合は、<AssemblyVersion> プロパティに、アプリケーションのバージョン番号を記載するとよい。

もちろん、Visual Studio の GUI 上からも設定可能だ。

こうしてプロジェクトファイルに記載したアセンブリバージョンは、サーバー側実装 (今回は C#) のコードからは、下記コードで取得可能だ。

// これはサーバー側実装の任意の C# コード。

// 変数 appVer に System.Version オブジェクトが入る。

// (上記 .csproj の例だと、ver.1.2.3.4 を示す System.Version オブジェクト)

var appVer = typeof(Program).Assembly.GetName().Version;

なお、プロジェクトファイル (.csproj) 中に記載するアプリケーションのバージョン番号を、どのように加算していくか、CI/CD なども絡めたバージョン番号管理とその自動化などについては、本投稿では割愛する。

クライアント側にも、サーバー側実装と同じバージョン番号を埋め込みたい!

さて、サーバー側実装でこのように管理することとしたアプリケーションのバージョン番号であるが、同じバージョン番号を、クライアント側実装である Angular のコードでも埋め込みたくなった。

というのも、今回案件は前述のとおり、サーバー側実装とクライアント側実装とが割と密接につながっているモノシリック構造である。

そのため、ブラウザに古いバージョンのクライアント側実装がキャッシュされて残ってて、しかしサーバー側実装が新しくなっている、という、サーバー側とクライアント側との間での "アプリケーションのバージョン番号の不一致" が問題になるのである。

その点、ビルド時のタイミングで、クライアント側実装にサーバー側アプリケーションバージョン番号を埋め込むことができれば、あとはサーバー側アプリケーションバージョン番号を返すような Web API をサーバー側に設け、これをクライアント側から呼び出すことで、クライアント側実装が、自身のバージョン番号がサーバー側と食い違っていないか、セルフチェックできるわけだ。

ということで、プロジェクトファイル (.csproj) はすなわち MSBuild スクリプトであるわけなので、プロジェクトファイル (.csproj) 内に MSBuild スクリプトを書き足してこれを実現してみた。

方針としては、「<Version> プロパティの内容を、TypeScript コード表現にして .ts ファイルを生成する」としてみた。

生成する .ts ファイルは、"~/ClientApp/src/app/app.version.ts" とし、生成されるこの .ts ファイルの内容は、以下の TypeScript コードとする。

export const appVersion = "1.2.3.4"

サーバー側とクライアント側とでバージョン番号の不一致がないかチェックする処理などでは、この "app.version.ts" を import して、文字列定数 "appVersion" を参照すればよいようにする。

以上の仕様・要件を実現する、プロジェクトファイル (.csproj) 内に書き足す MSBuild スクリプトは下記のとおりとなった。

<!-- これは .csproj ファイル -->

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

  ...

  <Target 

    Name="GenerateAppVersionFileForSPA" 

    BeforeTargets="PreBuildEvent">

    <WriteLinesToFile 

     File="$(SpaRoot)src/app/app.version.ts"

     Lines="export const appVersion = &quot;$(Version)&quot;"

     Overwrite="true" 

     WriteOnlyWhenDifferent="true">

    </WriteLinesToFile>

  </Target>

  ...

</Project>

まず、(ターゲット名は何でも良いのだが) BeforeTargets 属性として "PreBuildEvent" を指定し、ビルド開始時点で実行されるターゲット枠を用意する。

そして、MSBuild には標準で "WriteLinesToFile" という、テキストファイルへの書き出しを行なうタスクが装備されているので、これを用いて "app.version.ts" ファイルの作成・内容の書き込みを行なっている。

MSBuild スクリプトの仕組みとして、<Version> プロパティの内容は、"$(Version)" の記法で参照、該当部分が置換される。

これを利用して、.ts ファイルの内容としてアセンブリバージョン (厳密にはパッケージバージョン) を書き込んでいる次第。

MSBuild スクリプトファイルは XML 記法なので、ダブルクォーテションの記述などに XML 実体参照記法で記載している点が少し注意すべきところであろうか。

あとは、上書きを許可 (Overwrite="true") しつつ、内容に変化がなければいたずらに書き込んでタイムスタンプを更新してライブリロードが走ったりしないよう、WriteOnlyWhenDifferent="true" の指定を付け加えるなど、微調整して完成である。

以上の仕込みでビルドを実行すると、めでたく、プロジェクトファイル (.csproj) 中で指定したバージョン番号が、TypeScript ソースファイルとしても自動生成されるようになった。

補足

なお、この app.version.ts ファイルであるが、このような MSBuild スクリプトによる自動生成であることを、コメントで明記したほうがよいだろう (下記例)。

// このファイルは "GenerateAppVersionFileForSPA" MSBuild タスクによって自動生成されました。

export const appVersion = "1.2.3.4"

このように複数行にわたるテキストファイルを、"WriteLinesToFile" MSBuild 標準タスクで作成するには、同タスクの "Lines" 属性に指定するテキスト内容を、1行ごとにセミコロン (;) 区切りで記述すればよい。

<!-- これは .csproj ファイル -->

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

  ...

  <Target 

    Name="GenerateAppVersionFileForSPA" 

    BeforeTargets="PreBuildEvent">

    <WriteLinesToFile 

     File="$(SpaRoot)src/app/app.version.ts"

     Lines="// このファイルは～;export const appVersion = &quot;$(Version)&quot;"

     ...

</Project>

まとめ

以上、サーバー側とクライアント側との双方に、プロジェクトファイル (.csproj) に記載されたバージョン番号を埋め込む方法であった。

あとは前述のとおり、サーバー側に自身のバージョン番号を返す Web API を設けつつ、これをクライアント側から呼び出すことで、サーバー/クライアント間のバージョン番号不一致を検出できる。

バージョン番号の不一致を検出したらどうするか (UI 上にその旨通知するとか、問答無用でハードリロードを実行するとか) は、アプリケーションの仕様・要件次第だろう。

また、クライアント側実装にアプリケーションのバージョン番号が埋め込まれているので、気軽にアプリケーションのバージョン番号表示をクライアント側実装のみで行なうことも可能だ。