@jsakamoto

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 上にその旨通知するとか、問答無用でハードリロードを実行するとか) は、アプリケーションの仕様・要件次第だろう。

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

Visual Studio 2019や dotnet CLI での "発行" 処理時に、発行したファイルを Zip ファイルにまとめる方法

背景

Visual Studio や dotnet CLI を使っての、C# による ASP.NET Core アプリ開発における話。

一般的な ASP.NET Core Web アプリケーションは、インターネット上に配置して利用してもらうものだ。

しかし今回の案件はちょっと変わってて、開発した Web アプリを、クライアント台数が数十台程度の閉鎖系のローカルエリアネットワーク内で稼働させることとなった。

(ちなみに、開発した ASP.NET Core Web アプリを稼働させるサーバーPCは Windows OS が採用された)

そこで、この案件で開発する ASP.NET Core Web アプリは Windows サービス として開発。

サーバーPC上への最初のセットアップ (Windows サービスとしての登録) を済ませた以後は、xcopy 配置にて簡易にバージョンアップできるようにすることとした。

さてこのような形態だと、開発した ASP.NET Core Web アプリは、Visual Studio 上で開発中ならば「フォルダへ発行」のプロファイルで、ファイルシステム上に成果物を吐き出すようにすることもあろうかと思う。

但し、そうして吐き出されるファイルはかなりの本数に上る。

今回の案件だと、発行された成果物のファイル本数は 184 ファイルに達した。

このように発行された成果物のファイル群を、そのままやりとりするのは無茶がある。

通常は Zip などのアーカイブファイル x 1つにまとめて、そのアーカイブファイルをやりとるすることであろう。

ということで本案件でも実際、発行された成果物のファイル群は、単一の Zip ファイルに固めて持ち運ぶこととなった。

プロジェクトファイルにちょっと書き足して、自動で Zip 化!

さて、MSBuild 15.8 からは、「指定されたフォルダ内のファイルを、ディレクトリ構造もそのままに、サブフォルダのファイルも含めてまるっと Zip アーカイブファイルにまとめてしまう」という、"ZipDirectory" タスクが追加されたそうだ。

(そう、それまでは、MSBuild 標準では、Zip アーカイブにまとめる機能は備えられておらず、MSBuild 内で Zip アーカイブを作成するためには MSBuild 拡張を導入する必要があった。)

そこで、今回案件では、Visual Studio から「発行」を行なったら、 (発行された成果物のファイル群を収録した) Zip アーカイブファイルを自動で生成するよう、MSBuild スクリプトを仕込むことにしてみた。

MSBuild スクリプトへの仕込みはあっけない。

対象の MSBuild スクリプトファイル = プロジェクトファイル (.csproj) 内に、下記内容のような <Target> ノードを追記するだけだ。

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

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

  ...

  <!-- ↓この Target 要素を記述 -->

  <Target Name="MakeZipPackage" 

          AfterTargets="AfterPublish">

    <MakeDir Directories="$(ProjectDir)..\_release" />

    <ZipDirectory

      SourceDirectory="$(ProjectDir)$(publishUrl)"

      DestinationFile="$(ProjectDir)..\_release\$(AssemblyName)-v.$(Version).zip"

      Overwrite="true" />

  </Target>

  ...

</Project>

もう少し解説を加えよう。

まず Target 要素の Name 属性を "MakeZipPackage" としているが、このビルドターゲットの名前は重要ではない (衝突しなければ/他のターゲットから依存されていなければ、名前は何でも良い)。

それよりも肝心なのは、AfterTargets 属性で指定している、"AfterPublish" というターゲット名。

すなわちこの指定により、発行が行なわれたあとのタイミングで、上記の「Zip アーカイブを作成する」ターゲットが実行されるようになる仕掛けだ。

あとは MakeDir タスクで、作成する Zip アーカイブファイルの配置先フォルダを作成。
そして最後に満を持して ZipDirectory タスクによって、発行先フォルダの中身を Zip アーカイブファイルにまとめて完了だ。

発行先フォルダのパスは、"$(ProjectDir)$(publishUrl)" で参照できるので、これを "ZipDirectory" タスクの "SourceDirectory" パラメータ (Zip 化対象のフォルダの指定) に渡している。

作成する Zip アーカイブファイルの配置先フォルダは概ねどこでも構わない。

ただしプロジェクトフォルダの直下にするのだけは、ややこしいことになりかねないので止めておくのが良さそうだ。

出力先フォルダ (~/bin) より下のサブフォルダか、あるいはプロジェクトフォルダの兄弟フォルダがいいのではないかと思われる。

上記例では、プロジェクトフォルダの兄弟フォルダのレベルで、"_release" というサブフォルダを作成して、そこを Zip アーカイブファイルの配置先としている。

作成する Zip アーカイブファイルのファイル名も、これまた何でも良い。

上記の例では、ビルドで生成されるアセンブリ (.dll) の名前を "$(AssemblyName)" で参照できるので、、これを Zip アーカイブファイルのファイル名としつつ、さらにパッケージバージョンの指定が "$(Version)" で参照できるので、これを利用して、作成する Zip アーカイブファイルのファイル名の後半にバージョン番号を含めるようにしてみた。

上記例のようなビルドターゲットの MSBuild スクリプトをプロジェクトファイル内に仕込むことで、発行された成果物のファイル群を単一の Zip アーカイブファイルにまとめることができるようになった。

dotnet CLI であれば、下記のように、Release 構成でのビルドを指定しつつ、発行を実行することで、発行成果物ファイル群を収録した Zip アーカイブファイルが生成される。

> dotnet publish -c:Release

複数ある発行プロファイルの内ひとつで Zip 化したい場合

もしも、複数の発行プロファイルを使い分けつつ、そのうちのひとつの発行プロファイルで発行する場合のみ、Zip アーカイブファイルを作成したい場合はどうするか。

いくつかやり方はあるのだが、ひとつの方法として、発行プロファイル内に Zip アーカイブファイルを作成する MSBuild スクリプトを仕込むという方法がある。

先の例で記述した <Target Name="MakeZipPackage" ...>...</Target> 要素をいったん .csproj 内からは削除し、代わりに、対象の発行プロファイル、すなわち .pubxml ファイル内に記述するのだ。

<!-- これは Zip 作成を伴いたい発行プロファイル (.pubxml) -->

<Project ...>

  ...

  <Target Name="MakeZipPackage" AfterTargets="AfterPublish">

    <!-- 中身は先の例と同じ -->

    ...

  </Target>

  ...

</Project>

発行プロファイル (.pubxml) を指定しての発行の場合は、発行対象のプロジェクトファイル (.csproj) と発行プロファイル (.pubxml) を合成しての MSBuild 実行に等しい。

なので、ある特定の発行プロファイルでのみ何かさせたい場合 (今回の例では Zip アーカイブファイルの作成を行ないたい) は、発行プロファイル (.pubxml) 側に MSBuild スクリプトを仕込むことで実現可能である。

ちなみに、dotnet CLI で、発行プロファイル (.pubxml) を指定しての発行を行なうには、下記のように、"PublishProfile" MSBuild プロパティに、発行プロファイル (.pubxml) へのプロジェクトからの相対パスを設定して実行すればよい。

> dotnet publish -c:Release -p:PublishProfile={ここに.pubxmlへの相対パス}

複数ある発行プロファイルの内いくつかで Zip 化したい場合

もうちょっと込み入ったケースでは、複数の発行プロファイルがあって、しかしそのうちのひとつだけではなく、いくつかの発行プロファイルで Zip アーカイブファイルを作成したい、というケースも想定される。

ではということで、Zip アーカイブファイルの作成スクリプトを、複数の .pubxml にベタで書いても、まぁ、それで実現はできる。

しかし、できるのではあるが、"DRY 原則" というか、同じスクリプトがコピペで複数のファイルに散在するのは気持ち悪い。
書いていた Zip 作成のスクリプトに手直しが必要になったら、すべての発行プロファイル (.pubxml) で修正作業をするのもどうかと思うわけである。

このようなケースに対処するにはどうするか。

これまたいくつかやり方があるが、一例として、Zip 化する処理はプロジェクトファイル (.csproj) に記載しつつ、「発行後に Zip アーカイブファイルの作成を行なうかどうか」を MSBuild スクリプト内のプロパティでフラグ表現する方法がある。

まず、Zip アーカイブファイルを作成するターゲットは最初の紹介のとおり、(発行プロファイル (.pubxml) ではなく) プロジェクトファイル (.csproj) 内に記述しておく。

但し最初の紹介例に加えて、"Condition" 属性を追加して、「発行後に Zip アーカイブファイルの作成を行なう」フラグが立てられていたときだけ、Zip アーカイブファイル作成ターゲットを有効とするよう書き加える。

なお、「発行後に Zip アーカイブファイルの作成を行なう」フラグを表現する MSBuild プロパティの名前は何でもよく、スクリプトの実装者が決めればよい。

ここでは "MakeZipAfterPublish" というプロパティ名とすることとし、このプロパティに "true" と設定されていた場合にのみ Zip アーカイブファイルを作成する仕様としよう。
その場合、.csproj 内のターゲットの記述は下記要領となる。

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

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

  ...

  <Target Name="MakeZipPackage" 

    AfterTargets="AfterPublish"

    Condition="'$(MakeZipAfterPublish)' == 'true'"><!-- ←これを追加 -->

    <!-- 中身は先の例と同じ -->

    ...

  </Target>

  ...

</Project>

ここまでの段階ではまだ、発行しても、MSBuild プロパティ ”MakeZipAfterPublish" の値は "true" ではない (既定だと空文字になる) ため、Zip アーカイブファイルは作成されない。

最後の仕上げとして、発行後に Zip アーカイブファイル作成を行ないたい各発行プロファイル (.pubxml) 中で、MSBuild プロパティ "MakeZipAfterPublish" の値に "true" を設定してやればよい。

<!-- これは Zip 作成を伴いたい発行プロファイル (.pubxml) -->

<Project ...>

  ...

  <PropertyGroup>

    <!-- どこでもいいので MakeZipAfterPublish プロパティを "true" で定義 -->

    <MakeZipAfterPublish>true</MakeZipAfterPublish>

    ...

  </PropertyGroup>

  ...

</Project>

こうすることで、Zip アーカイブファイル作成を行なう発行プロファイル (.pubxml) を使って発行を実行すると、プロジェクトファイルの内容 + その発行プロファイルの内容 が合成されて MSBuild が実行されるので、結果、以下の流れで Zip アーカイブファイルが生成されることとなる。

1. 当該発行プロファイル (.pubxml) 内で MakeZipAfterPublish プロパティに true が設定されている
2. プロジェクトファイル (.csproj) 内に仕込んでおいた Zip アーカイブファイル作成ターゲットの Condition 属性による条件を満たす
3. Zip アーカイブファイル作成ターゲットが実行され、Zip アーカイブファイルができあがる

他の実現方法としては、Zip アーカイブファイル作成を行なうターゲット定義を、独立した外部の MSBuild スクリプトファイル (拡張子に決まりはないっぽいが .targets ファイルとか?) に書いておいて、発行プロファイル (.pubxml) からインポートするといった方法も思い浮かぶ。

補足

本投稿では割愛するが、今回紹介したのと同じような要領で、「発行」時ではなく、「ビルド」時に、ビルド成果物のファイル群を自動で Zip アーカイブファイルにまとめるよう、MSBuild スクリプト (.csproj) を記述することも可能だ。

なお、ちょっとした注意事項だが、この MSBuild 標準の "ZipDirectory" タスク、拡張子やファイル名パターンを指定しての、Zip アーカイブファイルへの収録を除外することはできないようだ。

指定したフォルダの中身を、一切合切、Zip アーカイブファイルに収録してしまう他ないらしい。

拡張子やファイル名パターンを指定しての Zip アーカイブファイルへの収録を除外するには、MSBuild 標準の "ZipDirectory" タスクに頼らずに、MSBuild.Extension.Pack NuGet パッケージをプロジェクトに追加して、"MSBuild.ExtensionPack.Compression.Zip" タスクを利用するのがよさそうだ。

• NuGet Gallery | MSBuild.Extension.Pack

まとめ

以上、Visual Studio や dotnet CLI を使っての、ASP.NET Core Web アプリケーション開発における、ファイルへの「発行」時に、自動で、発行成果物ファイル群を単一の Zip アーカイブファイルにまとめる、MSBuild を使った方法の紹介であった。

さてさて、しかしながら昨今であれば、何らかの CI/CD のパイプラインで、このような Zip アーカイブファイルを作成するのかな、と想像する (自分はよく知らない)。

また、Docker イメージを構築して、コンテナ上で稼働させるようなケースでは、単一の Docker イメージとして持ち歩けるので、このような Zip アーカイブファイルにまとめるような需要はそもそも発生しないことだろう。

ということで、今となっては、このような方式で、発行成果物の Zip アーカイブファイルを作成するケースはあまりないかもしれない。

...ところで、MSBuild の v.15.8 って、いつリリースされたんでしたっけ??

EntityFramework Core の ver.3.0 から、"所有されているエンティティ型" に関したテーブル構造が変わってしまった

EFCore の "所有されているエンティティ型"

.NET プログラミングにおけるデータベースアクセスライブラリの定番である、EntityFrame Core (以下、EFCore)。

EFCore を用いたデータベースを読み書きするプログラム開発において用いられる技法のひとつとして、"Code First" と呼ばれる作り方がある。

すなわち、EFCore を基盤とした C# ソースコードとしてデータベースのテーブル構造を記述してプログラムをビルドし、そのプログラムの実行によって、データベースとその構造を自動生成するというものだ。

自分は趣味/仕事の双方で、この "Code First" スタイルのプログラム開発を行なっている。

さてそのような "Code First" スタイルでの EFCore プログラミングにおいて、"所有されているエンティティ型" という機能が EFCore に用意されている。

これは何か、ちょっとサンプルコードを示してみよう。

まず、データベース上で People テーブルにマップすることにする、Person クラスというのを C# ソースコードとして記述する。

public class Person {

  

  public int Id { get; set; }

  

  [Required]

  public string Name {get; set; }

  public double Height { get; set; }

  public double Weight { get; set; }

}

ところで、このプログラム開発において、Height と Weight の 2つのプロパティのペアが、この Person クラスに限らず他の多数のクラス (=テーブル) でも頻出するとしよう。

その場合、Height と Weight の 2つのプロパティを持つ独立したクラスを "所有されているエンティティ型" として作成し (ここでは Metric クラスとする) 各所で再利用できるようになる。

public class Person {

  

  public int Id { get; set; }

  

  [Required]

  public string Name {get; set; }

  public Metric Metric { get; set; }

}

[Owned] // <--  "所有されているエンティティ型" であることを記す

public class Metric {

  

  public double Height { get; set; }

  public double Weight { get; set; }

}

こうして実装したプログラムを実行し、データベースを自動生成されると、次のような People テーブルを作成してくれるのである。

"所有されているエンティティ型" を使った実装について、このサンプルコードだと今ひとつ効能がわかりにくいかもしれない。

しかし、同じセンサーデータ構成をセンサーの数だけ同一レコード上に列として並べたい場合など、効率良く且つミスなく実装できるので便利なのである。

なお、"所有されているエンティティ型" は他にもいくつかその自動生成されるデータベース構造にバリエーションがあるのだが、自分はもっぱら上記サンプルコードで示したようなパターンで利用している。

その他、"所有されているエンティティ型" について詳しくは、公式ドキュメントを参照されたし。

EFCore の v2.x と v.3.0 とで生成されるテーブル構造が異なる!

...と、まぁ、このような "所有されているエンティティ型" を活用したプログラム開発を、EFCore の ver.2.1～2.2 ベースで行なってきた。

そしてあくる日。 

EFCore の次バージョン、ver.3.0 がリリースされたので、手持ちのプロジェクトの EFCore のバージョンを、ver.2.x から ver.3.0 に更新した。

そして動作を確認していたところ、"所有されているエンティティ型" に関して、自動生成されるテーブル構造が変わっていることに気がついた。

まずおさらいだが、EFCore v2.x においては、最初に示したサンプルコードだと、Height および Weight は、C# コード上は double 型なので、自動生成されるデータベース上の型は float NOT NULL というように非 null 許容となっている。
（以下にデータベース構造の図を再掲する）

これは少なくとも自分にとっては直感と相違ない振る舞いである。
もしデータベース上の型を null 許容としたければ、C# コード側を double? と記述することになる。

ところが、である。

EFCore v3.0 だと、同じコードからデータベースを自動生成するようにすると、なんと、C# コード上、"所有されているエンティティ型" に含まれる double 型が、データベース上では float NULL というように null 許容になってしまったのだ（下図）。

これが、"所有されているエンティティ型" に含まれるプロパティではなく、テーブルにマップされるクラス直属のプロパティであれば、これまでと変わらない振る舞いとなる。
すなわち、C# コードの double 型はデータベース上の float NOT NULL に、double? 型は float NULL となるようにデータベース構造が生成される。

この "所有されているエンティティ型" に含まれるプロパティが null 許容になってしまう振る舞いは、現時点での最新バージョン (但し安定版ではない) である v.3.1 Preview 3 や、安定版の最新パッチバージョン v.3.0.1 でも同じであった。

破壊的変更があるのは仕方がないが...

まぁ、EFCore も v.2 から v3 へとメジャーバージョンがあがるくらいなので、破壊的変更があるのは仕方がないとは思う。

また、もう既にこの振る舞いで ver.3.0 として安定版リリースされていることもあるだろうから、今更 ver.2.x と同じ動作に戻すことも無理があろう。

しかしである。

ちょっと問題視してる点、というかホントに困った点は、いろいろ調べた限りでは、どうも、"所有されているエンティティ型" に含まれるプロパティを、明示的に非 null 許容としてデータベース生成する方法がなさそうなのだ。

あちこちに Required 属性をつけたり、OnModelCreating() メソッド内で fluent API であれこれモデルの指定を行なっても、 "所有されているエンティティ型" に含まれるプロパティが null 許容になってしまう動作は変えられなかった。

唯一の回避策としては、データベースマイグレーションの仕組みを使ってデータベース自動生成の処理を C# ソースファイルとして生成し、その自動生成されたマイグレーション用の C# ソースファイルを手で編集して、nullable: true になってる箇所を nullable: false に書き直してくれ、というのである (出典は下記)。

これはちょっとあんまりではないかと個人的には思われるのだが、どうだろうか。

EFCore は Apache License 2.0 のオープンソース製品であり、リポジトリは GitHub にある。

そして EFCore の GitHub リポジトリ上には本件に関する Issue があがっており（下記 #12100）、いちおう EFCore の開発チームはこの問題(?)を承知しているようではある。

また、必要な人はこの Issue (#12100) に投票しよう、との呼びかけもある。

とはいえ、1,000 を超える Issue が開かれたままであり、また、この問題についての Issue についての Vote (投票) 数も目立って多いとはいえず、近い将来の内にも何かしらの対応がなされるのかどうかはあまり期待が持てないでいる。

最後に

この問題(?)を再現するソースコード一式は下記にて公開している。

EFCore の ver.3.x は、ver.2.x に比べていろいろ魅力的な改善が施されており、早く移行したいところではある。

しかし自分がたずさわっているプロダクトではこの件がネックになって、未だに EFCore ver.2.x を使用したまま足踏みしている。

同じ悩みを抱えている方々はいないのだろうか、あるいは、どのように回避されているのであろうか、気になる次第。

File.ReadLines() で開いた Stream を確実に閉じる方法

巨大なテキストファイルでも1行ずつなら処理可能!

.NET Core 3.x 上の C# でのプログラミングにおける話。

改行で区切られた行指向のテキストファイルを、1行ずつ読み取っては何か処理をする、といった場合、自分がよくお世話になるのは、System.IO 名前空間の File クラスに備わっている ReadLines() 静的メソッドだ。

このメソッドに目的のテキストファイルのパスを渡して呼び出してやれば、そのテキストファイルの1行1行を文字列に読み込んで列挙する IEnumerabe<string> が返る。

あとはその返された IEnumerabe<string> を使って、foreach で列挙を回したり、LINQ で加工したりというように、1行1行の処理を実装すればよい。

この File.ReadLines() メソッドは、対象のファイルすべてをメモリに読み込むのではない。  

1行ずつ読み取っては結果の文字列をその都度返すので、未使用となった文字列は適宜ガベージコレクターに回収されるに任せられる。  

その結果、このメソッドは省メモリで動作し、大量の行から成る巨大なテキストファイルも一定の消費メモリだけで安定して処理が行える。

列挙を途中で抜けたらどうなるの?

そんな便利な File.ReadLines() であるが、あるとき、ちょっと困ったことになった。

あんまり遭遇することはないシチュエーションと思われるのだが、File.ReadLines() で行読み取りを開始したあと、最終行まで列挙せずに、途中で列挙を中断する要件に遭遇したのだ。

中断する実装自体は別に問題ではない。  

そうではなく心配なのは、列挙を中断したことで、File.ReadLines() が開いたテキストファイル読み取りの Stream が、開きっぱなしになってしまわないだろうか、という点だった。

もちろん、いずれガベージコレクターに回収されることで、最終的には Stream は閉じられる。  

しかしそれでは、Stream が閉じられるタイミングに予測性がない。

今回自分が遭遇したシチュエーションでは、列挙中断後、即座に Stream が閉じられている必要があったのだ。

ふーむどうしたものかと思いつつ、ちょっと試しに下記のような実験コードを書いて試してみた。

var lines = File.ReadLines(path);

foreach (var line in lines)

{

  Console.WriteLine($"line: {line}");

  break;

}

File.Delete(path);

すなわち、File.ReadLines() でテキストファイル中の行の列挙を開始し最初の1行をコンソールに表示するも、それだけで列挙を中断している。

で、その直後に当該ファイルの削除を試行している。

上記のように、foreach による列挙ループを break で中断したことによって、File.ReadLines() が開いた Stream が開きっぱなしになっているとしたら、続くファイル削除で IOException 例外が発生するはずだ。

実行したところ...

で、実行したところ...

なんと例外も発生せずに、正常にファイルの削除まで実行されたのだ。

自分の予測と違った振る舞いになったため、もう少し調べてみることに。

次は foreach で列挙ではなく、生の列挙子を自分で MoveNext() しながら while ループで列挙する実装を試してみた。

var lines = File.ReadLines(path);

var enumerator = lines.GetEnumerator();

while (enumerator.MoveNext())

{

  var line = enumerator.Current;

  Console.WriteLine($"line: {line}");

  break;

}

File.Delete(path);

するとこちらの実験コードでは、期待どおり (?) に、ファイルの削除で IOException 例外が発生した。  

例外メッセージはもちろん。他のプロセスで対象ファイルが使用中である、というものだ。

なにが起きているのかよくわからなくなってきたので、先の foreach 方式の実験コードをビルドした結果である .dll ファイルを ILSpy で見てみた。

すると、foreach って、using で囲ったコードに展開されているのであった...!  

(知らなかった...)

var lines = File.ReadLines(path);

using (var enumerator = lines.GetEnumerator())

{

  if (enumerator.MoveNext())

  {

    var line = enumerator.Current;

    Console.WriteLine("line: " + line);

  }

}

File.Delete(path);

とはいえ、IDisposable ではなく IEnumerator<string> を using するとは何事だろうか。

さらに ILSpy でコードをたどってようやくわかった。

File.ReadLines() が返す列挙オブジェクト、及び、それが返す列挙子であるが、ちゃんと IDisposable インターフェースを実装していたのだ。

言い換えると、File.ReadLines() が返す列挙オブジェクト、及び、それが返す列挙子を IDisposable インターフェースでキャストすると、ちゃんと IDisposable インターフェースとしての参照が手に入るのであった。

var lines = File.ReadLines(path);

var enumerator = lines.GetEnumerator();

var disposable = enumerator as IDisposable; // <- 非nullになる

それで列挙子を using 節で囲うことで、ちゃんと Stream を閉じる動作につながるのであった。

まとめ

これまで自分はまったく理解していなかったが、列挙子に適宜 IDisposable インターフェースを実装しつつ IEnumerator<T> として公開するのは、定番のイディオムなのであろう。

なので、C# の foreach は、上記のとおり、using で列挙子を囲いつつ MoveNext() で列挙を進めるというコードに展開される仕様なのであろうと理解した。

たぶん、公式を含め、ちゃんとそこかしこのドキュメントに明記されていることなのだろうが、お恥ずかしい、今の今までこの foreach の仕組みをわかっていなかった。

[2019/11/08 追記]

公式ドキュメントについてお知らせ頂いた。

教えて頂いた公式ドキュメントへのリンクはこちら。

たしかに、Dispose する仕様について明記されている。

[― 追記ここまで ―]

さておき、ということで、File.ReadLines() が返す列挙オブジェクトは、foreach で回したり、LINQ で使うぶんには、列挙が途中で中断しても、スコープを抜ける限りはちゃんと Dispose される、ということがわかった。

とはいえ、生の列挙子を自分で while ループで回すときなどは、もし列挙を中断する場合は自分で責任をもって Dispose する必要はある。  

そんな実装が必要になるケースはかなり希だとも思うが...。

なお、MoveNext() が false を返すまですべて列挙し終えた場合は、自前で Dispose しなくても、列挙完了時点で Dispose されるので安心して大丈夫だ。

(File.ReadLines() が返す列挙オブジェクトがそのように実装されているため)。

EntityFramework Core 用にデバッグロガーを仕込む - EFCore v3 編

EntityFramework Core とは

EntityFramework Core (以下 EFCore) とは、C# などの .NET 言語で使用される、データベースアクセス用途のライブラリだ。

この EFCore を使用して、C# などのプログラムからデータベースなどを読み書きする際は、生の SQL 文文字列を記述することは多くなく、大抵の場合はデータベースの要素にマッピングされるクラスやそのプロパティなどの操作を介して行なう (※開発チームの指針に依るかも知れません)。

とはいえ、アプリケーション実装者が書くコード上から生 SQL 文文字列が消えただけで、最終的にデータベースシステムに送り込まれるのは SQL 文である。  

EFCore がその背後で SQL 文を生成してデータベースシステムとやりとりしてくれる訳だ。

EFCore は、プロジェクトの規模やチューニング要件次第ではあるものの、おそらくは多くの場面で便利に使える定番のライブラリであろう。

EFCore が吐く SQL 文を知りたい

そんな便利な EFCore ではあるが、その EFCore が生成・発行する SQL 文文字列を把握したい状況は往々にしてある。

とくに、少々入り組んだクエリを実装したときに、果たして、ちゃんと効率の良い SQL を EFCore が生成できているか、確認したいときなどだ。

ASP.NET Core による Web アプリサーバー側実装において、EFCore が発行する SQL 文を知る方法については、過去に自分のブログ記事としても書いた。

いっぽうで、ASP.NET Core とかではなく、コンソールアプリなど、任意の形態のプログラムにおいて、EFCore が吐く SQL 文を把握したいケースもあろうかと思う。

そのような場合は、ASP.NET Core 上でのときとは違い、自分でロギング周りを配線してやる必要があるらしい。

ネットで検索してみると、以下のような記事が見つかった。

他にもいくつか類似の記事が見つかるが、いずれも、ロガープロバイダを自分でインスタンス化 (new) して差し込むこととなる。

EFCore の ver.3 では使えない!

ところがである。

EFCore のバージョンが、ver.2.x までは上記記事の方法で目的を達成できるのだが、EFCore ver.3 になると、上記記事の実装ではコンパイルができなくなっていた。

例えば、デバッグ出力に SQL 文を出力するように実装してたコードを、EFCore v3 に昇格すると、以下のコンパイルエラーが発生する。

CS1729: 'DebugLoggerProvider' does not contain
a constructor that takes 1 arguments

このエラーメッセージからも察しが付くと思うが、厳密に言うと、EFCore のバージョンというよりも、EFCore v3 が依存している、ロギング周りのパッケージの v3 が、旧バージョン用の上記実装に対して破壊的変更があったのである。

具体的には、旧バージョンでは、ロガープロバイダ (ConsoleLoggerProvider や DebugLoggerProvider など) のコンストラクタには、ログの分類 (カテゴリ) やレベルに応じた絞り込みを行なうフィルタ関数を、そのコンストラクタ引数に受け取るオーバーロードバージョンが用意されていた。

それが ver.3 以降は、そのようなオーバーロードバージョンのコンストラクタが廃止されたのだ。

(ver.2.x 時代から、すでに Obsolete 属性でマーク、すなわち廃止予定であるとちゃんと示されていたようではある。)

EFCore ver.3 からは LoggerFactory.Create が便利

ではどうするのかというと、LoggerFactory.Create() を使ってロガーを構成するやり方が使えるらしい。

なお、下記公式ドキュメントを見ると、ロガーの構成方法はそれはもう色々ありすぎて習得するのも骨が折れる印象だ。

さておき、詳細は公式ドキュメントに譲るとして、ざっくり下記のようなコードにて、デバッグ出力に EFCore が発行する SQL 文が出力されるようになった。

using Microsoft.EntityFrameworkCore;

using Microsoft.Extensions.Logging;

...

// 以下、LoggerFactory の構築方法が v.2.x 以前と異なる。

var loggerFactory = LoggerFactory.Create(builder =>

{

  builder

    .AddDebug()

    .AddFilter(

      category: DbLoggerCategory.Database.Command.Name,

      level: LogLevel.Information);

});

// ここから以降はこれまでと変わらず、構築した LoggerFactory を差し込むだけ。

var option = new DbContextOptionsBuilder<MyDbContext>()

  ...

  .UseLoggerFactory(loggerFactory)

  .Options;

var dbContext = new MyDbContext(option);

...

まとめ

他にも LoggerFilterOptions オブジェクトを使ってログフィルターを構成するとか、上記実装例にしても、AddFilter() 拡張メソッドには少なくとも 9 種のオーバーロードバージョンがあったりとか、様々なやり方があるようだ。

とりあえず自分が検証した範囲では、上記実装例が、この用途ではいちばんシンプルに書けたので、ここに紹介する次第。

以上、EFCore v3 で、発行される SQL 文をログ出力する方法であった。

.NET Core 3.0 の単一実行可能ファイル生成を手なずける

.NET Core 3.0 の単一実行可能ファイル生成

先日、公式リリースとなった .NET Core 3.0。

その新機能のひとつとして「単一ファイルの実行可能ファイル」を発行する機能がある。

これまでは、C# や VB、F# など .NET Core プラットフォームのプログラムをビルド・発行した場合、その最終成果物は、各種 .dll ファイル群がごちゃっと発行先フォルダに出力されるだけであった。

それが、.NET Core 3.0 の新機能「単一実行可能ファイル生成」を用いると、発行先フォルダには、たったひとつだけの実行可能ファイルが生成されるだけとなり、配布などの取り扱いが容易になる。

(なお、本機能の動作原理は、たとえて言うならば tar のような、どうやらある種の "アーカイブ" として必要 .dll ファイル群を単一実行可能ファイル内に収録しているようである)

もっとも、これまでも ILMerge や ILRepack などなど、.NET プラットフォームのバイナリを単一ファイルにまとめる手法やツールは存在していた。

とはいえ、.NET Core SDK 本体に類似の機能が標準で搭載されており、すぐに使える点は大変便利である。

ということで、Windows OS 上で Visual Studio 2019 を使った開発体制にて、「単一実行可能ファイル生成」を実際に試してみた。

まずは動作を確認

まずは試しにということで、Visual Studio 2019 のプロジェクトテンプレートから .NET Core コンソールアプリケーション (今回は言語は C#) を生成。

"Hello World" を表示するだけの C# プログラムだ。

そして下記記事を参考に、.csproj ファイルに2行書き加えてみる。

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

<PropertyGroup>

<OutputType>Exe</OutputType>

<TargetFramework>netcoreapp3.0</TargetFramework>

<PublishSingleFile>true</PublishSingleFile>

<RuntimeIdentifier>win10-x64</RuntimeIdentifier>

</PropertyGroup>

</Project>

まずはここまででビルドして実行してみる。まぁ、普通に成功することを確認。

続けて、いよいよ発行である。

Visual Studio 2019 上の開発作業ということで、Visual Studio 上でフォルダへの発行プロファイルを作成し(下図)、発行を実行。

すると、手順どおりにやっているのだから当たり前であるが、無事、発行先には .exe ファイルがひとつだけ生成された。(実行環境に 64bit Windows10 OS を指定しているので、生成される実行可能ファイルは拡張子 .exe の PE ファイルである。)

なお、たかが "Hello World" を表示するだけのコンソールアプリケーションであるが、その実行可能ファイルのサイズは 65.8MB になってしまった。

まぁ、ターゲットランタイムがポータブルでない、且つ、配置モードが自己完結 (Self-Contained) な発行成果物を、非圧縮でアーカイブしているだけのようなものなので、こんなものだろう。

他の OS 用にも発行できる

なお、.NET Core といえばクロスプラットフォームである。

ということで、上記プロジェクトを、例えば 64bit Linux 用に単一実行可能ファイルを発行したい場合はどうするか?

これはもう、何も難しいことはない。

ただただ単純に、ターゲットランタイムとして "linux-64" を指定した発行プロファイルを作成して、その発行プロファイルで発行すれば良いだけである (下図)。

だがしかし、そのプロジェクト、Windows 専用になってない?

さてところで、上記までの手順だと、プロジェクトファイル内にターゲットランタイム指定が記載されているため、発行ではなくビルドの時点でも、64bit Windows10 用のバイナリを吐くように規定されてしまっている。

このようなプロジェクトファイルを、Linux や macOS など他の OS 上でビルドするとどうなるか?

まぁ、実はビルドは成功する。

だが、さすがに実行まではできない。

(※実は、Windows10 上の Windows Subsystem for Linux, いわゆる WSL の中だと実行できてしまったりもするのだが、それはまた別の話。)

かといって、ターゲットランタイムの指定をプロジェクトファイル内から記述削除し、ポータブル形式でてビルドしようとしても、今度はビルドが下記エラーで失敗するようになってしまう。

error NETSDK1097:

RuntimeIdentifier を指定せずにアプリケーションを単一ファイルに発行することはサポートされていません。

RuntimeIdentifier を指定するか、PublishSingleFile を false に設定してください。

".NET Core といえばクロスプラットフォームである" といっておきながら、これはいただけない。

どうしたものか?

発行プロファイルで指定する

答えは

「単一実行可能ファイル生成の指定は、プロジェクトファイル (.csproj) に書かない。代わりに発行プロファイル (.pubxml) に書く。」

である。

Visual Studio で開発していての発行プロファイルとは、その実態は、Properties フォルダ以下に配置された拡張子 .pubxml のファイルであり (下図)、プロジェクトファイル (.csproj) に対する差分である。

ということで、まずは .csproj ファイルからは、先ほど追加した単一実行可能ファイル生成およびターゲットランタイム指定の2行を削除して、元に戻す。

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

<PropertyGroup>

<OutputType>Exe</OutputType>

<TargetFramework>netcoreapp3.0</TargetFramework>

</PropertyGroup>

</Project>

次に、先に作成していた発行プロファイルを (Visual Studio の発行プロファイル編集 GUI 経由ではなく) エディタで開いて直接編集し、"<PublishSingleFile>true</PublishSingleFile>" の行を追加する。

(※ターゲットランタイム指定 ("<RuntimeIdentifier>～</RuntimeIdentifier>") は既に含まれているはず)

<?xml version="1.0" encoding="utf-8"?>

<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

<PropertyGroup>

...

<RuntimeIdentifier>win10-x64</RuntimeIdentifier>

<PublishSingleFile>true</PublishSingleFile> <!-- ← これを追記 -->

</PropertyGroup>

</Project>

以上で OK だ。

これでこのプロジェクトは、どの OS 上であっても、ターゲットランタイム = ポータブルとしてビルド・デバッグ実行可能となる。

その上で、上記発行プロファイルを使って発行すれば、64bit Windows 10 上で直接実行可能な (.NET Core Runtime の事前インストールも不要な) 単一ファイルの実行可能ファイルが手に入る。

もちろん、他の OS 用に発行プロファイルを変更したり発行プロファイルを追加したりしてもよい。

補足1 - dotnet CLI での開発時

冒頭で示した公式ドキュメントを見ると、dotnet CLI を使う場合は、dotnet CLI 実行時のコマンドライン引数に、ターゲットランタイム指定と、単一実行可能ファイル生成指定を行なう方法が説明されている (下記例)。

> dotnet publish -r win10-x64 /p:PublishSingleFile=true

このように、やはりプロジェクトファイル内では単一実行可能ファイル生成の指定はせず、発行時に個別に単一実行可能ファイル生成の指定を行なう (この例で言えば、dotnet CLI のコマンドライン引数で指定する) のがよさそうである。

また、dotnet CLI を使った場合でも下記要領にて、今回説明したような発行プロファイルを用いた発行をすることもできる。

dotnet publish /p:PublishProfile=<ここに.pubxmlファイルのパス>

補足2 - Visual Studio 2019 の発行プロファイル編集 GUI がおかしい

ここまでわざと気づかぬフリをしてきたが、実はここまで説明してきた手順だと、本記事のスクリーンショットにもちょっと見えているが、Visual Studio 2019 の発行プロファイル編集 GUI の表示上は、配置モードが「フレームワーク依存」と表示されてしまっている。

しかし実際に発行される内容は、配置モード = 「自己完結」 (Self-Contained) な内容となっている。

実はこれ、ターゲットランタイム指定 (RuntimeIdentifier) が指定されていると、配置モード指定が明示的に設定されていない場合、どうやらビルドスクリプト上は配置モードのデフォルト値が、「フレームワーク依存」から「自己完結」に切り替わっているようなのである。

ただ、そのビルドスクリプトの仕様が Visual Studio 2019 の発行プロファイル編集 GUI には反映されていないようで、すなわち、Visual Studio 2019 の発行プロファイル編集 GUI では、配置モードの指定が明示的に設定されていない場合は「フレームワーク依存」と表示されているようだ。

ぐだぐだ書いたが、このような混乱を避けるには、配置モード指定を発行プロファイル内に明記してしまえばよい。

...

<SelfContained>true</SelfContained> <!-- ← これを明記 -->

</PropertyGroup>

</Project>

あるいは Visual Studio 2019 の発行プロファイル編集 GUI 上で、配置モードを明示的に「自己完結」に選択し直しておいても OK だ。

このように常に配置モードの指定を明示的に設定しておくようにすれば、要らぬ混乱を避けられるであろう。

なお、この逆に、配置モードを「フレームワーク依存」として明示的に設定して単一実行可能ファイル生成指定で発行したらどうなるか?

そうすると、OS に別途 .NET Core ランタイムの事前インストールが必要となるが、サイズは極小となる、そのような単一実行可能ファイルが発行先に生成される。

.NET Core SDK がインストール済みであることが前提な開発者向けのツールなど、これはこれで需要あるかもしれない。

まとめ

単一実行可能ファイル生成は、その機能の性質上、ターゲットランタイムの指定が必須である。

そのため、単一実行可能ファイル生成の指定は、プロジェクトファイルに記入するのではなく、発行プロファイルに記入しておくのが、自分的にはお勧めである。

[2019/12/29 追記]

Visual Studio 2019 v.16.4.2 で発行プロファイル編集の GUI を開いたところ、[単一ファイルの生成] チェックボックスが増えていた!

このチェックを On にすると、本記事で示したように、発行プロファイル (.pubxml) 中に "<PublishSingleFile>true</PublishSingleFile>" が書き込まれる。

もちろん、.pubxml を直接エディタで編集しても何ら問題ないが、このように GUI 上でも設定できるのはやはり便利である。

Entity Framework Core でデータベースを読み書きする ASP.NET Core アプリ開発中に、発行される SQL 文字列を確認する

背景 - EFCore が出力する SQL 文を知りたい

データベースを読み書きする ASP.NET Core Web アプリ実装において、データベースアクセスライブラリの選択肢としてとりあえずオーソドックスな "Entity Framework Core" (以下 EFCore)。

EFCore およびその前身である "Entity Framework" の面白いところは、データベースクエリの結果をオブジェクトに "マップ" する O/R マッパーというだけでなく、C# コードとして記述されたラムダ式木に基づく SQL クエリビルダーでもあるという側面がある。

さてそんな EFCore であるが、だがしかし、期待していたのとは異なる SQL が発行される可能性も少なくない。

とくに EFCore の ver.2.x だと、GROUP JOIN ですら、簡素な SQL を発行して早々にデータベースから多量のレコードをオブジェクトとして読み込んでしまい、オンメモリで残りの処理を実行することもあるという。

なお、本ブログ執筆時点では未だリリースされていない、次バージョン EFCore 3.x では、このあたりの挙動が変更され、SQL に変換できないクエリは例外を発生させることになるらしい。

この辺りの話題は、下記などが参考になる。

そんなこともあり、とくにアプリ開発中は、EFCore が発行する SQL 文を確認したいところである。

なお、コンソールアプリなどで EFCore 使用時に、その発行する SQL を確認するには、その目的のロギング機構を組み立てて適用すればよい。

詳しくは下記などが参考になる。

実は開発時ログ出力には、既に含まれている

さてさて、ASP.NET Core アプリ開発中は、一般的なプロジェクトテンプレートから起こしたプロジェクトであれば特に、すでにロギング機構が組み込まれており、且つ、開発時向けのログレベル構成が適用済みである。

下記は開発時用構成ファイルである appSettigs.Development.json 中のログレベル構成だ。

{

"Logging": {

"LogLevel": {

"Default": "Debug",

"System": "Information",

"Microsoft": "Information"

}

}

この構成だと、Visual Studio で開発中であれば、Visual Studio の出力ウィンドウに色々ログが流れているのが確認できる。

(※デバッガなし実行でも表示される)

また、dotnet CLI を使ってる場合も "dotnet run" などで実行すると、コンソールにログが流れるのを見ることができる。

実は既に、EFCore が出力する SQL 文は、このログの中に表示されているのだ。

よーく見ると、EFCore が出力する SQL 文が、ログの中に表示されているのを見つけることができる (下図、赤丸のところ)。

大量のログ出力に埋もれてしまう...

しかしである。

上図でもわかるように、このままでは、ブラウザ等からの要求ごとの ASP.NET Core 関連ログが大量に発生し、EFCore の SQL 文ログがそれらログに埋もれてしまう。

(ないしは、あっという間にスクロールアウトしてしまう)

実際問題として、この構成のままでは、大量のログの中から EFCore が出力する SQL 文を探し出して確認するという作業はあまり現実的ではない。

これは個人的な意見であるが、実のところ、ASP.NET Core 関連の要求処理時の情報ログは、あまり必要を感じない。

どのようなリクエストがブラウザから発生しているかを見るときは、どちらかといえば、ブラウザの開発者ツールで確認するだけで用が足りることがほとんどだ。

EFCore 以外のログレベルを調整

ということで、appSettings.Development.json を改訂し、"Microsoft" カテゴリのログレベルを "Information (情報)" から "Warning (警告)" レベルに引き上げてしまうと良かろう。

そうすることで、ASP.NET Core 関連の大量の情報ログが表示されなくなる。

ただしそれだけだと、EFCore の SQL 文出力も同じく表示されなくなってしまう。

そこで、EFCore の SQL 出力だけはログ出力されるよう、"Microsoft.EntityFrameworkCore.Database.Command" カテゴリのログレベルを、再び "Information" としてオーバーライドするとよい。

最終的な appSettigs.Development.json は下記のような感じになる。

{

"Logging": {

"LogLevel": {

"Default": "Debug",

"System": "Information",

"Microsoft": "Warning",

"Microsoft.EntityFrameworkCore.Database.Command": "Information"

}

}

}

これで下図のような感じで、EFCore の出力する SQL 文だけが都度流れるようになる。

自分の開発スタイルとしてはこれくらいのログレベルでちょうどいい感じだ。

以上、すべてのケースでこのログレベル構成が最適とは言わないが、同じような境遇の人にこの情報が役に立てば幸いである。

補足

データベースアクセスのためには、EFCore 以外にも選択肢はいろいろあるので、発行される SQL を完全に制御したい場合などは、無理に EFCore を使う必要もない。

下記など参考にされたし。

ASP.NET Core での単体テスト内で、オプションおよびサービスプロバイダを作成する

C# による ASP.NET Core プログラミングにおける、単体テストを実装していての話題。

ネットで検索すればすぐに見つけられるような内容かとも思うが、自分の為の備忘録を兼ねてここに記す。

さて、前述のとおりの単体テストを実装している際、IOption<T> をコンストラクタ引数に求めるオブジェクトをテスト対象とすることがある。

さらにたまーにではあるが、コンストラクタ引数に IServiceProvider を直に要求するオブジェクトを扱うこともある。

このようなケースで、どのように IOption<T> ならびに IServiceProvider をテストプログラム中でインスタンス化すればよいか、という話である。

IOption<T>

ASP.NET Core におけるオプション構成は、通常は Startup クラス中の ConfigureServices メソッド内で初期化するのが通常だ (下記は MyOptions 型のオプションを appSettings.json などの構成情報から読み取って取得する例)。

public class Startup

{

private IConfiguration Configuration { get; }

public Startup(IConfiguration configuration)

{

Configuration = configuration;

}

public void ConfigureServices(IServiceCollection services)

{

services.Configure<MyOptions>(this.Configuration.GetSection("My"));

...

こうしておくと、MVC/API コントローラなどで MyOptions 型のオプション情報が必要な場合は、そのコンストラクタ引数として IOptions<MyOptions> 型の引数を用意しておけば、依存性注入機構によって引き渡されるようになっている (下記例)。

public class MyController : Controller

{

private IOptions<MyOptions> MyOptions { get; }

public MyController(IOptions<MyOptions> myOptions)

{

this.MyOptions = myOptions;

...

さてこのような IOption<T> を自前のテストコード中で直に生成するには、Microsoft.Extensions.Options 名前空間の Options クラスの Create<T>(T options) 静的メソッドを用いる。

この Create<T>(T options) 静的メソッドの引数に、任意の型 T のオブジェクトを渡せば、その戻り値で IOption<T> が返る　(下記例)。

using Microsoft.Extensions.Options;

...

IOptions<MyOptions> myOptions = Options.Create(new MyOptions {...});

IServiceProvider

IServiceProvider を自前のテストコード中で生成するには、Microsoft.Extensions.DependencyInjection 名前空間の、ServiceCollection クラスを使う。

手順としては、まずは ServiceCollection クラスをインスタンス化する。

次にこの ServiceCollection オブジェクトに対し、AddSingleton<T1,T2>() などをはじめとしたおなじみのメソッドを呼び出して、そのテストで必要となるサービスを登録しておく。

(すなわち、IServiceProvider を要求しているテスト対象のコード中では、その IServiceProvider に対して GetService<T1>() とか呼び出して、サービスを入手しているであろうため)

以上の準備が整ったら、ServiceCollection オブジェクトの BuildServiceProvider() メソッドを呼び出す。

そうすると、BuildServiceProvider() メソッドの戻り値として、IServiceProvider が返る。

var services = new ServiceCollection();

services.AddSingleton<IMyService, MyServiceMock>());

...

var serviceProvider = services.BuildServiceProvider();

使い終わったら、Dispose() メソッドを呼び出してリソース破棄しておくことを忘れずに。

以上!

Azure Storage Emulator v.5.9 をインストールするも create database でエラーとなって動かない

Windows OS 上で C# による Azure Functions 開発を行なおうとしての話。

とある事情でまっさらの環境に Visual Studio 2019 をインストールするところから開始。

Visual Studio 2019 のインストーラにお任せで、Azure Storage Emulator (ver.5.9) や SQL Server 2017 Express および LocalDB も自動でインストールされるに任せた。

ということで早速にプロジェクトテンプレートからちゃっちゃっと C# で Azure Function プロジェクトを作り、Ctrl + F5 でビルド & 実行。

Azure Functions は背後で Azure Storage を使っている関係で、開発環境におけるローカル実行時は、Azure Storage Emulator がローカル環境で起動される。

...が、なんとここで想定外に、Azure Storage Emulator がエラーを吐いて起動に失敗してしまった。

エラーの原因は「データベースを作れません」!?

コンソールには以下のとおり出力されていた。

Error: Cannot create database 'AzureStorageEmulatorDb59' : The database 'AzureStorageEmulatorDb59' does not exist. Supply a valid database name. To see available databases, use sys.databases..

Azure Storage Emulator がその永続化層に使用するために、SQL Server LocalDB に "AzureStorageEmulatorDb59" という名前のデータベースを作ろうとするも、何やら上手くいっていないようである。

とりあえずネットで検索してみると、StackOverflow に同様のトラブルでの質問投稿を発見した。

今までこんなトラブルに遭遇したこともなくて、Azure Storage Emulator を使い倒したこともなく知らなかったのだが、上記 StackOverflow のスレッドを見ると、Azure Storage Emulator には様々なコマンドライン引数指定ができるとのこと。

例えば、"/forceCreate" スイッチ付で、"init" を指定することで、データベースが壊れた場合でも再作成・最初期化できるとのこと。

> AzureStorageEmulator.exe init /forceCreate

まずは自分のこのケースでも上記コマンド実行を試してみた。

しかし残念ながら、自分のケースでは表示されるエラーメッセージは変らず。

ちゃんとエラーログを読もう

さらに先の StackOverflow をスレッドを読み進めるに、まぁ、ちゃんとログ読もうぜ、という話らしくて、改めてちゃんと、Azure Storage Emulator のエラーログファイルを見てみることにした。

ちなみに Azure Storage Emulator のエラーログファイルは、下記フォルダに「error.log」というファイル名で保存されている。

%USERPROFILE%\AppData\Local\Microsoft\Microsoft SQL Server Local DB\Instances\MSSQLLocalDB

error.log ファイルの内容を "AzureStorageEmulatorDb59.mdf" で検索してみたところ、下記行を発見。

2019-06-09 11:24:13.15 spid52      CREATE FILE encountered operating system error 5(Access is denied.) while attempting to open or create the physical file 'C:\Users\jsakamotoAzureStorageEmulatorDb59.mdf'.

よーく見ると、作成しようとしているデータベースの物理パスがなんかおかしい。

'C:\Users\jsakamotoAzureStorageEmulatorDb....'

となっているが、あれ、ユーザーフォルダ名 (C:\Users\jsakamoto) とファイル名 (AzureStorageEmulatorDb59.mdf) との間のディレクトリ区切りが無くなってない?

正しくは

'C:\Users\jsakamoto\AzureStorageEmulatorDb....'

じゃないですか?

どうしてこうなった?

原因は SQL Server 側の不具合?

先の StackOverflow のスレッドを見直していると、コメント欄に答えがあった。

Indeed this was the issue. I installed CU13 HotFix for SQL Server 2017 and it works now. – Andrii Mar 8 at 21:07

どうやら CU13 という SQL Server 用の Hotfix で本現象は解消できるらしい。

つまり SQL Server LocalDB 側の不具合だったということだろうか。

ということで上記コメントのリンクをたどりながら下記から CU13 Hotfix をダウンロードして適用すれば直るらしい。

https://www.microsoft.com/en-us/download/details.aspx?id=56128

他の回避策

ただちょっと今回は事情があって、冒頭で "とある事情でまっさらな環境に..." とか書いたように、すぐにダウンロード & インストールできない、特殊な状況であった。

自分がこれまで今回のようなトラブルに遭遇しなかったのも、おそらくはインストールしたての環境ではなくて、ちゃんと最新の Update を適用済みの環境だったからかもしれない。

さておき、今の状況ではこれは詰んだかなー、と諦めようかと思っていたところ、別の回避策を発見。

先にも書いたが、Azure Storage Emulator にはいろいろなコマンドライン引数指定ができるのだが、その中に、永続化層に使用する SQL Server インスタンスを指定する方法があるとのこと。

具体的には、"/server" スイッチに続けて、使用する SQL Server インスタンスを指定して、"init" 動作を指定するらしい。

試しにと言うことで、この環境にインストール済みである、SQL Server 2017 Express のインスタンス (インスタンス名は "SQLEXPRESS") を使用するように、Azure Storage Emulator を構成・初期化してみることにした。

> AzureStorageEmulator.exe init /server .\SQLEXPRESS

すると、CU13 Hotfix が未適用でも、ちゃんと Azure Storage Emulator 用に、データベース AzureStorageEmulatorDb59 が SQL Server 2017 Express 上に作成された。

Windows Azure Storage Emulator 5.9.0.0 command line tool
Attempting to use server specified.
User specified an instance through /server or /sqlInstance options.
Probing SQL Instance: '.\SQLEXPRESS'.
Found SQL Instance .\SQLEXPRESS.
Creating database AzureStorageEmulatorDb59 on SQL instance '.\SQLEXPRESS'.

Granting database access to user MyPC\jsakamoto.
Database access for user MyPC\jsakamoto was granted.

Initialization successful. The storage emulator is now ready for use.
The storage emulator was successfully initialized and is ready to use.

もちろんその後の Azure Functions プログラムのローカル実行も難なく実行されるようになった。

もちろん CU13 Hotfix も有効!

後日、CU13 Hotfix を適用後に、改めて "AzureStorageEmulator.exe init" を実行したところ、こちらも無事成功し、SQL Server LoacDB 上でも正常稼働するようになった。

まとめ

ということで、 Azure Storage Emulator のコマンドライン引数指定、"init" コマンド実行に加えて付属のスイッチ群 "/forceCreate" "/server" などについて知っていると、何かトラブルの際に役立つかも知れない。

以上。

node のバージョンあげたら node-sass の npm instal でこけた話 - windows-build-tools 入れずに解決させる

Windows OS 上で SPA を開発していてのお話。

先日、しばらく前に構築した、とある Web アプリ (SPA) プロジェクトを保守する必要が出てきた。

久しぶりに当該プロジェクトをリモートリポジトリからローカル開発環境に git clone し、とりあえず npm install を実行したところ、いきなりエラーになってしまった。

npm ERR! node-sass@4.7.2 postinstall: `node scripts/build.js`

npm ERR! Exit status 1

npm ERR!

npm ERR! Failed at the node-sass@4.7.2 postinstall script.

どうやら、SaSS を CSS へ変換する Node.js 用ライブラリ node-sass のパッケージインストールでこけたっぽい。

使用している node-sass のバージョンは v.4.7.2。

開発当時はちゃんとクリーンビルド成功してたのに、なんで?

Node.js のバージョンが当時と今とで違う

当該プロジェクトの開発当時と、今回とで環境で変っていたのは Node.js のバージョンだった。

開発当時、インストールされていたのは、たしか Node.js の v.8 系。

現在は Node.js を v.10.15.3 にアップデートしたあとの環境である。

どうも、この Node.js のバージョン違いが、開発当時は問題なくて、現在だと npm install できなくなる原因らしい。

さて、この npm install できなくなる問題をどうにかしないと、本題の保守作業に入ることもままならない。

どうしたものか。

Python や C/C++ の環境が必要?

インターネット検索した感じだと、どうやら、node-sass のバイナリビルドのために、Python 2.x や C/C++ の環境が必要らしい。

で、macOS や Linux 系列だと、だいたい Python や gcc 入ってたりするので、すんなり node-sass のバイナリビルドが済んでしまう模様 (あくまでもネットで聞きかじった情報であるが)。

ところが Windows OS ではそのあたりでひっかかって、node-sass のバイナリビルドができずに npm install がコケて終わり、となるらしい。

たしかに自分の場合も、それっぽいログが表示されていた。

gyp ERR! stack Error: Can't find Python executable "python", you can set the PYTHON env variable.

gyp ERR! stack at PythonFinder.failNoPython (C:\Work\app1\node_modules\node-gyp\lib\configure.js:484:19)

gyp ERR! stack at PythonFinder.<anonymous> (C:\Work\app1\node_modules\node-gyp\lib\configure.js:509:16)

gyp ERR! stack at C:\Work\app1\node_modules\graceful-fs\polyfills.js:282:31

このような場合の定番の解決方法は、「npm install --global windows-build-tools」を実行して、Windows OS 上でもそれらビルドに必要な環境を npm でインストールしてしまえばよいようだ。

でもちょっと待て欲しい。

開発当時は、そのようなビルドツールが未インストールでも、すんなり npm install できていたのだ。

なんでだろう?

ビルド済みバイナリが GitHub 上にある!

いろいろ調べていくうちにだんだんとわかってきた。

まず、node-sass の Node パッケージスクリプトは、常にはバイナリビルドを実行しようとはしない。

まずは node-sass の GitHub リポジトリに登録されている、ビルド済みバイナリのダウンロードを試みるようだ。

そして、ダウンロードしようとしている node-sass のビルド済みバイナリのファイル名の末尾には、対応している Node.js 実行環境の "モジュールバージョン" が含まれていた。

具体的には、Windows OS 用バイナリの場合、
「win32-x64-{ここにモジュールバージョン}_binding.node」
というファイル名になる。

node-sass の GitHub リポジトリで調べてみると、node-sass v.4.7.2 のビルド済みバイナリは、モジュールバージョン 57 まで登録がある。

しかし今回の開発環境 Node.js v.10.15.3 のモジュールバージョンは 64 であった。

ということで、node-sass の GitHub リポジトリには登録のない、"v.4.7.2 で、且つモジュールバージョンが 64" であるビルド済みバイナリのダウンロードを試みて失敗 (HTTP 404 Not Found) となっていたようだ。

(下記はその証拠の npm install ログ表示。)

> node-sass@4.7.2 install C:\Work\app1\node_modules\node-sass

> node scripts/install.js

Downloading binary from https://github.com/sass/node-sass/releases/download/v4.7.2/win32-x64-64_binding.node

Cannot download "https://github.com/sass/node-sass/releases/download/v4.7.2/win32-x64-64_binding.node":

HTTP error 404 Not Found

なお、node-sass の Node パッケージスクリプトは次なる手段としてローカル環境でのバイナリビルドを開始する。

だがしかし自分の環境ではビルド用のツールの整備がなっていないので、これもコケてしまい結局エラーで終了、ということだったらしい。

さて、改めて node-sass の GitHub リポジトリの Release ページを見てみると、ちゃんとビルド済みバイナリが用意済みの、対応されている Node.js バージョンが明記されている。

これを頼りに今回は node-sass v.4.9.0 以降を使用するよう packages.json を更新した。

その結果、自分のローカル環境にビルドツール類をインストールすることなく、無事 npm install が成功するようになった。

まとめ

ということで、Windows OS 上で、必ずしも windows-build-tools Node パッケージの利用をはじめビルドツールの整備をしなくても、node-sass のバージョンを適切にアップデートしていけば、すんなり npm install を通すことはできる、という話。

なお、Node.js のいつのバージョンからかよく覚えていないが、最近の Node.js Windows 版のインストーラーでは、ビルドツールも一緒にインストールするかどうかの選択肢が出てきてるっぽい。

この選択肢を有効にして Node.js をインストールしてある環境ならば、このような node-sass を npm install できない問題は起きないのだろうか。

検証したことはないが、気になるところである。