"React での ASP.NET Core" テンプレートで生成されるプロジェクトの仕組みを調べてみた

Visual Studio や .NET SDK を使って、フロントエンドは React、バックエンドは ASP.NET Core を用いた Web アプリケーション開発における話。

最近の Visula Studio または .NET SDK のプロジェクトテンプレートから上記構成のプロジェクトを新規作成すると、

• React 側の開発環境構成で提供される開発用サーバーでコンテンツをサーブし、React 開発のツールチェインにてホットリロードなどを実現しつつ
• サーバー側実装への API 呼び出しは、同開発用サーバーによる HTTP プロクシ機能で ASP.NET Core サーバープロセスへ要求を転送

という構成でできあがる。

ざっくり言うと上記のとおりであるわけだが、もう少し詳しく、上記構成がどのように構築されているか、調べてみた。

ASP.NET Core サーバー側

React + ASP.NET Core 構成のプロジェクト (.csproj) と、単独の ASP.NET Core サーバープロジェクトとの違いとして大きく目に付くのは、まずは Microsoft.AspNetCore.SpaProxy NuGet パッケージを参照していることだ。

<!-- .csproj -->

...

<ItemGroup>

  <PackageReference Include="Microsoft.AspNetCore.SpaProxy" Version="6.0.8" />

</ItemGroup>

...

Visual Studio 等でこのプロジェクトを開き、F5 ないしは Ctrl + F5 などでプロジェクトを実行すると、順番としてはまずは ASP.NET Core サーバープログラムがビルド、起動される。

そしてこのとき、Microsoft.AspNetCore.SpaProxy NuGet パッケージに収録されているアセンブリ (.dll) に棲息している各種実装が、React 側のビルドと開発サーバーの起動を行なうようだ。

実は、Microsoft.AspNetCore.SpaProxy NuGet パッケージをパッケージ参照でプロジェクトに追加するだけでは、この仕掛けは発動しない。

Microsoft.AspNetCore.SpaProxy をパッケージ追加しただけでプロジェクトを実行しても、あくまでも開発者が実装した (おそらくは Program.cs から始まるであろう) ASP.NET Core サーバープロセスが稼働するだけである。

Microsoft.AspNetCore.SpaProxy パッケージ内のアセンブリに収録されているコードが、ASP.NET Core サーバープログラム起動時に同時に実行されるのには、もうひとつ仕掛けがあって、それは、環境変数 "ASPNETCORE_HOSTINGSTARTUPASSEMBLIES" の指定だ。"./Properties/launchSettings.json" による起動プロファイルを確認するとわかるのだが、この起動プロファイルによって、Visual Studio や .NET CLI からのプロジェクト起動時に、環境変数 "ASPNETCORE_HOSTINGSTARTUPASSEMBLIES" に "Microsoft.AspNetCore.SpaProxy" というアセンブリ名を設定してからプログラムが起動するように指定されている。

// ./Properties/launchSettings.json

...

"profiles": {

  "...": {

    "environmentVariables": {

      ...,

      "ASPNETCORE_HOSTINGSTARTUPASSEMBLIES": "Microsoft.AspNetCore.SpaProxy"

    },

    ...

環境変数 "ASPNETCORE_HOSTINGSTARTUPASSEMBLIES" による効能について詳細はマイクロソフトの公式ドキュメントサイトを参照頂きたいが、

とにかく、起動プロファイルによって、環境変数 ASPNETCORE_HOSTINGSTARTUPASSEMBLIES に "Microsoft.AspNetCore.SpaProxy" が設定されていることで、ASP.NET Core サーバープログラムの起動時に、Microsoft.AspNetCore.SpaProxy パッケージ内に実装されているスタートアップ処理も読み込まれるらしい。

なお、Microsoft.AspNetCore.SpaProxy が実行する React 側開発サーバーの起動コマンドや、作業フォルダ、React 側開発サーバーのリッスン URL は、下記例のようにプロジェクトファイル (.csproj) 内に MSBuild プロパティ値として記載されている。

<!-- .csproj -->

...

<PropertyGroup>

  ...

  <SpaRoot>ClientApp\</SpaRoot>

  <SpaProxyServerUrl>https://localhost:44474</SpaProxyServerUrl>

  <SpaProxyLaunchCommand>npm start</SpaProxyLaunchCommand>

  ...

Microsoft.AspNetCore.SpaProxy はこのプロジェクトファイル (.csproj) 内の指定を参照して動作するというわけである。

さてところで、起動プロファイル ./Properties/launchSettings.json を改めて確認すると、プロジェクト起動時にブラウザで開く URL は明示的に指定されていない。明示的指定がない場合は、Visual Studio ないしは .NET CLI は、ASP.NET Core サーバーのリッスン URL をブラウザで開くように動作する。しかし冒頭で説明したとおり、このプロジェクト構成では、ブラウザで開くべきは、React 側の開発サーバーのリッスン URL である。

実はここでも Microsoft.AspNetCore.SpaProxy が一役買っている。このプロジェクトの起動時、たしかにいったんはブラウザは ASP.NET Core サーバーのリッスン URL を開いて起動する。しかしこのブラウザからの要求を、Microsoft.AspNetCore.SpaProxy が捕捉し、ひとまず「待機中」の Web コンテンツを返すのだ。いっぽうで、Microsoft.AspNetCore.SpaProxy は、先に説明したとおり React 側のリッスン URL をプロジェクトファイル (.csproj) による指定にて把握しており、その React 側のリッスン URL でサーバーが開始しているかどうかをポーリングして確認する。その結果、Microsoft.AspNetCore.SpaProxy が、React 側開発サーバーが起動していることが確認できると、先ほどまずはいったんブラウザに返した「待機中」Web コンテンツを介して、ブラウザを React 側の開発サーバーのリッスン URL にページ遷移させるのだ。

こうした起動プロセスを経て、フロント Rect + サーバー ASP.NET Core の構成の開発環境でブラウザ起動までが実行されるというわけである。

React フロント側

さて、ここまでの説明でおわかりのとおり、React 開発サーバーは ASP.NET Core サーバープログラム (に注入された Microsoft.AspNetCore.SpaProxy) から起動され、その起動コマンドは前述のとおり "npm start" と設定されていた。

ところで、このプロジェクト構成における React 開発サーバー、素で "npx create-react-app" で作成した場合と異なり、(http ではなく) https プロトコルでリッスンしていたり、ASP.NET Core サーバー側で処理すべき URL への要求をプロクシ機能で中継したりするようになっている。その仕掛けがどうなっているのか見てみよう。

まずは React 側の packages.json を見てみる。"npm start" で実行される、"scripts" ノードの "start" スクリプトは、"react-scripts start" と設定されている。これは素で "npx create-react-app" で作成した場合と同じである。しかしそれとは別に、素で作った場合と比べて、"prestart" スクリプトが追加されているのがわかる。

// packages.json

...

"scripts": {

  "prestart": "node aspnetcore-https && node aspnetcore-react",

  "start": "react-scripts start",

  ...

この "prestart" スクリプトは、npm の動作仕様上、"npm start" コマンドを実行の際に、"start" スクリプトの先に実行されるスクリプトだ。

そしてその "prestart" スクリプトには、"aspnetcore-～" というファイル名で始まる、何やら ASP.NET Core と関係してそうな名前の JavaScript ファイルを Node.js で実行するスクリプトが指定されている。

つまり、React 開発サーバー起動の前に、これら "aspnetcore-～" という JavaScript プログラムが Node.js 上で実行されるわけだ。ではこれら JavaScript ファイルが何をやっているのか見てみよう。

aspnetcore-https.js

まずは "aspnetcore-https.js" から。この JavaScript コードが行なっているのは、React 開発サーバーが https でリッスンするようにするための、開発サーバー用サーバー証明書の発行だ。実装としては、この JavaScript プログラム内から "dotnet dev-certs" コマンドを実行することで、.NET SDK によって自己署名証明書を発行するようになっている。

ちなみに "aspnetcore-https.js" JavaScript プログラムの実行によって生成されるファイルは、PEM 形式の証明書である .pem ファイルと、秘密鍵である .key ファイルの 2つのファイルで、そのファイル名は既定では React 側の "packages.json" で指定されるパッケージ名 ("name" ノードの値) となっている。

これらファイルの保存先フォルダは、Windows OS 環境だと、"%USERPROFILE%\AppData\Roaming\ASP.NET\https" フォルダであるようだ。

aspnetcore-react.js

次に "aspnetcore-react.js"。こちらは、先に説明した "aspnetcore-https.js" の実行によって生成された自己署名証明書を、React 開発サーバーが使うように環境設定する JavaScript プログラムとなっている。

具体的には、React 側における ".env.development.local" 環境変数設定ファイルの自動編集という形で実装されている。Rect 開発サーバーは、環境変数 "SSL_CRT_FILE" と "SSL_KEY_FILE" のそれぞれに、証明書ファイルと秘密鍵ファイルのパスを設定しておくことで、https でリッスンできるようになるらしい。ということで、"aspnetcore-react.js" は、最終的に、下記のような内容が記載されているよう、React 側の ".env.development.local" 環境変数設定ファイルを生成・更新するようになっている。

# .env.development.local

SSL_CRT_FILE=C:\Users\...\AppData\Roaming\ASP.NET\https\....pem

SSL_KEY_FILE=C:\Users\...\AppData\Roaming\ASP.NET\https\....key

なお、証明書と秘密鍵を与えただけでは、React 開発サーバーは https でリッスン "できるようになる" だけで、そのままでは https でリッスンするわけではない。React 開発サーバーを https でリッスンさせるには、環境変数 "HTTPS" に "true" を設定しておく必要がある。そして実際、このプロジェクト構成では React 開発サーバーは https でリッスンしてくれるわけだが、ではどこで環境変数 "HTTPS" を設定しているのか。

.env.development

その設定場所は、React 側の環境変数設定ファイルのひとつである ".env.development" である。この環境変数設定ファイルは、プロジェクトテンプレートからのプロジェクト新規作成時に同時に生成されており、その内容は以下のようになっている。

# .env.development

PORT=44474

HTTPS=true

BROWSER=none

上記のとおり ".env.development" に環境変数 "HTTPS" に "true" を設定する指定が含まれている。この設定により、React 開発サーバーは、".env.development.local" で環境変数に設定されたパスの証明書及び秘密鍵を用いて、https でリッスンするようになる。

その他、リッスンするポート番号も、上記例だと 44474 に設定されている。ここのポート番号は、ASP.NET Core 側のプロジェクトファイル (.csproj) 内で指定した、React 側開発サーバーのリッスン URL の指定と一致している必要がある。そうでないと、ASP.NET Core サーバープログラムが、React 開発サーバーが起動しているかどうかの検知ができないからだ。

<!-- .csproj (再掲) -->

...

<PropertyGroup>

  ...

  <SpaProxyServerUrl>https://localhost:44474</SpaProxyServerUrl>

  ...

および、".evn.development" には、環境変数 "BROWSER" に "none" の指定も追加されている。この指定がない場合は、"react-scripts start" による React 開発サーバー起動時に、ブラウザもいっしょに起動してくれる。しかしこの React + ASP.NET Core 構成の場合、Visual Studio ないしは .NET CLI によるプロジェクト起動によっても、./Properties/launchSettings.json の指定に従ってブラウザが起動する。つまりこのままだと、Visual Studio 上で Ctrl + F5 とかでプロジェクト起動したときに、ブラウザウィンドウが 2 つ開いてしまうわけだ。そこで、環境変数 "BROWSER" に "none" を設定することで React 側のブラウザ起動を抑止することで、プロジェクト起動時にブラウザウィンドウが 2つ開いてしまわないように構成しているわけである。

なお、React 側の環境変数設定ファイル ".env.development.local" であるが、ファイル名が "～.local" で終わる環境変数設定ファイルは、開発者個々人の環境に依存する設定を記述するファイルであるため、ソースコード管理には登録しない (してはならない) ファイルである。そのため、プロジェクトテンプレートからプロジェクト新規作成したときに、下記内容を含む ".gitignore" ファイルも同時に生成され、Git リポジトリにソース管理登録されないように構成されている。

# .gitignore

...

.env.local

.env.development.local

.env.test.local

.env.production.local

...

プロクシ

さてここまでで、React 開発サーバーを https でリッスンさせて起動するところまではわかった。残るは、ASP.NET Core サーバーへのプロクシによる中継方法である。これはどのようにして実現されているのだろうか。

プロジェクトテンプレートにて生成される React 側のファイルのひとつに、"./src/setupProxy.js" という JavaScript ファイルがある。もうファイル名から自明のように、この JavaScript プログラムが React 開発サーバー内のプロクシ機能を担っている。

この、プロジェクトテンプレートで作成された "./src/setupProxy.js" であるが、内容を見てみると、ASP.NET Core サーバーのリッスン URL は、環境変数 "ASPNETCORE_HTTPS_PORT" や "ASPNETCORE_URLS" を見て、実行時に動的によしなに判断してくれている。

いっぽうで、「どんな URL パスに対する要求は、ASP.NET Core サーバーへ中継するのか?」という判断は、どうも、この "./src/setupProxy.js" JavaScript プログラム内にハードコードされているように見える。

下記はその該当箇所である。

// ./src/setupProxy.js

...

const context = [

  "/weatherforecast",

];

...

ASP.NET Core サーバー側で提供する Web API エンドポイントの URL パスが、すべて "/api/～" で始まる、などの規則性があれば、"./src/setupProxy.js" は下記のように書き換えておけばよいだろう。

// ./src/setupProxy.js

...

const context = [

  "/api/",

];

...

そのような規則性がない場合は、対象となる URL パスを、"./src/setupProxy.js" にちまちまと書き記していくしかなさそうである。

// ./src/setupProxy.js

...

const context = [

  "/weatherforecast",

  "/userprofile",

  "/draft",

  "/articles",

  "/tags",

  ...

];

...

まとめ

以上、React + ASP.NET Core プロジェクトの開発環境は、上記のようになかなかに凝った仕掛けで実現されていることがわかった。

だがひとたび上記のように理解できると、応用力が格段に上昇する。

例えば、Visual Studio ないしは .NET SDK のプロジェクトテンプレートから作られる React + ASP.NET Core プロジェクトだと、React 側は TypeScript に対応されていないのだが「やっぱり TypeScript で書きたい!」という場合も、

1. いったん ClientApp フォルダ以下はバッサリ削除して、
2. 改めて "npx create-react-app --template typescript" で TypeScript 構成込みで React 側コードを生成しなおし、
3. あとは、"aspnetcore-https.js"、"aspnetcore-react.js"、".env.development"、"./src/setupProxy.js" を復元、
4. "packages.json" の "prestart" スクリプトを書き足し直し

といった手順で対応可能であることがわかるだろう。

まぁ、この例だと、プロジェクトテンプレートが生成した結果に TypeScript 対応するよういじったほうが早いかもしれない。
しかしまぁ、とにかく、仕掛けがわかればできることも増えるはずだ。