@jsakamoto

認証が有効な Blazor Wasm アプリで、アクセストークンなしで匿名アクセス可能なエンドポイントに HTTP リクエストを送信する

C# で Single Page Application (SPA) を実装できるフレームワーク "Blazor (ブレイザー)"、その WebAssembly 版を使っての SPA 開発中の話。

プロジェクトテンプレートから認証有効 な Blazor Wasm アプリを作るのは簡単

ある日、ASP.NET Coreサーバーでホストされている、認証対応の Blazor WebAssembly アプリを作ることになった。

過去にも、Twitter 認証する Blazor WebAssembly アプリを作ったことはある。

そのときは認証後のセッション情報はブラウザの Cookie を使う方式で実装していた。

そのため、ユーザー情報を内蔵した、また、アクセストークンを使用する方式の Blazor WebAssembly アプリを実装したことはこれまではなかった。

なお、自分は普段は Windows OS の Visual Studio を使って Blazor アプリを開発している。

そのため、下図のとおり、Visual Studio のプロジェクトテンプレートから認証機能付き Blazor WebAssembly アプリを作るのはとても簡単なことだ。

こうして実装した Blazor WebAssembly は認証後のセッション情報はアクセストークンとしてクライアント側に保持される。

この Blazor WebAssembly アプリでは、想定どおり、[Authorizaition] 属性を付与した Web API エンドポイントは匿名アクセスから保護されるようになっていた。

次は公開 API エンドポイントを追加

続けてこのアプリに、"最近の更新" ニュースフィードを一覧表示する機能を実装することになった。

"最近の更新" ニュースフィードのリストは、サーバー側で生成、Web API エンドポイントを経由してクライアント側に提供するように実装。

なお、要件として、このニュースフィードは、ログインしていないユーザーでも公開される必要があった。

そのため，匿名アクセスを許可する目的で，"最近の更新" リストを提供する API エンドポイントには [Authorization] 属性を付与しないよう実装した。

[ApiController]

[Route("[controller]")]

public class RecentlyUpdatesController : ControllerBase

{

  [HttpGet]

  public IEnumerable<string> Get()

  {

    ...

この API 実装を、資格情報なしの cURL コマンドでテストしてみたところ、もちろん問題なく動作た (下図)。

だがしかし... 捕捉されない例外が発生!

サーバ側の実装が完了、続けてクライアント側の実装に取り掛かった。

DI 経由で注入された「HttpClient」オブジェクトを使い、その匿名アクセス可能な API エンドポイントから "最近の更新" リストを取得するコードを記述。

そこまで実装してアプリを実行してみた。

しかし残念ながら、予期せぬことに、画面上に "最近の更新" リストが表示される代わりに何かのエラーが発生してしまった。

Microsoft.AspNetCore.Components.WebAssembly.Rendering.WebAssemblyRenderer[100]

  Unhandled exception rendering component: ''

  Microsoft.AspNetCore.Components.WebAssembly.Authentication.AccessTokenNotAvailableException: ''

  at Microsoft.AspNetCore.Components.WebAssembly.Authentication.AuthorizationMessageHandler.SendAsync(

    System.Net.Http.HttpRequestMessage request, 

    System.Threading.CancellationToken cancellationToken)

この例外の原因は...

Visual Studio のプロジェクトテンプレートから「認証」オプションを有効にして作成された Blazor WebAssembly アプリのコードをよく読んでみた。

するとどうやら、HTTP リクエストの送信時は、ユーザがサインインしているかどうかに関わらず、また、リクエスト先の URL に関係なく、その HTTP リクエストに常にアクセストークンを添付するよう、起動時の初期化コードで構成されているようであった。

しかしユーザーがサインインしていないときは、アクセストークンを HTTP 要求に添付したくても、（まだサインインしていないので）アクセストークンを入手前なので添付できない。

以上が原因で AccessTokenNotAvailableException 例外が発生してしまったようだ。

解決方法

この問題を解決する方法は、自分が思いついた範囲だと3つほどある。

解決策 その 1

解決策その 1 は、AuthorizationMessageHanlder を設定して、指定されたサブパス以下のエンドポイントにのみアクセストークンを添付できるようにすることである。

この方法を選択するには、まず、サーバ側のエンドポイント (保護したいエンドポイント) の URL を、同じサブパス (例: "/authorized/...") の下になるように配置し直す必要がある。

[Authorize]

[ApiController]

// [Route("[controller]")]

[Route("authorized/[controller]")]

// 👆 このAPIのURLを "authorized "サブパスの下になるように変更。

public class WeatherForecastController : ControllerBase

{

...

次に、クライアント側で AuthorizationMessageHandler をカスタムオプションで設定する必要がある。

これはクライアント側プロジェクトの Program クラスの Main メソッドで行う。

public static async Task Main(string[] args)

{

  var builder = WebAssemblyHostBuilder.CreateDefault(args);

  builder.RootComponents.Add<App>("app");

  // 👇 この、AuthorizationMessageHandler を構成する

  //    コードを追加。

  builder.Services.AddTransient<AuthorizationMessageHandler>(sp =>

  {

    // 👇 作業に必要なサービスを DI から入手。

    var provider = sp.GetRequiredService<IAccessTokenProvider>();

    var naviManager = sp.GetRequiredService<NavigationManager>();

    // 👇 新しい「AuthorizationMessageHandler」インスタンスを作成、

    //    設定後にそれを返す。

    var handler = new AuthorizationMessageHandler(provider, naviManager);

    handler.ConfigureHandler(authorizedUrls: new[] {

      // 👇 ここに、HTTP 要求送信時には

      //    アクセストークンを添付したい URL を列記。

      naviManager.ToAbsoluteUri("authorized/").AbsoluteUri

    });

    return handler;

  });

  ...

最後に、HttpClientFactory に対し、こうして自分で設定したAuthorizationMessageHandler を使用するように設定する。

  ...

  // 👇 BaseAddressAuthorizationMessageHandler ではなく、

  //   上記で設定した AuthorizationMessageHandler を使用。

  builder.Services.AddHttpClient("BlazorWasmApp.ServerAPI", client => ...)

    // .AddHttpMessageHandler<BaseAddressAuthorizationMessageHandler>();

    .AddHttpMessageHandler<AuthorizationMessageHandler>();

  // Supply HttpClient instances that include access tokens when making requests to the server project

  builder.Services.AddTransient(sp => sp.GetRequiredService<IHttpClientFactory>()

    .CreateClient("BlazorWasmApp.ServerAPI"));

  ...

以上で、"/authorized/..." サブパス以下の URL に HTTP 要求を送信する場合にのみ、アクセストークンが添付されるようになる。

解決策 その 2

解決策その 2 は、認証が必要なエンドポイントに HTTP リクエストを送信する際に、「IHttpClientFactory」からアクセストークンを添付するように設定された,

名前付きの HTTP クライアントを明示的に取得する方法だ。

まず、クライアント側プロジェクトの Program クラスの Main メソッドで HttpClient を DI に登録する際、IHttpClientFactory サービスから HttpClient を取得するのではなく、ベースアドレスを設定しただけのプレーンな HttpClient を DI に登録するようにする。

  public static async Task Main(string[] args)

  {

    ...

    // 👇 DI には、プレーンな HttpClient サービスを登録。

    // builder.Services.AddTransient(sp => ...CreateClient("BlazorWasmApp.ServerAPI"));

    builder.Services.AddTransient(sp => new HttpClient { 

      BaseAddress = new Uri(builder.HostEnvironment.BaseAddress)

    });

    ...

そして、保護された API エンドポイントに HTTP 要求を送信する際には、DI から直接HttpClient を取得するのではなく、IHttpClientFactory から名前付きの HttpClient オブジェクトを明示的に指定して取得すればよい。

@* @inject HttpClient Http *@

@inject IHttpClientFactory HttpClientFactory

...

@code {

  protected override async Task OnInitializedAsync()

  {

    ...

    // 👇 保護された API にアクセスするためには、

    //    DI から直接 HttpClient を取得しない。

    // forecasts = await Http.GetFromJsonAsync<WeatherForecast[]>("WeatherForecast");

    // 👇 代わりに IHttpClientFactory サービスから

    //    明示的に名前を指定して HttpClient を取得して使用。

    var http = HttpClientFactory.CreateClient("BlazorWasmApp.ServerAPI");

    forecasts = await http.GetFromJsonAsync<WeatherForecast[]>("WeatherForecast");

}

解決策 その 3

解決策その 3 は、解決策 その 2 とは逆の解決方法である。

この解決策は、匿名アクセスを許可されたエンドポイントに HTTP リクエストを送信する際に、IHttpClientFactory からプレーンな HTTP クライアントを、名前を指定して明示的に取得する方法だ。

これを行うためには、クライアント側プロジェクトの Program クラスの Main メソッドにて、IHttpClientFactory サービスの構成処理に対し、プレーンな HttpClient を名前付きで登録しておく。

public static async Task Main(string[] args)

{

  ...

  // 👇 プレーンな HttpClient を、

  //    IHttpClientFactory サービスに名前を付けて追加する。

  builder.Services.AddHttpClient("BlazorWasmApp.AnonymousAPI", client => {

    client.BaseAddress = new Uri(builder.HostEnvironment.BaseAddress);

  });

  builder.Services.AddHttpClient("BlazorWasmApp.ServerAPI", ...)

      .AddHttpMessageHandler<BaseAddressAuthorizationMessageHandler>();

  ...

そうした上で、公開 API のエンドポイントに HTTP 要求を送信する際には、DI から HttpClient オブジェクトを直接取得するのではなく、IHttpClientFactory から名前を指定して明示的にプレーンな HttpClient オブジェクトを取得して使うとよい。

@* @inject HttpClient Http *@

@inject IHttpClientFactory HttpClientFactory

...

@code {

  protected override async Task OnInitializedAsync()

  {

    ...

    // 👇 公開 API にアクセスするためには、

    //    DI から直接 HttpClient を取得しない。

    // RecentlyUpdates = await Http.GetFromJsonAsync<string[]>("RecentlyUpdates");

    // 👇 代わりに IHttpClientFactory サービスから

    //    明示的に名前を指定して HttpClient を取得して使用。

    var http = HttpClientFactory.CreateClient("BlazorWasmApp.AnonymousAPI");

    RecentlyUpdates = await http.GetFromJsonAsync<string[]>("RecentlyUpdates");

}

まとめ

Visual Studio のプロジェクトテンプレートから "認証 "オプションを有効にして作成した Blazor WebAssembly アプリは、ユーザがサインインしているかどうかに関わらず、常にアクセストークンを HTTP 要求に添付しようとする。

この実装では、たとえ匿名のエンドポイントへのアクセスであっても、ユーザがサインインしていない場合は "AccessTokenNotAvailableException" 例外が発生してしまう。

この問題は、以下のいずれかの方法で回避することが可能だ。

• 解決策 1. - 指定されたサブパス以下の URL のみにアクセストークンを添付するように制限を設定する。
• 解決策 2. - 保護された API にアクセスする場合に、アクセストークンを添付するよう構成した HttpClient を明示的に名前を指定して取得して使用する。
• 解決策 3. - 匿名でアクセス可能な API にアクセスする場合に、プレーンな HttpClient を明示的に名前を指定して取得して使用する。

今回の問題の再現と、上記 3 つの解決策を収録したサンプルコードを、下記 GitHub リポジトリで公開してある。

以上

ASP.NET Core で静的ファイルを認証で保護する

"Microsoft Docs" サイトに記載のやり方は好きになれず...

C# 等による Web アプリ開発フレームワーク "ASP.NET Core" を用いた、サーバー側実装での話。

数週間ほど前から、新しい ASP.NET Core Web アプリ開発の案件が始まった。

この案件では、この Web アプリ上に配置される静的ファイルの一部を認証で保護、すなわち匿名アクセスは拒否する要件があった。

実のところ、ASP.NET Core 上に配置された静的ファイルを認証で保護する方法についてはわかっていなかった。

そこで、インターネット上で "protect static files, authorization, asp.net core" といったキーワードで検索するところから始めた。

相当数の検索結果がヒットしたが、その多くは "stackoverflow.com" に投稿された質問とその回答だ。

それらの回答は、以下のいずれかの解決策を提案しているケースが多かった。

• (A) 自分で ASP.NET Core ミドルウェアのカスタム実装を作り、静的ファイルミドルウェアより前の HTTP 処理パイプラインにそのミドルウェアを差し込み、認証されていない要求をそのミドルウェアで拒否する。
• (B) 保護したい静的ファイルを "wwwroot" フォルダの外部に配置し、代わりに、[Authorized] 属性付きの自作の ASP.NET Core MVC コントローラでその保護したい静的ファイルを応答で返すようにする。

特に上記解決策のうち (B) については、下記 URL の "Microsoft Docs" サイトでも公式に説明が掲載されている。

しかしながら、詳細はここでは割愛するが、今回案件特有の要件や背景事情をはじめ、いくつかの要因から、上記解決策 (A) (B) はちょっと採用したくなかった。

そこでもう暫し検索結果を読み進めた結果、幸いなことに、「これはよさそう!」と思われる解決案を stackoverflow.com 内で発見した。

その解決策とは、

「静的ファイルミドルウェアが提供している、"OnPrepareResponse" というコールバックポイントをフックする」

という方法だ。

ASP.NET Core 静的ファイルミドルウェアが提供しているフックポイント

静的ファイルミドルウェアを HTTP 処理パイプラインに登録するとき、すなわち Statrtup クラスの Configure メソッド内で UseStaticFiles() メソッドを呼び出すときだが、この際、StaticFileOptions 型のオプション指定をその引数に渡すことができる。

この　StaticFileOptions クラスに、静的ファイルを処理する直前に自前の処理を差し込みすることができる、あつらえたプロパティが用意されていたのだ。

そのプロパティの名前は OnPrepareResponse。

この OnPrepareResponse プロパティに自前の関数を設定すると、静的ファイルをブラウザに返す直前に、この設定した関数を呼び出してくれるのだ。

この自前の関数内で、要求が認証済みであるか否かに応じて、ブラウザへの応答を変更できる。

早速に、"stackoverflow.com" の下記回答にあるサンプルコードをコピーしてきて試してみた。

なお、もちろんのこと、認証ミドルウェアが静的ファイルミドルウェアよりも先に HTTP 処理パイプラインに登録されている必要がある。静的ファイルミドルウェアが要求を処理するより前に、認証済みであるか否かを判定済みにしておく必要があるからだ。

ということで自分のサンプルコードは下記のようになった。

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)

{

  ...

  app.UseAuthentication();

  app.UseStaticFiles(new StaticFileOptions

  {

    OnPrepareResponse = ctx =>

    {

      // 現在の要求が認証済みでないなら...

      if (!ctx.Context.User.Identity.IsAuthenticated)

      {

        // "HTTP 401 Unauthorized" を返す.

        ctx.Context.Response.StatusCode = (int)HttpStatusCode.Unauthorized;

      }

      ...

...なのに秘密のファイルが丸見え!

続けて先のサンプルコードをビルド、実行してみた、のだが...

期待に相反し、保護したはずの静的ファイルが、匿名アクセスでも見えてしまった!

たしかに自分が設定したコールバック関数は、認証されていない要求がきたら、 "401 Unauthorized" HTTP ステータスをブラウザに返せてはいるようだ。

しかしながら、静的ファイルミドルウェアがブラウザにコンテンツを返す処理に対し何の処置もしていなかったので、こんなことになったらしい。

応答全体を阻止する

HTTP ステータス 401 を返すことに加えて、静的ファイルミドルウェアによる応答本文をどうにかして破棄する必要がある。

これを実現するために、あともう2行、先のサンプルコードに追加した。

...

// "HTTP 401 Unauthorized" を返し...

ctx.Context.Response.StatusCode = (int)HttpStatusCode.Unauthorized;

// さらに下記の2行を追加して、応答ボディを破棄!

ctx.Context.Response.ContentLength = 0;

ctx.Context.Response.Body = Stream.Null;

..

この追加の2行で、静的ファイルミドルウェアによる応答ボディをすべて破棄することができる。

というのも、応答オブジェクトの Body ストリームを System.Null に差し替えているためだ。

System.Null への書き込みはすべて単純に破棄され、また、読み取りは空を返すので、静的ファイルミドルウェアは応答ボディに対して何の影響も及ぼさなくなる。

こうすることで、めでたく、秘密のファイルを保護することに成功した。

なお、さらなる考慮事項として、ブラウザキャッシュの挙動にも気を付けた方が良さそうだ。

というのも、自分が試した範囲だと、いちど認証を済ませて保護された静的ファイルを開いたことがある場合、その後サインアウトして未認証の状態でも、ブラウザキャッシュから当該静的ファイルを見ることができた場合があったからだ。

自分は "Cache-Control" 応答ヘッダに "no-store" を指定し、キャッシュに保存することを一切禁止とブラウザに知らせることで、この挙動を回避した。

ctx.Context.Response.Headers.Add("Cache-Control", "no-store");

リダイレクトさせたい場合

未認証の状態で保護された静的ファイルの URL が要求されたときに、HTTP 401 応答を返すのではなく、"サインイン" ページなどにリダイレクトさせることも可能だ。

コードは次のようになるだろう。

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)

{

  ...

  app.UseAuthentication();

  app.UseStaticFiles(new StaticFileOptions

  {

    OnPrepareResponse = ctx =>

    {

      if (!ctx.Context.User.Identity.IsAuthenticated)

      {

        // 任意の URL にリダイレクト可能.

        ctx.Context.Response.Redirect("/")

      }

      ...

まとめ

• 静的ファイルミドルウェアを HTTP 処理パイプラインに登録するとき (UseStaticFiles() 呼び出し) のオプション引数の OnPrepareResponse プロパティを活用することで、静的ファイルを認証で保護することができる。
• 但し、UseAuthentication() 呼び出しを、UseStaticFiles(...) 呼び出しよりは前に済ませておくこと。
• また、HTTP 401 応答を返して要求を拒否する場合は、加えて静的ファイルミドルウェアによる応答ボディ書き込みも阻止すること。
• 完璧に保護するためには、キャッシュ制御についても考慮が必要。
• もちろん、HTTP 401 応用を返すのではなく、特定の URL にリダイレクトさせることもできる。

サンプルコード全体は下記 URL の GitHub リポジトリで公開している。

実際に動作するライブデモサイトも下記 URL で稼働中だ。

https://protect-staticfiles-with-auth-on-aspnetcore.azurewebsites.net/

以上!

(エディタのXML自動整形でレイアウトが崩れてしまわないよう) プロジェクトファイル外に NuGet パッケージリリースノートを書く

プロジェクトファイルをエディタで編集するのは容易

昨今の C# プログラミングにおける話。
とくに Windows OS 上で Visual Studio を使っての開発場面を想定している。

最近では、XML 形式である C# プロジェクトファイル (.csproj) を、Visual Studio のプロジェクトのプロパティ表示 GUI 経由ではなく、テキストエディタで直接 XML を編集する機会が増えているように思う。

というのも、"SDK スタイル" と呼ばれる今風の形式のプロジェクトファイルであれば、その内容はきわめて簡素だからだ。

加えて既定の設定だと、Visual Studio のソリューションエクスプローラにてプロジェクトのノードをダブルクリックしたときに、そのプロジェクトが "SDK スタイル" であるならば、プロジェクトのプロパティ GUI ではなく、XML テキストエディタで開かれたりもする。

しかしリリースノートの編集は酷いことに...

さてところで、NuGet パッケージライブラリを開発しているような場合は、パッケージに記載されるリリースノートを記述することと思う。

パッケージのリリースノートを、Visual Studio のプロジェクトプロパティ GUI にて編集している間は何の問題もない。

しかしひとたび、Visual Studio のテキストエディタにて、プロジェクトファイルの XML を直接編集し始めると状況は一転する。

というのも、Visual Studio は親切にも、XML 形式であるプロジェクトファイルを保存するたびに、その書式を自動整形してくれるからだ。

そしてこの自動整形が、なんと、プロジェクトファイル内に記載された、改行を含むリリースノートのレイアウトをぶち壊してくれるのである!

ご覧のとおり自動整形が適用されることで、リリースノートに、無用な空白や改行が大量に追加されてしまうのだ。

もちろん、自動整形の機能を無効に設定すれば、このような悲劇は防ぐことが出来る。
とはいえ、今度は、自動整形なしでプロジェクトファイルの編集 (例えば、カスタムビルド処理を書く場合とか) が厄介なことになってしまう。

さてどうしたものか。

解決策

こんなことで悩んでいたある日、ようやく解決策を思いついた。

その方法は、リリースノートをプロジェクトファイル外に記述し、代わりにプロジェクトファイル内からその外部リリースノートファイルを取り込む、というものだ。

以下、その手順を記す。

Step 1. プロジェクトファイル外にリリースノートを記述

まず始めに、"RELEASE-NOTES.txt" といったファイル名のテキストファイルとして、パッケージリリースノートを記述する。

例えばこんな感じ。

v.1.0.1

- Support to Blazor v.3.2 Preview 3.

v.1.0.0

- Initial release.

"RELEASE-NOTES.txt" はどこに配置しても構わないが、以降の説明では、ソリューションがあるフォルダに配置したものとする。

Step 2. プロジェクトファイルからこれを取り込む

次の手筈として、数ステップの MSBuild スクリプトをプロジェクトファイル内に実装し、"RELEASE-NOTES.txt" ファイルの内容を取り込むようにする。

この目的で、MSBuild ターゲットをひとつ作成し (ターゲット名は既存のターゲットと衝突しなければ何でも良い)、"GenerateNuspec" ターゲットよりも前に実行されるようにする。

"GenerateNuspec" ターゲットが実行される直前は、パッケージリリースノートの準備をするのに最適なエントリポイントとなっている。

この MSBuild ターゲットでは、MSBuild に標準で備え付けの "ReadLinesFromFile" タスクを使って "RELEASE-NOTES.txt" ファイルの各行を読み出し、適当なアイテム名 (ここでは "ReleaseNoteLines" とした) の MSBuild アイテムに、読み込んだ各行を出力する。

そしてこれら読み込んだ結果の MSBuild アイテムを使って、"PackageReleaseNotes" MSBuild プロパティを上書き設定すればよい。

なお、既定では、MSBuild はアイテムの連結時、区切り文字をセミコロン (";") で連結する。

しかしここでは、リリースノートを改行区切りで連結する必要がある。

なので、下記のように区切り文字として LF (ラインフィード) を明示的に指定して、MSBuild アイテムの参照を記述する必要がある。

@(ReleaseNoteLines, '%0a')

("%0a" は、MSBuild スクリプトファイル内では "LF" コードを意味する。)

MSBuild ターゲットの全体像は下記のとおりとなる。

<Target Name="BuildPackageReleaseNotes" BeforeTargets="GenerateNuspec">

<ReadLinesFromFile File="../RELEASE-NOTES.txt" >

<Output TaskParameter="Lines" ItemName="ReleaseNoteLines"/>

</ReadLinesFromFile>

<PropertyGroup>

<PackageReleaseNotes>@(ReleaseNoteLines, '%0a')</PackageReleaseNotes>

</PropertyGroup>

</Target>

Step 3. 同僚や他の開発者に向けて、コメントを残す

最後に仕上げとして、もとのリリースノート記述場所に、「パッケージリリースノートは "RELEASE-NOTES.txt" に書いて下さい」というコメントを記載して完成だ。

おわり

こうしてようやく、プロジェクトファイルをバリバリと直接エディタで編集もしつつ、安心してパッケージリリースノートも記述できる環境を整えることができた。

MSBuild の WriteLinesToFile で、改行、あるいはセミコロンを含むテキストを、ファイルに書き出す方法

ビルドスクリプト "MSBuild"

C# プログラミングなどで使われるビルドスクリプト MSBuild のお話。

すなわち、C# プログラミングなどにおいて、"プロジェクトファイル" と呼ばれる、例えば拡張子 .csproj の、XML 書式のあのファイルが、実は MSBuild (エムエスビルド) スクリプトファイルである。

最近は .NET Core の進出により、プロジェクトファイル (MSBuild スクリプトファイル) の中身が、"SDK スタイル" と呼ばれる随分とすっきりした内容に進化している。  

また、Visual Studio を使って開発中の場合、この "SDK スタイル" のプロジェクトファイルを、Visual Studio のソリューションエクスプローラからのダブルクリックで、Visual Studio 内のエディタで中身が開かれる (※Visual Studio の設定によって動作は変更可能)。

このようなこともあり、最近はプロジェクトファイル (MSBuild スクリプトファイル) をエディタで直接編集して、ビルド時のカスタム処理などを MSBuild スクリプトとして書くことも多くなった。

MSBuild スクリプトでテキストファイルを書き出す

さてそんな MSBuild スクリプトであるが、つい先日、ビルド時のカスタム処理のひとつとして、とあるテキストファイルの生成を、MSBuild スクリプト内で実装したい要件が発生した。

このようなケースで使える MSBuild スクリプトの標準タスク (プログラミング言語で言うところの標準ライブラリ関数の MSBuild 版) として、WriteLinesToFile タスクがある。

上記公式ドキュメントにあるとおり、使い方は難しくない。

書き込み先のファイルのパスと、書き込む内容の文字列を、それぞれしかるべき属性に指定してやれば良い。

例えば以下のような XML ファイルを、例えば foo.msbuild とかいうファイル名で保存しておき、

<Project>

  <Target Name="test">

    <WriteLinesToFile 

      File="foo.txt" 

      Lines="Hello World" />

  </Target>

</Project>

.NET Core SDK がインストールされている環境 (Windows でも macOS でも各種 Linux ディストリでも OK) で、この foo.msbuild ファイルがあるディレクトリ上で以下のように dotnet コマンドを実行すれば、

dotnet msbuild test.msbuild -t:test

同ディレクトリ直下に、"foo.txt" というファイル名で、中に "Hello World" と書かれたテキストファイルが生成される。

なお、既に指定されたファイル名のファイルが存在している場合は、そのファイルに行追加されるのが既定の動作。

追記ではなく上書きとしたい場合は Overwrite 属性を書き足して true を指定してやればよい。

そうすることで、追記ではなく、上書きの動作となる。

また Overrite="true" を設定している場合に、これから書き込もうとしている内容と、既に存在する書き込み先ファイルの内容とが合致している場合は何もしない、すなわち、書き込み先ファイルの最終更新日時を変更しないようにすることもできる。  

そのためには WriteOnlyWhenDifferent 属性に true を設定してやるとよい。

改行を含むテキストファイルを生成するには?

さてそんな WriteLinesToFile 標準タスクであるが、さて、内容が単一行のテキストファイルではなく、複数行の内容のテキストファイルを書き出したい場合はどうすればよいだろうか?

まずひとつめのやり方だが、そもそもとして、MSBuild スクリプトは XML 書式で記述する。

なので、WriteLinesToFile 標準タスクの Lines 属性に指定する内容に、改行を意味する文字コードを XML の文法に従ってエンコードして指定 (実体参照) することで実現可能だ。

LF での改行を行なうなら、以下のように "&#xa;" を指定するとよい。 

<WriteLinesToFile 

  File="foo.txt" 

  Lines="line1&#xa;line2&#xa;line3"

  Overwrite="true"/>

そして、他にも MSBuild 特有の方法がある。

実は、MSBuild では、「複数の項目 (リスト)」を即値で記述するには、セミコロンで区切る、という文法となっている。

強引にざっくり例えると、JavaScript であれば  "[1, 2, 3]" というように「複数の項目」を表現するところを、これを MSBuild で示すと "1;2;3" という記法になる、ということだ。

そして、WriteLinesToFile 標準タスクにおける、書き出すテキスト本文を指定する属性の名前をよくよく見ると、"Lines" というように複数形になっている。

そう、実は WriteLinesToFile 標準タスクは、書き出すテキスト本文の指定に「複数の項目 (リスト)」を渡せる仕様なのだ。

ということで、改行を含むテキストファイルの生成は以下のように記述できる。

<WriteLinesToFile 

  File="foo.txt" 

  Lines="line1;line2;line3"

  Overwrite="true"/>

※こういった MSBuild の書き方は、下記書籍で勉強させていただきました。

...じゃぁセミコロンを書き出すにはどうすれば?

さてここで注意が必要となるのは、「改行がしたいんじゃなくて、セミコロンを含むテキストを書き出したい」場合だ。

実体参照方式で "&#x3b;" などとセミコロンの文字コードで指定しても、これは効果はない (改行になる)。

よく考えればわかることではあるが、実体参照方式で記述しようとしまいと、その XML を読み込んだ側、すなわち MSBuild エンジンの身にしてみれば、セミコロンはセミコロンである。  

つまり、元の XML 側での表現方法が違っても、パース (読み込み) した結果には違いがない訳だ。

このケースで必要なのは XML の書き方の知識ではなく、MSBuild における特殊文字のエスケープ表記方法の知識だ。

幸い、その方法は公式ドキュメントに明記されている。

上記にあるとおり、「% に続く、ASCII 文字コードを意味する16進数表記」という記法で、MSBUild 上における特殊文字、すなわち今回のケースではセミコロンを、表現可能だ。

セミコロンについては、具体的には `%3b` と記述すればよい。

ということで、下記のような C# ソースコードを生成することも可能である。

<WriteLinesToFile 

  File="foo.cs" 

  Lines="var foo = &quot;bar&quot;%3b"

  Overwrite="true"/>

おわり

以上。

XML の実体参照による特殊文字の記述と、MSBUild 固有の特殊文字をエスケープする記法とで、つい頭の中がこんがらがってしまうことがあったので、改めて本記事にまとめてみた次第。

MSBuild スクリプトで、ビルド時に同時に C# ソースファイルを自動生成しようとして、「行末のセミコロンが書き出されない!」と焦っていたのは内緒だ。

Twitter 認証を実装した ASP.NET Core 3.1 Web アプリで、Twitter 認証時にキャンセルをしたら、アプリがクラッシュした件

背景

ASP.NET Core 3.1 による、C# で実装した自作 Web アプリでの話。

昨今の Web アプリ用フレームワークの例に漏れず、ASP.NET Core においても、いわゆる "Twitter アカウントでサインイン" といった外部認証を実装することは容易である。

例えば Twitter での認証の仕組みを組み込みたい場合は、下記公式ドキュメントなどを参考に実装すればよい。

上記公式ドキュメントを参照することでわかるとおり、他にも、Google アカウントや Microsoft アカウント、Facebook アカウントなどなど、様々な外部アカウントを使った認証が容易に組み込み可能だ。

実装例

実際、自分が開発しているとある Web アプリ (ソースコードは下記) でも、Twitter による認証を実装している。

実装についてポイントだけかいつまむと、まずは自作の Web アプリのソースコード中、DI 機構へのサービス登録を行なっている、Startup クラスの ConfigureServices() メソッド内にて、標準的な Cookie ベースの認証用のサービスに加えて、Twitter 認証のためのサービスを "AddTwitter()" 拡張メソッドで登録してやる。

このタイミングで、Twitter 側で作業を済ませておいた、コンシューマー API キーとシークレットを、Twitter 認証構成オプションに設定するよう実装しておく。

// Startup.cs

...

public void ConfigureServices(IServiceCollection services)

{

  ...

  services.AddAuthentication(...)

    .AddCookie(...)

    // Twitter アカウントでのサインイン機構を組み込み

    .AddTwitter(options =>

    {

      options.ConsumerKey = ...;

      options.ConsumerSecret = ...;

    });

    ...

続けて、HTTP 要求を処理するパイプライン中に、認証の処理を挿入するため、同じく Startup クラス内の Configure() メソッド内にて、"UseAuthentication()" 拡張メソッドをしかるべき順序で呼び出し・ミドルウェアの挿入を行なっておく。

// Startup.cs

public void Configure(IApplicationBuilder app, ...)

{

  ...

  app.UseAuthentication();

  ...

最後に、Twitter アカウントでの認証を開始するための MVC アクションや API エンドポイントを実装し、これを呼び出してやれば良い。

// 何かコントローラなど

...

[HttpGet("/auth/signin")]

public IActionResult SignIn()

{

  // 認証スキーマとして Twitter による外部認証を指定している

  return Challenge(TwitterDefaults.AuthenticationScheme);

}

詳細はかなり端折っているが、概ね上記のような実装にて、この Web アプリの ~/auth/sigin へ遷移すると、Twitter の認証画面が開き、Twitter アカウントによる認証ができるようになる。

実装の "手抜き" が発覚!

さて、そんな自作 Web アプリにおいて、ちょっと手抜きしていた点が発覚してしまった。

自作 Web アプリから認証を開始し、Twitter 側のページに遷移したあと、この Twitter の認証画面で「キャンセル」された場合を考慮していなかったのだ。

で、実際に Twitter の認証画面でのキャンセルを試してみたところ、あえなく、この自作 Web アプリは HTTP 500 Internal Server Error を吐いてしまった。

ローカル開発環境にて確認してみると、下記のような例外が発生していた。

System.Exception:

  An error was encountered while handling the remote login.

System.Exception:

  Access was denied by the resource owner or by the remote server.

 at Microsoft.AspNetCore.Authentication.RemoteAuthenticationHandler`1.HandleRequestAsync()

解決方法

では、外部認証先でのキャンセルの操作に対応するにはどうしたらよいのか?

某氏に教えてもらったところ、下記 Stackoverflow のスレッドに答えがあった。

すなわち、Twitter 認証のためのサービスを DI 機構に登録する際、そのオプション構成指定時に「Twitter による認証が失敗した」ときに呼び出されるコールバック関数を指定することができる。

具体的には、オプション引数の Events > OnRemoteFailure プロパティがそのコールバック関数となる。

というか、コールバック関数を指定してアプリケーション開発者が外部認証失敗時の処理を明示しないと、前述の例外発生となってしまうようだ。

さて、OnRemoteFailure で指定するコールバック関数、その引数には RemoteFailureContext オブジェクトが渡される。

このコンテキストオブジェクトには、Exception 型の Failure プロパティが公開されている。

これを参照することで、同じ「認証失敗」であっても、キャンセルなのかもっと他の要因で失敗したのか、処理の場合分けができそうだ (※自分は未確認)。

また、このコールバック関数の引数 = RemoteFailureContext オブジェクトには Response プロパティが提供されている。

この Repsonse オブジェクトを使うことで、外部認証失敗時における、お好みの HTTP 応答を返すことができる。

自分のアプリの場合は、何があろうと雑に、しれっとアプリのトップページに戻すこととした。

具体的には下記のとおり実装してみた。

...

.AddTwitter(options =>

{

  ...

  options.Events.OnRemoteFailure = context =>

  {

    var appUrl = $"{context.Request.Scheme}://{context.Request.Host}/";

    context.Response.Redirect(appUrl);

    context.HandleResponse();

    return Task.CompletedTask;

  };

})

...

まとめ

以上で Twitter の認証画面でキャンセルされた場合でも、HTTP 500 ページになることなく、それなりの動作 (今回の例では単にアプリケーションのトップページに戻るだけ) に収めることができた。

自分は Twitter アカウントによるサインインでしか確認していないが、おそらくは他の外部認証の場合でも、この Events.OnRemoteFailure による外部認証失敗時のハンドリングの仕組みは同じことだろう。

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 文をログ出力する方法であった。