ConsoleAppFramework - .NET Coreコンソールアプリ作成のためのマイクロフレームワーク(旧MicroBatchFramework)

以前にMicroBatchFramework - クラウドネイティブ時代のC#バッチフレームワークという名前でリリースしていたライブラリですが、リブランディング、ということかでConsoleAppFrameworkに変更しました。それに伴い名前変更による多数の破壊的変更と、全体の挙動の調整を行っています。

当初の想定ではバッチ、特に機能紹介にあるMulti Batchをメイン機能と捉えて作っていたのですが、最終的には汎用的なコンソールアプリケーション用のフレームワークとして出来上がっていたので、より適正な名前にすることで、多くの人に正しく捉えてもらって、届けられるのではないかと思い、今回の変更に至りました。

といったように、 Microsoft.Extensions の仕組みに乗ってLogging, Configuration, DIなどをカバーしつつ、CLI用にパラメーターバインディング、メソッドルーティング、ライフサイクル管理を乗っけているのがConsoleAppFrameworkの意義となります。一度使ってもらえば、もう素のConsoleAppを作ることはなくなります、というぐらいには便利なのではないかと……!

同様のコンセプトとしては、PHPではLaravel Zeroという、Micro-framework for console applicationsがあります。Laravelのロギングやコンフィグレーションを共有しつつも、コマンドラインアプリケーションで使いやすいような処理が施されています。Microsoftによる実装ではdotnet/command-line-apiの System.CommandLine.Hosting + System.CommandLine.DragonFruit が近い機能を持っていますが、ConsoleAppFrameworkのほうがよりプロダクティビティが高いです。というかMSのはダメです。こういうの作るのにMicrosoftはセンスないんですよねー。

あらためてConsoleAppFrameworkの単純な例ですが

using ConsoleAppFramework;
using Microsoft.Extensions.Hosting;
using System;
using System.Threading.Tasks;
 
// Entrypoint, create from the .NET Core Console App.
class Program : ConsoleAppBase // inherit ConsoleAppBase
{
    static async Task Main(string[] args)
    {
        // target T as ConsoleAppBase.
        await Host.CreateDefaultBuilder().RunConsoleAppFrameworkAsync<Program>(args);
    }
 
    // allows void/Task return type, parameter is automatically binded from string[] args.
    public void Run(string name, int repeat = 3)
    {
        for (int i = 0; i < repeat; i++)
        {
            Console.WriteLine($"Hello My ConsoleApp from {name}");
        }
    }
}
 
> SampleApp.exe -name "foo" -repeat 5.

といったように、Mainに毛が生えた程度の記述だけで、気の利いたコマンドラインアプリケーションが作れます。今回からヘルプのフォーマットに気合いを入れているので、

public void Run(
    [Option("n", "name of send user.")]string name, 
    [Option("r", "repeat count.")]int repeat = 3)
{
    // ...
}

といったようにいい感じのショートカットと説明を属性で追加してあげると、

> SampleApp.exe help
Usage: SampleApp [options...]
 
Options:
  -n, -name <String>     name of send user. (Required)
  -r, -repeat <Int32>    repeat count. (Default: 3)

いい感じのhelpが表示されるようになりました。ちなみにこれは dotnet コマンドのフォーマットに近いものです。

.NET Core 3.0からはランタイム不要での単一ファイルのバイナリ作成がやっとできるようになったので、配布もよりやりやすくなりました。また、パッケージマネージャー経由での .NET Core Global Toolsという仕組み(.NET Core 2.1から)や、プロジェクト単位で設定してバージョン固定などがやりやすい.NET Core Local Tools(.NET Core 3.0から)といった仕組みも整備されているので、かなりいけてます。

また、ConsoleAppFrameworkの持つ複数のバッチ(コマンド/メソッド)を単一アプリケーションで管理する実行可能にする機能は、プロジェクト固有のバッチ(大量にあるはず!)やインフラ管理スクリプトなどを一本化して、CIなどではgit pull後に dotnet run command で済ませられたりするなどは、実際私自身も有用に使っています。

リブランディングについて

MicroBatchFramework、正直なところもう少しウケてもいいと思ってたんですが、あんま伸びなかったんですよねー。コンセプトは良いはずだし実際機能的にもいいのになんでー?と思ったんですが、ようは”Cloud Native Batch Framework” というのが全然ピンときてないんですよねー。Cloud Nativeとか言っておけば喰い付くだろうとかいう安易なネーミングがダメ。あとBatchってのがやっぱダメだよね。バッチ。バッチって。

というわけで、ずっと気になってたんで、結果、今回の名前変えたのは本質をより表していていいんじゃないかなー、と思いますがどうでしょう?ReadMeも全体的に見直して、ウケる雰囲気になったと思うので、これでもう一発逆転狙いたいです(?)

それと、こういう名前変えるみたいなのも決断の一種なわけですが、名前を変えること自体は誰でもできるし、変えた名前も安易で誰でも決めれるわけですし、実際に変えてみるとピタッとピースがはまったように見える。けれど、じゃあいざ変えましょう、と踏み出すのはとてもむずかしい。というわけで、あ、シャッチョさん仕事したな、みたいな気になりました。まる。

2019年を振り返る

今年はどういう年だったかというと、うーん、まともに会社として動き出した年、ですかね。去年Cysharpという会社を作りましたが、その時点では一人だったので会社感も全く何もなかったのですが、今年から何人か入ってきたので、やっと会社として体をなしてきました。

ブログの本数があからさまに減ってますが、Cygames Engineers’ Blogに書いている分もあるのでそこはしょーがない。今年は講演も結構した気がします。CEDECやUniteなど大きなイベントでも話してきましたし、特にUniteのUnderstanding C# Struct All Thingsは好評だったようで、アンケート結果でも実質一位(正しくは4位、1~3位はUnity Technologies Japanの人だったので、それを除いたらという謎基準により)だったので、嬉しみがあります。

ライブラリは、なんか一年中ずっとMessagePack for C# v2に関わってた気がするのですが、なんとか駆け込みでリリースできてよかった。それに合わせてMagicOnionMasterMemoryといった内部でMessagePackを使っているライブラリのアップデートも間に合い、今年を気持ちよく終えることができそうです。

Cysharpとしてはパブリックなリポジトリ(github/Cysharp)が10個。設立から一年ちょいの会社のポートフォリオとしては、かなり立派なんじゃないでしょうか!会社の社是「C#の可能性を切り開いていく」のとおりに、C#にないものを絶妙な感じに埋めまくっています。

私はC#にとてもこだわっているわけですが、実際のところ、言語の選択がアプリケーションの開発の成功に必須かといったら、別にそうではないとも思っているのです、実のところ。ほとんどのことは、別に何の言語だろうと達成できるだろう、とも。(実際、私はCTOとして在籍していた前の会社、グラニの立ち上げタイトルである「神獄のヴァルハラゲート」をPHPでの開発に同意して、暫くPHP書いていたりもしましたしね←ただし成功したらすぐにC#リプレイスプロジェクトを始動して、半年後に完全移行しましたが)。

それでも、人は何かを選択しなきゃあいけないわけで、そのときにC#を選んでほしいし、選ぶ理由を作っていくことを大事にしています。前提としての他の言語にあってC#にはないものをなくしていき、差別化としてC#にしかないものを用意(超ハイパフォーマンスなライブラリであったり、C#大統一理論なんかがそうです)する。そうすれば自然と選択肢に上がってくるし、その結果、選ばれることが増えていく。実績だって数多くできていく。そういった環境を作っていくために、気を吐いているわけです。

それって会社の経営者としてどうなの!?というと、そうした活動が回り回って自分たちにうまくいくようにうまくしている(いく)ので、まぁまぁうまくいってるんじゃないでしょうか。

私はいっぱいOSSを公開しているのですが、そもそもに私はライブラリを作ることをアートだと捉えているんですよね。比喩でなく文字通りの。強く伝えたいメッセージ、表現したい衝動があり、それは時に、哲学的であり、政治的であり、ポジショントークでもある。私にとってはOSSの形で公開することこそが最も強く表現できる手段で、ライブラリは思想の塊であり、言葉だけよりもずっと流暢に語ってくれると考えています。

なので、つまんない量産型アーキテクチャの話とか聞くと、もっと個性が立っていてもいいのに!いったい何がしたいの?(いや、普通に動くアーキテクチャが一番大事ですが)、とか思ったりはよくします。あと、外資系企業とかシアトルやシリコンバレー勤務とかの話もつまんないですね、彼らが誇っているのって結局は場所が違うだけで自分自身はフツーのことをしてるだけじゃない?魂がないよね!それで他人を腐してるのだから実にダサい。(いやまぁそれは言い過ぎで、どんな仕事にも情熱はこもっているものです!だいじょうぶだいじょうぶ!)

とはいえアートじゃ生きていけない!実際OSSでは喰っていけない!中世ならパトロンが必要なところですが、現代においても食客のような立ち回りが必要です。つまり……。いやまぁ、食客かどうかはともかくとしてともかくとして、私は役に立つべき局面(たまにある、しょっちゅうはない)では驚くべきほど役に立ちます!し、実際、食客じゃないのでちゃんと仕事してますし(してます!)、今仕込んでいるものはきっと来年にはお見せできる(したい)と思うのですが、非常にインパクトのある成果になっていることと思います。Win-Winじゃないですかー。そうありたいね。

というわけで、生きていく間で大事にしたいのは、これからもそうした表現したい衝動を持ち続けられること、です。そのためにも、どこから降ってくるか分からない衝動のために、色々な刺激を受け、脳みそで咀嚼して考えていきたいなあ、と。

C#

今年も色々作ったのですが、MicroBatchFrameworkが地味に大きかったかなあ。めっちゃくちゃ使ってます。作って良かった。もっと評判になればいいのに、ぐぬぬ……。

技術的にはMessagePack for C# v2がめちゃくちゃ大きくて、また一つC#が新しいレベルに到達してしまった……。みたいな感慨があります。v2のお陰で、MagicOnionはどうあるべきなのか、といった道筋がスッと通っていったのが実際感動的です。というわけで、来年はフレームワーク全体を通しての新世代のアーキテクチャの掲示、というのを行えるんじゃないかと思っています。

MasterMemoryも良かったのではないかと、SQLiteの4700倍!なのも当たり前で、これがあると取るべきアーキテクチャの幅が広がるはずです。サーバーサイドでもクライアントサイドでも、活用しがいのあるライブラリになっています。

反省点はUnity側の深堀りがほとんど出来なかったことですね。毎年言い続けているECSやる、とか、去年も言っていたECS+物理エンジンでちゃりんちゃりん、みたいなのも今年も何も実装せずに終わった、とか、いやはやー。来年こそECSイヤーにするぞい!

諸事情で、プログラミングに集中して割ける時間というのがどんどん減っていってはいるのですが(GitHubの草も壊滅的で)、それでも要所要所での爆発力みたいなので成果は出せているし、今年も純粋な能力的成長は果たせたと思っています。今のところの脳みその調子的にはかなり良いので、来年もいい成果を出していけそうです。

漫画/音楽/ゲーム/その他…

GDC 2019に行ってきたのですが、そのアウォードで表彰されてたゲームが、さすがの普通にとても良かった。特にCelesteは本当によく出来ていて暫く遊び続けていました。それとFlorence、これは(リリースは2018年ですが私が今年プレイした中で)Bestで、感情を動かすためのUI/UXの究極系みたいな感じで、がっつりショック受けました。とにかくヤバい。制作秘話がまさにGDCで発表されていました。[GDC 2019]鮮やかな人間ドラマを描く新感覚ゲーム「Florence」は,どのように作られたのか。22か月間の苦闘をデザイナーが振り返る

音楽は念願の相対性理論の野外ライブに行ってきた!Liveアルバム調べる相対性理論を日比谷野音で全曲実演したのですが、信じられないほど良かった!メンバーチェンジ後の相対性理論はビミョンに思ってたのですが、前のメンバーじゃこのライブには絶対ならなかっただろうし、この到達点のための……!みたいに思ってもう全てが受け入れられた。そんなわけで今年はずっとこのアルバム聴いてましたね。Live映像も出してほしい……。

あとは、魂がふるえる展でふるえて来ました。いやあ、よかったね。実際この展示は最終的に今年の美術展の入場者数でもトップクラスだったそうで、映え、もそうですけれど実物から漂う死生観には圧倒されました。

ベストガジェットはAirPods Proということで。SonyのWF-1000XM3も買っちゃってはいたんですが、どうにも使いづらくてAirPodsをずっと使い続けてたんですが、AirPods Proが出た瞬間に、完全に全て乗り換えました。恐ろしい完成度のデバイスだし、様々な面で既存の延長線上「ではない」革命的な要素が散りばめられていて、モノを作るならこういうのを作りたいよね(喩えで、別にハードウェアを作りたいとかそういうことを言ってるわけではない)、と思わせる一品でした。

来年は

MagicOnion v4と、そのためのパーツ作りが年始に入っています。これは間違いなくC#にとってのキーパーツになるので、ちゃんと仕上げたいですねえ。仕事のほうでも今仕込んでいるものが公開されていく年だと思うので、きっちりやっていけば相乗効果でC#元年(とは)ですよ!にできるんじゃないかと思ってます。そしてUnity度合いが結構下がっちゃってるので、そこも補填していければパーフェクトな姿に……!

といったのを目指してどしどしやっていきます。来年は爆発の年、ということで。

MessagePack for C# v2によるC#における最新のI/Oパイプライン最適化

MessagePack for C#のVersion 2を本日リリースしました。出る出る詐欺で、一年がかりでリリースまで漕ぎ着けました!とにかくめっちゃ時間かかった、死ぬほど私のリソースが取られていた、ので本当にリリースまで持ってこれてよかった……。めでたし。

今回はとてもOSSっぽく開発していて、メインの開発はMicrosoftのVisual StudioチームのPrincipal Software EngineerであるAndrew Arnottさんが書いています。私はそれに対してひたすら、APIデザインが好きじゃないだの、パフォーマンスが私の基準に満たしてないだの、文句つけまくる仕事をしていました。しかしコードのクオリティはさすがに非常に高くて、私だけだったらここには至れなかっただろうことを考えると、いい感じの共同開発ができたんじゃないかなあと思います。その結果として、一年前に掲示されたv2よりも、百億倍良くなってます。この一年間で磨きに磨き抜いたわけです。

最初のリリースから2年半が経ち、MessagePack for C#は今では ASP.NET のリポジトリに含まれていたり、Visual Studio内部で使われていたりと、もはや準標準バイナリシリアライザの地位を得ていたりします。さすがにここまで成長するとは想像してなかった。.NETに貢献し過ぎで偉い。Version 1はシリアライザのパフォーマンスの基準を大きく塗り替えて、新しい世代の水準を作り出したという偉業があったわけですが、今回のv2も大きな成果を出せると思っています。v2はI/Oパイプライン全体の最適化を見据えて、パイプラインの心臓部として正しく機能するためにはどうあるべきか、というのを指し示しました。今後のC#のアプリケーションのアーキテクチャは、ここで指し示した道に進んでいくことでしょう。

v1 -> v2においては破壊的変更多数なので、移行ガイドをmigration.mdにまとめてあるので、適当に読んでおくと良いでしょう、詳しい解説は特にしません。ライブラリ類は一斉にバージョン上げないと詰みます。Cysharpで作っているMagicOnionMasterMemoryは作業中なので、来週にはドバッと上げておきます多分予定。

パイプラインによるゼロコピー

MessagePack for C#の内部構造について、見るべきメソッドシグネチャは以下の2つです。

public static void Serialize<T>(IBufferWriter<byte> writer, T value, MessagePackSerializerOptions options = null, CancellationToken cancellationToken = default)
public static T Deserialize<T>(in ReadOnlySequence<byte> byteSequence, MessagePackSerializerOptions options = null, CancellationToken cancellationToken = default)

シリアライズにおいては IBufferWriter<byte>, デシリアライズにおいては ReadOnlySequence<byte> を入出力口に使うというのがポイントです。 どちらもSystem.Buffersに定義されている .NET Standard 2.1 世代のインターフェイスです。反面、v1ではともに byte[] ベースでした。

I/Oのパイプラインってなんぞや、というと、ようするに入出力へのbyte[]をどう扱うかということであり、C#的には入り口も出口も最終的にはネイティブがやり取りするので、その手前のもの(SocketAsyncEventArgs, ConslePal+Stream, FileStream, etc…)、を呼び出して処理するフレームワーク、が呼び出すシリアライザ。といった流れになっています。シリアライザは常に中心(Object -> byte[]変換)にいます。上の画像は一般的なやり取りの場合(あるいはv1の場合)で、RedisValue(StackExchange.Redis)がbyte[]を、ByteArrayContent(HttpClient)がbyte[]を、といったように、割と素のbyte[]を求められる局面は多い。その場合、シリアライザはnew byte[]した結果を返すことになり、それはフレームワークの処理を得て、入出力の源流へ再度コピーされ(されないこともある)ます。

ここにおける無駄は、byte[]のアロケーションと、コピーです。

と、いうわけで、byte[]のアロケーションを避けるパターンとして、シリアライザは作業領域として外部のバッファープール( System.Buffers で定義されたArrayPool<byte>は .NET Core 3.0ではクラスライブラリ内でも多用されています)を使用し、フレームワークから提供されるStreamに書き込むことで、必要なコストをコピーだけにする手法があります。v1でも一部実装していました。なお、Streamに対して直接Writeすることで自前バッファを使わないという手も理論上可能ですが、Writeによるオーバーヘッドが多いため性能が悪化します。また、どちらにせよStream内部でバッファを持っている場合もあります。さらに、非同期にも対応できませんし、では全てをWriteAsyncで処理すれば、更にオーバーヘッドが多くて全く性能がでません。つまり、性能の良いアプリケーションを作るには、バッファをどう扱うが大事です。v1の設計思想として、シリアライズの一単位をバッファとして取り扱えば良い、だから全てをbyte[]ベースで処理し、Streamへは一気に書き込めば良い。という指針がありました。そして、それは実際正しく機能して、当時存在したあらゆるシリアライザを引き離す性能を叩き出しました。

IBufferWriter<byte>を活用すると、作業に必要なバッファを元ソースに対して直接要求することができます。それによりバッファ管理を完全に元ソースに任せることができるため、シリアライザ内部の作業バッファからのコピーコストが消滅します。例えばソケット通信で使われるSocketAsyncEventArgsは通常使いまわされますが、それの持つ(byte[] Buffer)に直接書き込む、といったようなことが可能です。

Streamに対してはSystem.IO.Pipleinesの提供するPipeWriterIBufferWriter<byte>を実装し、最適なバッファ管理を代替してくれます。

ASP.NET Core 3.0からは従来の(Stream HttpResponse.Body)だけでなく、(PipeWriter HttpResponse.BodyWriter)も提供されるようになりました。MessagePack.AspNetCoreMvcFormatterは、.NETCoreApp 3.0の場合にはBodyWriterに対してシリアライズする実装を用意しています。

現在の.NETのフレームワークは、Streamを要求するものか、あるいはbyte[]を要求するものがほとんどです。しかし、フレームワークレベルでのIBufferWriter対応が進んでいけば、よりMessagePack for C# v2の真価が発揮されていくことでしょう。もちろん、byte[]を返すAPI(byte[] Serialize<T>(T value))でも、最適なバッファ管理によってアロケーションやコピーコストを抑えるようになっています。

理論とパフォーマンス

多くある誤解として、async/awaitにしたら速くなるわけでもないし、Span<byte>にしたから速くなるわけでもありません。そして、IBufferWriter<byte>ReadOnlySequence<byte>にしても速くなるわけではありません。理屈上コピーが減ったとしても、遅くなりえます。素朴に実装すればコピーしたほうが10倍速い、といった状況はありえます。

例えば [10, 100, 100] をシリアライズしたいと思ったとして、intが最大5バイト必要だとして、都度writter.GetSpanで取得した場合と、byte[]でどばっと取得した場合を比較すると……

// IBufferWriter<byte>
foreach(var v in values)
{
    var buffer = writer.GetSpan(5);
    var length = WriteInt(buffer, v); // WriteInt returns write length
    writer.Advance(length); 
}
 
// byte[]
var buffer = ArrayPool<byte>.Shared.Rent(64K).AsSpan();
var offset = 0;
foreach(var v in values)
{
    var length = WriteInt(buffer.Slice(index), v);
    offset += length;
}
// Return buffer...

というようなコードを書いた場合、どう見てもbyte[]ベースで素朴にやったほうが速そうです、というか速いです。ReadOnlySequence<byte>もそうで、内部は複雑な型のため、そのまま使ってSliceなどを多用すると、かなり遅くなります。よって、IBufferWriter<byte>によって得られたバッファを適切に管理する中間層、ReadOnlySequence<byte>によって得られたSegmentのバッファを適切に管理する中間層、の作り込みが必要になってきます。

v2の開発にあたっては、byte[]ベースで極限まで性能を高めたv1があるので、どれだけv1と比較して遅くなっていないか、を基準に随時ベンチマークを取ることによって、中間層の存在による性能低下を検知し、極力性能低下を抑えることに成功しました。

逆に言えば、純粋なシリアライザとしての性能はv1のほうが高速(な場合も多い/バッファ管理が賢くなったのでシリアライズ対象が大きい場合はv2が有利な場合もある)なのですが、パイプラインに組み込めることと、様々な工夫により、トータルでみるとv2のほうが実アプリケーションとしては有利になっています。

配列上のLZ4圧縮

v1 -> v2による性能向上の一つに、v1では64K以上のシリアライズではプールを使わず新規アロケーションをしていましたが、v2ではArrayPoolから取得する32Kのチャンクの連結リストを内部バッファとして使用しています(外部からIBufferWriterを渡さず、v2内部のバッファプールを使用する場合)。

image

byte[]を作る場合は、最後に連結して一塊に。Streamに書き込む場合は32K毎にWriteAsyncします。これによりバッファが溢れた場合に、List<T>のように二倍のサイズのバッファを新規に確保して書き込み、などせずに済んでいます。また、常に使用するバッファの大きさが85K以下で済むため、悪名高いLarge Object Heap(LOH)を消費する(ここに溜まるとGCの性能が極度に低下する)ことも避けられています。

そしてv2から新規搭載された新しい圧縮モードである MessagePackCompression.Lz4BlockArray では、この内部形式を利用して32K単位でLZ4圧縮をかけることにより、圧縮するために、一度、全部が一塊になった大きな配列を確保することを避けています。

image

実装上の工夫としては、MessagePackの拡張領域であるExtを使用することによって圧縮種別を判定可能にしていることと、Extは長さが必要なため、LZ4で圧縮されてサイズが縮むことを考えると事前に長さを計算することができない!ことを避けるために、Arrayを使用した上で、Arrayの最初の要素をExtにして判定用+LZ4のデシリアライズに必要な圧縮前の長さをここの部分に格納しています。これ、シリアライズもそうですが、デシリアライズ時もブロック単位で伸張できるので、大きなデータでも巨大配列を確保しないで済むという利点があります。

v1までの圧縮モードはMessagePackCompression.Lz4Blockとして残していますが、v2ではMessagePackCompression.Lz4BlockArrayを使用することをお薦めしています。既に圧縮済みのバイナリデータに関しては、Lz4BlockArrayでもLz4Blockをデシリアライズすることが可能です(逆も同様)。

ちなみにこの32Kというサイズを選んだのには、ちゃんと意味があります!まず、ArrayPoolの仕様で16K, 32K, 64K, 128Kの大きさで確保されます。20Kを要求した場合は32Kが、65Kを要求した場合は128Kが得られるという図式です。

そしてLZ4圧縮した場合、全く圧縮できなかった場合、ワーストケースでは要求サイズよりもほんの少し「大きく」なります。さて、そこでチャンクのサイズが64Kギリギリまで使用していて、LZ4圧縮をかけようとした場合は、圧縮後のサイズは圧縮完了まで不明のため、事前にワーストケースを想定し64.1K(仮)を要求し、結果として128Kが得られます。つまり、LOH行きです。厳密にはArrayPoolを使用しているため使い回されるので大丈夫ですが、プールサイズには上限を設けているので(全体で共有で32K * 100)、使い切った場合はアロケートされるので、そういうケースでもLOH行きを避けるためのサイズになっています。

真のコードジェネレーター

悪名高いド不安定なコードジェネレーターは大きく改善され、真の安定性と、ディレクトリ単位での指定と、ファイル単位での出力と、CIで使いやすい .NET Core (Local/Global) Toolsでのインストールと、XamarinやUWPで便利なMSBuild Taskの提供と、Unityでは初心者フレンドリーなEditor拡張を追加しました。

とにかくMac/Linuxでも安定して動作する!というのが大きい!やっと大手を振って人にお薦めできるようになりました。

まとめ

と、解説しましたが、実装の8割以上は前述のAArnottさんが行ったものなので、まずは本当にありがとうございます。そもそもv2のキッカケはプロトタイプ実装を掲示されて、Forkしていくパターンか一緒に実装するかのどちらかと言われて、(何ヶ月も返事を放置した末に)、一緒にやっていきましょうとしたのが元でした。その後も、一ヶ月質問を放置するとかメールスルーとか、そもそも開発の遅れは私のコミュニケーションによるものでは……、というようなところを粘り強く乗り越えてもらったお陰です。

いや、そうはいっても私もかなりしっかりやってますよ!?特にAPIのデザインは紆余曲折あってもめにもめた末に一周回って私が最初に掲示したデザインになってるし、性能面では延々と私が地道にベンチマーク取って掲示することで腰を上げてもらったり(その時点で大体どこをどう変えればいいのかは分かってるので、指摘しながら)、Unity周りはそもそも興味ないみたいなので油断するとすぐ壊れるところを直していったりと、はい。

これでパイプラインにおける心臓部分を手に入れることが出来たのですが、改めてまだそもそもパイプラインに血が流れてません。ASP.NET Coreだけでなく他のフレームワークやライブラリ郡(特にRedisと、ADO.NETはいい加減に10年前のレガシーモデルから卒業して新しい抽象層を提供して欲しい)も対応していかなければならないし、私の場合はMagicOnionが、トランスポート層に採用しているGoogleのgRPCがイマイチなせいでめちゃくちゃイマイチです。

というわけで、次回はMagicOnionのパイプライン化を最適化するために、通信層から手を入れる予定です。また、シリアライザはMessagePackだけではなく、JSONも重要なので、改めてUtf8Jsonの改修も行いたいと思っています。.NET Core 3で華々しくデビューしたMicrosoft公式実装のSystem.Text.JsonによるJsonSerializerの性能が極めて悪いので……。残念ながらMicrosoftは柔軟かつ性能の出るシリアライザの作り方を全く分かっていないのでしょう。

また、このパイプラインはサーバーの入口→出口だけで閉じるものではなく、ネットワークを超えてクライアント側(Unity)にまで届くものだと考えています。サーバー/クライアントを大きなパイプラインに見立てて、見えるところ通るところ全てを最適化することが「C#大統一理論」であり、真に強力なのだ。ということを実証していくのが当座の目標で、やっと最初の一歩が踏めました。C#凄いな、と心の底から世界中の人が思ってもらうためにも(そしてあわよくば採用してもらう!)、まだ足りてないものは山のようにあるので、どんどん潰していきましょう。

.NET Core時代のT4によるC#のテキストテンプレート術

C# Advent Calendar 2019用の記事となります。C# Advent Calendar 2019はその2もあって、そちらも埋まってるので大変めでたい。

さて、今回のテーマはT4で、この場合にやりたいのはソースコードジェネレートです。つまるところC#でC#を作る、ということをやりたい!そのためのツールがテンプレートエンジンです。.NETにおいてメジャーなテンプレートエンジンといえばRazorなわけですが、アレはASP.NET MVCのHTML用のViewのためのテンプレートエンジンなため、文法が全くソースコード生成に向いていません、完全にHTML特化なのです。また、利用のためのパイプラインもソースコード生成に全く向いていない(無理やりなんとか使おうとするRazorEngineといったプロジェクトもありますが……)ので、やめておいたほうが無難です。

では何を使えばいいのか、の答えがT4(Text Template Transfomration Toolkit)です。過去にはMicro-ORMとテーブルのクラス定義自動生成についてという記事で、データベースのテーブル定義からマッピング用のC#コードを生成する方法を紹介しました。テーブル定義は、実際にDB通信してもいいし、あるいは何らかの定義ファイルを解析して生成、とかでもいいですね。また、最近の私の作っているライブラリには(UnityのIL2CPP対策で)コードジェネレーターがついていますが(MagicOnion, MasterMemory, MessagePack-CSharpなど)、それらの生成テンプレートは全てT4で作っています。

元々はVisual Studioべったりでしたし、実際べったりなのですが、Mac環境ではVisual Studio for Macで、あるいは(一手間入りますが)VS Codeで使用したり、最近だとRiderが2019.3 EAP 5からばっちしサポートされたようなので、MacやRider派の人も安心です。RiderのT4サポートは曰く

You asked us to support T4, and we’ve answered! T4 support is here, based on our own generator and available as a pre-installed plugin.
The plugin is open-sourced (https://github.com/JetBrains/ForTea) and your contributions are very welcome.
Feature-rich C# support in code blocks includes highlighting, navigation, code completion, typing assistance, refactorings, context actions, inspections, formatting, and more.
T4-specific features include inspections, typing assistance, folding, brace matching, etc.
Extensive support is offered for includes to make the resolve in C# code as correct as possible.
You can execute T4 templates.
You can also debug T4 templates.
All these features work across Windows, macOS, and Linux.

だそうで、なかなかイケてるじゃないですか。Visual Studioも、Riderもそうですが、テンプレートエンジンでデバッガ動かしてステップ実行できたりするのが地味に便利です。VS Codeだと設定に一手間が必要なので(Qiitaにて.NET Core+VS CodeでもT4 テンプレートエンジンでコード生成したい!といった紹介もありますが)、VS2019, VS for Mac, Riderを使ったほうが楽そうです。

T4には2種類の生成パターン、デザイン時コード生成(TextTemplatingFileGenerator)と、実行時テキスト生成(TextTemplatingFilePreprocessor)の2種類がありますが、両方紹介します。

また、詳細なドキュメントがコード生成と T4 テキスト テンプレートにあり、実際かなり複雑な機能も搭載してはいますが、テキストテンプレートで複雑なことはやるべきではない(テキストテンプレートなんてあまり使わないような機能で使い倒した複雑なことやられても解読に困るだけ)ので、シンプルに使いましょう。シンプルに使う分には、全く難しくないです。

デザイン時コード生成

デザイン時コード生成とは、テンプレート単体でテキストを出力するタイプです。出力されたコードが、そのまま自身のプロジェクトのコンパイル対象になるイメージ。使い道としては、手書きだと面倒くさい単純な繰り返しのあるソースコードを一気に量産するパターンがあります。例えばジェネレクスのT1~T16までの似たようなコードを作るのに、一個雛形をテンプレートとして用意して for(1..16) で生成すれば一発、というわけです。他に、プリミティブの型(intとかdoubleとか)に対してのコード生成などもよくやりますね。またマークダウンで書かれた表(別の人がドキュメントとして書いているもの)から、enumを生成する、なんてこともやったりしますね。違うようで違わないようで実際微妙に違う退屈なユニットテストコードの生成、なんかにも使えます。

例としてMessagePackのカスタムシリアライザとして、以下のようなものを作りたいとします(単純な繰り返しの例としてちょうどよかったというだけなので、MessagePackの細かいAPIの部分は見なくてもいいです)。

using System;
using System.Buffers;
 
namespace MessagePack.Formatters
{
    public sealed class ForceInt16BlockFormatter : IMessagePackFormatter<Int16>
    {
        public static readonly ForceInt16BlockFormatter Instance = new ForceInt16BlockFormatter();
 
        private ForceInt16BlockFormatter()
        {
        }
 
        public void Serialize(ref MessagePackWriter writer, Int16 value, MessagePackSerializerOptions options)
        {
            writer.WriteInt16(value);
        }
 
        public Int16 Deserialize(ref MessagePackReader reader, MessagePackSerializerOptions options)
        {
            return reader.ReadInt16();
        }
    }
 
    // 以下、Int16の部分がInt32だったりDoubleだったりするのを用意したい。
}

Int16になっている部分を、Int32やDoubleなど全てのプリミティブにあてはめて作りたい、と。手書きでも気合でなんとかなりますが、そもそも面倒くさいうえに、修正の時は更に面倒くさい。なので、これはT4を使うのが最適な案件といえます。

例はVisual Studio 2019(for Windows)で説明していきますが、T4の中身自体は他のツールを使っても一緒なのと、最後にRiderでの使用方法を解説するので、安心してください。

まずは新しい項目の追加で、「テキスト テンプレート」を選びます。

すると、以下のような空のテンプレートが生成されたんじゃないかと思われます。

<#@ template debug="false" hostspecific="false" language="C#" #>
<#@ assembly name="System.Core" #>
<#@ import namespace="System.Linq" #>
<#@ import namespace="System.Text" #>
<#@ import namespace="System.Collections.Generic" #>
<#@ output extension=".txt" #>

csprojには以下のような追加のされ方をしています。

<ItemGroup>
    <None Update="ForceSizePrimitiveFormatter.tt">
        <Generator>TextTemplatingFileGenerator</Generator>
        <LastGenOutput>ForceSizePrimitiveFormatter.txt</LastGenOutput>
    </None>
    <None Update="ForceSizePrimitiveFormatter.txt">
        <DesignTime>True</DesignTime>
        <AutoGen>True</AutoGen>
        <DependentUpon>ForceSizePrimitiveFormatter.tt</DependentUpon>
    </None>
</ItemGroup>

2個のItemが追加されているのは、T4本体と、生成物の2つ分です。<Generator>TextTemplatingFileGenerator</Generator>というのがT4をこれで処理しますよ、という話で、DependentUponはソリューションエクスプローラーでの見た目上、ネストする親を指定、ということになっています。Visual Studioの不正終了なので、たまに***1.csなどといった末尾にインクリメントされたファイルしか生成されなくなってムカつく!という状況にたまによく陥るのですが、その場合はLastGenOutputあたりを手書きで修正してけば直ります。

さて、まず思うのはシンタックスハイライトが効いていない!ということなので、しょうがないのでVS拡張を入れます。私がよく使うのはtangible T4 Editor 2.5.0 plus UML modeling toolsというやつで、インストール時にmodeling Toolsとかいういらないやつはチェック外してT4 Editorだけ入れておきましょう。なお、Visual Studioは閉じておかないとインストールできません。他のT4用拡張も幾つかあるのですが、コードフォーマッタがキモいとかキモいとか色々な問題があるので、私はこれがお気に入りです(そもそもコードフォーマットがついてない!変な整形されるぐらいなら、ないほうが百億倍マシです)。

さて、<#@ ... #>が基本的な設定部分で、必要な何かがあればここに足していくことになります。assembly nameは参照アセンブリ、基本的なアセンブリも最小限しか参照されていないので、必要に応じて足しておきましょう。ちなみにRiderだと何も参照されていない空テンプレートが生成されるので、デフォだとLINQすら使えなくてハァァァ?となるので要注意。System.Coreぐらい入れておけよ……。

import namespaceはまんま、名前空間のusingです。output extensionは、フツーは.csを吐きたいと思うので.csにしておきましょう。場合によってはcsvとかjsonを吐きたい場合もあるかもしれないですが。

次に、<# … #> を使って、テンプレートに使う変数群を用意します。この中ではC#コードが書けて、別に先頭じゃなくてもいいんですが、あまりテンプレート中にC#コードが散らかっても読みづらいので、用意できるものはここで全部用意しておきましょう。

<#
    var types = new[]
    {
        typeof(Int16),
        typeof(Int32),
        typeof(Int64),
        typeof(UInt16),
        typeof(UInt32),
        typeof(UInt64),
        typeof(byte), 
        typeof(sbyte),
    };
 
    Func<Type, string> GetSuffix = t =>
    {
        return t.Name == nameof(Byte) ? "UInt8" : (t.Name == nameof(SByte)) ? "Int8" : t.Name;
    };
#>

今回は生成したいプリミティブ型を並べた配列を用意しておきます。また、ここではローカル関数を定義して、くり返し使う処理をまとめることもできるんですが(テンプレート中に式を書くと見にくくなるので、引数を受け取ってstringを返す関数を用意しておくと見やすくなります)、tangible T4 Editorがショボくてローカル関数に対してシンタックスエラー扱いしてくるので(動作はする)、Funcを使うことでお茶を濁します。

ここから先は本体ですが、短いので↑で見せた部分も含めてフルコードが以下になります。Visual Studioの場合は保存時、Riderの場合は右クリックから手動で実行した場合に、ちゃんとファイルが生成されていることが確認できるはずです!

<#@ template debug="false" hostspecific="false" language="C#" #>
<#@ assembly name="System.Core" #>
<#@ import namespace="System.Linq" #>
<#@ import namespace="System.Text" #>
<#@ import namespace="System.Collections.Generic" #>
<#@ output extension=".cs" #>
<#
    var types = new[]
    {
        typeof(Int16),
        typeof(Int32),
        typeof(Int64),
        typeof(UInt16),
        typeof(UInt32),
        typeof(UInt64),
        typeof(byte), 
        typeof(sbyte),
    };
 
    Func<Type, string> GetSuffix = t =>
    {
        return t.Name == nameof(Byte) ? "UInt8" : (t.Name == nameof(SByte)) ? "Int8" : t.Name;
    };
#>
// <auto-generated>
// THIS (.cs) FILE IS GENERATED BY T4. DO NOT CHANGE IT. CHANGE THE .tt FILE INSTEAD.
// </auto-generated>
 
using System;
 
namespace MessagePack.Formatters
{
<# foreach(var t in types) { #>
    public sealed class Force<#= t.Name #>BlockFormatter : IMessagePackFormatter<<#= t.Name #>>
    {
        public static readonly Force<#= t.Name #>BlockFormatter Instance = new Force<#= t.Name #>BlockFormatter();
 
        private Force<#= t.Name #>BlockFormatter()
        {
        }
 
        public void Serialize(ref MessagePackWriter writer, <#= t.Name #> value, MessagePackSerializerOptions options)
        {
            writer.Write<#= GetSuffix(t) #>(value);
        }
 
        public <#= t.Name #> Deserialize(ref MessagePackReader reader, MessagePackSerializerOptions options)
        {
            return reader.Read<#= t.Name #>();
        }
    }
 
<# } #>
}

記法の基本的なルールは<# … #>で括っている部分以外は平文で出力されます。そして、<#= … #>が式で、そこが文字列として展開されます。

なお、テンプレートを書くにあたって、長年の経験から得たおすすめのお作法があります。

  • 計算式はなるべくテンプレート中で書くのを避ける、ために事前に関数として定義しておく
  • <auto-generated>を冒頭に書く、これはlintによる解析対象から外れる効果があるのと、このファイルがどこから来ているのかを伝えるために有用
  • foreachやifなどはなるべく一文で書く、複数行に渡っているとテンプレート中のノイズになって見難くなる。また、あまり
  • <#の開始行はインデントつけずに先頭で、というのもインデントつけてると平文のテンプレート生成対象になるため生成コードのインデントがズレやすい

この辺を守ると、割と綺麗に書けると思います。テンプレートはどうしてもコード埋め込みがあって汚くなりやすいので、なるべく綺麗にしておくのは大事です。それでもどうしても避けられないifだらけで、読みにくくなったりはしてしまいますが、そこはしょうがない。

実行時テキスト生成

実行時テキスト生成は、いわゆるふつーに想像するテンプレートエンジンの動作をするもので、プログラム実行時に、変数を渡したらテンプレートにあてはめてstringを返してくれるクラスを生成します。データベースのテーブル定義からマッピング用のC#コードを生成するツール、であったり、私がよくやってるのはRoslyn(C# Compiler)でC#コードを解析して、それをもとにして更にC#コードを生成するツールであったり、というかむしろC#コードを解析してKotlinコードを生成したりなど、やれることはいっぱいあります。リフレクションでアセンブリを舐めて、条件に一致した型、メソッドから何かを作る、みたいなのも全然よくありますね。

これの作り方は、追加→新しい項目から「ランタイム テキスト テンプレート」を選ぶと、悲しいことに別に普通の「テキスト テンプレート」とほぼ同じものが生成されてます(VS2019/.NET Coreプロジェクトの場合)。なぜかというと、csprojを開くとGeneratorがTextTemplatingFileGenerator、つまり普通のテキストテンプレートと同じ指定になっているからです。これは、多分バグですね、でもなんか昔から全然直されてないのでそういうもんだと思って諦めましょう。

しょーがないので手書きで直します。GeneratorのTextTemplatingFileGeneratorをTextTemplatingFilePreprocessorに変えてください。そうすると以下のようなファイルが生成されています(Visual Studioの場合は保存時、Riderの場合は右クリックから手動で実行した場合)

    #line 1 "C:\Users\neuecc\Source\Repos\ConsoleApp14\ConsoleApp14\MyCodeGenerator.tt"
    [global::System.CodeDom.Compiler.GeneratedCodeAttribute("Microsoft.VisualStudio.TextTemplating", "16.0.0.0")]
    public partial class MyCodeGenerator : MyCodeGeneratorBase
    {
        /// <summary>
        /// Create the template output
        /// </summary>
        public virtual string TransformText()
        {
            return this.GenerationEnvironment.ToString();
        }
    }

ファイル名で作られたパーシャルクラスと、TransformTextメソッドがあるのが分かると思います。これで何となく使い方は想像つくと思いますが、new MyCodeGenerator().TransformText()でテンプレート結果が実行時に得られる、という寸法です。

さて、しかしきっとコンパイルエラーが出ているはずです!これはNuGetで「System.CodeDom」を参照に追加することで解決されます。別にCodeDomなんて使ってなくて、CompilerErrorとCompilerErrorCollectionというExceptionを処理する生成コードが吐かれてるから、というだけなので、自分でその辺のクラスを定義しちゃってもいいんですが、まぁ面倒くさいんでCodeDom参照するのが楽ちんです。この辺ねー、昔の名残って感じでめっちゃイケてないんですがしょーがない。

それと行番号がフルパスで書かれててめっちゃ嫌、というかフルパスが書かれたのをバージョン管理に突っ込めねーよ、って感じなので、これも消しましょう。linePragmas=”false”をテンプレート冒頭に書いておけば消えます。

<#@ template language="C#" linePragmas="false" #>
<#@ assembly name="System.Core" #>
<#@ import namespace="System.Linq" #>
<#@ import namespace="System.Text" #>
<#@ import namespace="System.Collections.Generic" #>
<#@ output extension=".cs" #>

この対応はほとんど必須ですね、ていうかデフォでfalseにしといてくれよ……。

さて、テンプレートにパラメーターを渡す方法ですが、これは生成されたクラス名と同じpartial classを定義すればOK。

namespace ConsoleApp14
{
    // 名前空間/クラス名(ファイル名)を合わせる(親クラスの継承部分は書かなくてOK)
    public partial class MyCodeGenerator
    {
        public GenerationContext Context { get; }
 
        // とりあえずコンストラクタで受け取る
        public MyCodeGenerator(GenerationContext context)
        {
            this.Context = context;
        }
    }
 
    // 生成に使うパラメーターはクラス一個にまとめておいたほうが取り回しは良い
    public class GenerationContext
    {
        public string NamespaceName { get; set; }
        public string TypeSuffix { get; set; }
        public int RepeatCount { get; set; }
    }
}

これでテンプレート中でContextが変数として使えりょうになります。テンプレートの例として、面白みゼロのサンプルコードを出すと……(Roslynとか使うともっと意味のあるコード例になるのですが、本題と違うところがかさばってしまうので、すみません……)

<#@ template language="C#" linePragmas="false" #>
<#@ assembly name="System.Core" #>
<#@ import namespace="System.Linq" #>
<#@ import namespace="System.Text" #>
<#@ import namespace="System.Collections.Generic" #>
<#@ output extension=".cs" #>
// <auto-generated>
// THIS (.cs) FILE IS GENERATED BY ConsoleApp14.exe. DO NOT CHANGE IT.
// </auto-generated>
namespace <#= Context.NamespaceName #>
{
<# foreach(var i in Enumerable.Range(0, Context.RepeatCount)) { #>
    public class Foo<#= Context.TypeSuffix #><#= i #>
    {
    }
 
<# } #>
}

RepeatCountの回数で中身空のクラスを作るというしょっぱい例でした。これの注意事項は、普通のテキストテンプレートと特に変わりはないのですが、auto-generatedのところに、生成ツール名を入れておいたほうがいいです。外部ツールでコード生成するという形になるため、ファイルだけ見てもなにで生成されたかわからないんですね。あとから、何かで作られたであろう何で作られたかわからない自動生成ファイルを解析する羽目になると、ツールの特定から始めなくちゃいけなくてイライラするので、この辺をヘッダにちゃんと書いといてあげましょう。ただたんに「これは自動生成されたコードです」と書いてあるだけよりも親切で良い。

記述におけるコツは、やはりテンプレート中に式を書いて文字列を生成するよりかは、この場合だとContext側にメソッドを作って、引数をもらってstringを返すようにすると見通しが良いものが作りやすいでしょう。ちなみにthis.ContextのContextのIntelliSenseは効きません、そっちの解析までしてくれないので。テンプレートファイルにおける入力補完は甘え、おまけみたいなもんなので、基本的には頼らず書きましょう。もちろん、そのせいでばんばんTypoしてエラーもらいます。これが動的型付け言語の世界だ!をC#をやりながら体感できるので、いやあ、やっぱ静的型付け言語はいいですねえ、という気持ちに浸れます。

さて、こうして出来たクラスは、ただのパラメーターを受け取ってstringを返すだけのクラスなので、何に使っても良いのですが、9割はシンプルなコマンドラインツールになるのではないでしょうか。

C#でコマンドラインツールといったら!私の作ってるMicroBatchFrameworkが当然ながらオススメなので、それを使ってツールに仕立ててみましょう。

using MicroBatchFramework;
using System;
using System.IO;
using System.Text;
using System.Threading.Tasks;
 
namespace ConsoleApp14
{
    class Program : BatchBase
    {
        static async Task Main(string[] args)
        {
            await BatchHost.CreateDefaultBuilder().RunBatchEngineAsync<Program>(args);
        }
 
        public void Run(
            [Option("o", "output file path")]string outputPath,
            [Option("n", "namespace name")]string namespaceName,
            [Option("t", "type name suffix")]string typeSuffix = "Foo",
            [Option("c", "type generate count")]int repeatCount = 10
            )
        {
            // パラメータを作って
            var context = new GenerationContext
            {
                NamespaceName = namespaceName,
                TypeSuffix = typeSuffix,
                RepeatCount = repeatCount
            };
 
            // テキストを生成して
            var text = new MyCodeGenerator(context).TransformText();
 
            // UTF8(BOMなし)で出力
            File.WriteAllText(outputPath, text, new UTF8Encoding(false));
 
            Console.WriteLine("Success generate:" + outputPath);
        }
    }
}

これで ConsoleApp14.exe -o "foo.cs" -n "HogeHoge" -t "Bar" -c 99 というしょっぱいコマンドでfoo.csが吐かれるツールが完成しました!

RiderにおけるT4

RiderでのT4は、Visual Studioが使っている生成ツールとは違う、T4の記法として互換性のあるJet Brains独自のツールを実行している気配があります(そのため、場合によっては互換性がないところもあるかもしれません、というか実際linePragms=falseで行番号が消えなかった……)

実行自体は簡単で、ttに対して右クリックしてRunを選べばデザイン時コード生成、Preprocessを選べば実行時テキスト生成の出力結果が得られます。

image

現時点ではEAP、つまりプレビュー版ですが、まぁ他にもいっぱい良い機能が追加されてるっぽいので、Riderユーザーは積極的にEAPを使っていけばいいんじゃないかしら。

T4にできないこと

T4は、基本的に.ttで書かれたファイルを事前に(VSだと保存時、Riderだと任意に、あるいは設定次第でビルド時に)外部ツールが叩いて、テキスト(.csだったり色々)を生成します。いいところはC#プロジェクトと一体化して埋め込まれるので、パフォーマンスもいいし、そもそもT4生成時に型が合わなければエラーが出てくれる(動的の塊であるテンプレートファイルにとって、書き間違えは日常茶飯事なので、これは結構嬉しい)。実行効率も良いです、ファイル読んでパースして必要があればキャッシュして云々というのがないので。

が、しかし、プログラムが実行時に動的にテンプレートを読み込んでなにかする、みたいなことはできません。ツールのビルド時にテンプレートが出来上がってないといけないので、プラグイン的に足すのは無理です。それは成約になる場合もある、でしょうし、私的には型もわからないようなのを動的に合わせてテンプレート作るとか苦痛なので(←最近なんかそういうのやる機会が多くて、その度にシンドイ思いをしてる)、パラメータ渡しだけでなんとかして済むようにして諦めて作り込んだほうが百億倍マシ、ぐらいには思っていますが、まぁそういうのがしたいというシチュエーション自体は否定できません。その場合は、他のテンプレートエンジンライブラリを選んで組み込めば良いでしょう、T4がやや特殊なだけで、他のテンプレートエンジンライブラリは、むしろそういう挙動だけをサポートしているので。

まとめ

T4は十分使い物になります。微妙にメンテされてるのかされてないのか不安なところもありますが、そもそもMicrosoftもバリバリ使っているので(GitHubに公開されているcorefxのコードとかはT4で生成されているものもかなりあります、最近追加されたようなコードでも)、全く問題ないでしょう。実際、記法も必要十分揃っているし、特に極端に見にくいということもないと思います、ていうかテンプレートエンジンとしてフツーなシンタックスですしね。

仮に複雑なことやりたければ、例えばテンプレートをパーツ化して使い回すために分割して、都度インポートとか、というのもできます(T4 インクルード ディレクティブでは.t4という拡張子が紹介されていますが(拡張子はなんでもいい)、一般的には.ttincludeという拡張子が使われています)。他いろいろな機能がありますが、あらためて、テキストテンプレートごときで複雑なことやられると、追いかける気が失せるので、なるべく単純に保ちましょう。やるとしてもせいぜいincludeまで。それ以上はやらない。

というわけで、どうでしょう。MicroBatchFrameworkとも合わせて、C#のこの辺の環境は割といいほうだと思ってます。コード生成覚えるとやれることも広がるので、ぜひぜひ、コード生成生活を楽しんでください!

また、Unityでも普通に便利に使えると思います。Editor拡張でソースコード生成するものを用意するパターンは多いと思いますが(なにかリソースを読み込んで生成したり、あるいはそのままAssembly.GetExecutingAssembly().GetTypes()して型から生成したり)、その時のテンプレートとして、普通にstringの連結で作ってるケースも少なくなさそうですが、「デザイン時コード生成」も「実行時テキスト生成」も、どっちも全然いけます。「T4にできないこと」セクションに書いたとおり、よくも悪くも外部ツールで実行環境への依存がないので。

Unite Tokyo 2019でC# Structの進化の話をしてきました

Unite Tokyo 2019にて、「Understanding C# Struct All Things」と題して登壇してきました!動画は後日Unity Learning Materialsに公開される予定です。

【Unite Tokyo 2019】Understanding C# Struct All Things from UnityTechnologiesJapan002

C#成分強めなので、Unityに馴染みのない人でも読んで楽しめる内容になっていると思います。とはいえ勿論、Uniteでのセッションであるということに納得してもらえるようUnity成分もきちんと取り入れています。というわけで、どちらの属性の人にも楽しんでいただければ!

structに関する機能強化、実際めっちゃ多いんですが、それをカタログ的に延々と紹介してもつまらないので、そうしたカタログ紹介っぽさが出ないように気を配ってます。あと、あんましそういうのでは脳みそに入ってこないというのもあるので。

応用例的なところのものは、ないとつまらないよねーということで色々持ってきたのですが、もう少し説明厚くしても良かったかなー感はありました。セッション内でも雰囲気で流した感じありますしね。とはいえ尺とか尺とか。まぁ雰囲気を分かってもらえれば(structは色々遊べるよ、という)いい、と割り切った面もあるにはあります。詳しくは資料を熟読してください!

Span/NativeArrayの説明も厚くしたくはあったんですが、structそのものの本題からは若干外れるので見送り。あと尺とか尺とか。

今年のUnite、もの凄くいいイベントでした。神運営とはこのことか……。そしてDOTSが熱い。めっちゃやるやる詐欺なので、いい加減本当にそろそろDOTSに手を出して楽しみたいですます!

あと、MessagePack-CSharp v2はいい加減そろそろ出るはず予定です、ちなみにSystem.Memoryとかにめっちゃ依存しているので、MessagePack-CSharpを入れるとSpanとかSystem.Runtime.CompilerServices.Unsafeとかが解禁されます(依存ライブラリとして同梱する予定なので)。いいのかわるいのか。まあ、いいでしょふ。未来未来。

CEDEC 2019にてMagicOnion、或いは他言語とC#の協調について話しました

セッション名はUnity C# × gRPC × サーバーサイドKotlinによる次世代のサーバー/クライアント通信 〜ハイパフォーマンスな通信基盤の開発とMagicOnionによるリアルタイム通信の実現〜(長い!)ということで二部構成になっていて、私は後半部分を担当しました。

Unity C#と.NET Core(MagicOnion) C# そしてKotlinによるハーモニー from Yoshifumi Kawai

Cysharpは他社さんのお仕事も(ボリューム次第で、今はちょっとしたコンサルティングぐらいしか空きがないんですが)受けたりも可能です、ということでアプリボットさんのお手伝いをちょいちょいしています。リアルなMagicOnionの採用の話として、どんな風にやってるんですかねーというところの一環をエモ成分強めで語ってみました。リリースどころかタイトルもまだ未発表なので技術的な部分が弱めなので、次はリアルな実例として色々詰めたいところですね!

前半部、というかがっちゃんこされている資料はこちらで公開されています。前半でgRPCいいぞ!という話をしているのに、こちらは冒頭でprotoは嫌だお!という展開で繋げるアレゲさでしたが、まあジョークの一環です。多分。はい。protoのいいところは中間形式であり言語agnosticなところで、protoのよくないところは中間形式であること、ですね。これが何を言っているかを理解できれば100点満点です!是非の議論は、このことを理解してから進めましょう。

MagicOnionは、ちょうど今日Ver 2.4.0をリリースしまして、やる気満々です。次の展開もいろいろ考えているので、というか積みタスクがんがんがんが。まぁ、順次やってきます。

さて、9月はもう一つ、「Understanding C# Struct All Things」と第してUnite Tokyo 2019でセッションします。 Day 2のRoom A、13:30からでライブ配信もあるので、そちらも見ていただければ!

TaskとValueTaskの使い分け、或いはValueTaskSupplementによる福音

ValueTaskSupplementというライブラリを新しく作って公開しました!

これは、ValueTaskにWhenAny, WhenAll, Lazyを追加するという代物で、それだけだとヘーそーなんだー、としか思えないと思われます。しかし、ValueTaskを使っていくと、めっちゃくちゃ欲しくなる機能になってます。ないと死ぬレベルで。

と、いうわけで、なんでこれが必要なのか、っていうところから説明します。

TaskとValueTask

C# 5.0にasync/awaitが導入された当初はTaskしか存在しませんでした。標準APIのあらゆるメソッドにasyncメソッドを生やすなど、Microsoftの多大な努力により、C#はいち早く非同期時代を迎え、async/awaitは多用(濫用とも言う)されるようになりました。しかし、多用された結果、当初思ってたよりもTaskのオーバーヘッド多くね?同期をラップするだけのシチュエーションも少なくなくね?ということに気付き、C# 7.0から登場したのがValueTaskです。

登場当時のValueTaskは T | Task[T] という、もし中身が同期の場合はTを、非同期の場合はTaskをラップしたものとして存在しました。なので、TaskとValueTaskの使い分けは、中身が非同期の場合が確定している場合はラップが不要で、かつ(当時)スタンダードな定義に沿うTaskを基本に考えていくのが良いでしょう。と、されていました。

が、しかし、実際にアプリケーションを作っていくと、都度使い分けなんて考えられるものじゃないし、ValueTaskのオーバーヘッドといってもstructでラップするだけの話でそこまで大きいわけじゃない(同期のものをTaskで定義したほうがよほど大きい)ので、普通にアプリケーションで定義する場合のルールは全部ValueTaskでいーんじゃね?と思っていたりは、私の個人的な見解どまりでありました。

そして、更にパフォーマンスを追求する中で、ValueTask->Task変換のオーバーヘッドをなくし、中身をそれぞれに特化したコードを挟み込めるように IValueTaskSource というものが導入されました。これによりValueTaskは T | Task[T] | IValueTaskSource のどれかの状態を持つという共用体となり、個別に実装されたシナリオでは中身がTask[T]の場合よりもIValueTaskSourceの場合のほうがパフォーマンスが高いということで、名実ともにValueTaskの天下の時代が始まりました。

大々的にパブリックAPIにも露出してくるのは.NET Core 3以降だと思われますが、今でも問題なく使える状態&KestrelやSystem.IO.PipelinesにはValueTaskによるAPIが既に露出しています。MagicOnionのフィルターもValueTaskだったりしたりしましたり。

なお、別の世界線ではUniTaskというものも存在しますが、これは ValueTask + IValueTaskSource に近い代物です。つまり別にTaskなんていらなかったんや……。

ValueTaskの欠点

そんなValueTask最大の欠点は、ユーティリティの欠如。つまり、WhenAllやWhenAnyができない。それらが必要な際はAsTaskでTaskに変換する必要がありました。が、Taskに変換する時点でオーバーヘッドじゃーん。しかもいちいちAsTaskするのはクソ面倒くさい!せっかく IValueTaskSource があるなら、IValueTaskSourceを使ってネイティブなValueTask用のWhenAllやWhenAnyを作ればハイパフォーマンスじゃん!というわけで、それらを提供するのがValueTaskSupplementです。

using ValueTaskSupplement; // namespace
 
async ValueTask Demo()
{
    // `ValueTaskEx`が使う唯一の型です
 
    // こんな風な別々の型のValueTaskがあったとしても
    ValueTask<int> task1 = LoadAsyncA();
    ValueTask<string> task2 = LoadAsyncB();
    ValueTask<bool> task3 = LoadAsyncC();
 
    // awaitできて、タプル記法でサクッと分解できて便利!
    var (a, b, c) = await ValueTaskEx.WhenAll(task1, task2, task3);
 
    // WhenAnyでは int winIndexでどれが最初に値を返したか判定できます
    var (winIndex, a, b, c) = await ValueTaskEx.WhenAny(task1, task2, task2);
 
    // Timeoutみたいなものの実装はこんな風に
    var (hasLeftResult, value) = await ValueTaskEx.WhenAny(task1, Task.Delay(TimeSpan.FromSeconds(1)));
    if (!hasLeftResult) throw new TimeoutException();
 
    // Lazyも用意されています!
    // awaitを呼ぶまで遅延&値がキャッシュされるAsyncLazyのような代物ですが
    // 型がValueTask<T>そのものなので、フィールドに保持したまま、WhenAllなどがそのまま書けて便利
    ValueTask<int> asyncLazy = ValueTaskEx.Lazy(async () => 9999);
}

と、いったように、ただのTask.Xxxよりも更に便利になった機能が追加されていて、もう全部ValueTaskで統一でいいっしょ、って気になれます(特に var (a, b, c) = await ….)が便利ですよ!

まとめ

時代はValueTask。Taskのことは忘れて全部ValueTaskで良いのですー、良いのですー。そして、ValueTaskで統一したら、すぐに標準のまんまじゃしんどいのですー、ってことに気づくでしょふ。そこでValueTaskSupplementですよ、っという流れです。絶対そうなります。というわけで諦めて(?)使いましょう。

ところで、最近よくCygames Engineers’ Blogに寄稿しているのですが、なんとなくの私の中の使い分けは、Unityに関する成分が含まれる(新規)ライブラリはCygamesのブログのほうに、そうじゃないものはここに、みたいな気持ちではいます。まぁ、どっちも見ていただければればですです。

また、直近イベントでは9月4日にCEDEC 2019で「Unity C# × gRPC × サーバーサイドKotlinによる次世代のサーバー/クライアント通信 〜ハイパフォーマンスな通信基盤の開発とMagicOnionによるリアルタイム通信の実現〜」、9月26日にUnite Tokyo 2019で「Understanding C# Struct All Things」というセッションを行うので、是非是非見に来てください!

Microsoft MVP for Developer Technologies(C#)を再々々々々々々々受賞しました

しました。カテゴリ名が毎回ちょくちょく変わってるんですが、今の状態はDeveloper Technologiesだそうです。つまりC#です。一年ごとに再審査があって、今回も通りました。

去年はCysharpの設立もあり、よりC#に対して直接的に世の中に作用させていくよ!という意思を示しました。まだ活動は始まったばかりですが、ともあれC#を引っ張っていきたいという心持ちがあります。黙ってても別にC#は絶対死にはしないと思ってるんですが、もう少し表に立って光り輝いて欲しいよね、そこが足りないと思うんで、その辺をうまく補完できればなというところです。

去年の宣言は

去年よりも上を、去年よりも上を、とハードルは無限に高くなっていくので、個人にせよ会社にせよ、世界にインパクトを残していける何かをやっていこう、というのが目標ですね。

MagicOnionのリブートは比較的成功していると思いますし、MessagePack for C#は、より強力なライブラリになるよう画策中です。UniTaskは唯一無二でしょう。ワールドスタンダードをここから作っていくんだという気概でやっていますし、ある程度はやれているんじゃあないかしらん。ともあれ、まだ全然足りないので、より気合い入れてやっていこうかと。

引き続き主戦場はC#とUnityです。今はちょうど時代の変わり目で、多くの会社で、旧来のフレームワークから新しいフレームワークに移し替えるという話をよく聞きます。そこで.NET Coreですよ?と差し込める最後のチャンス(テクノロジースタックが固定されたら、また次の5年は入れ替えないですからねえ)、というぐらいに思ってるので(黙ってるとGoになっちゃいますしね!)、C#, .NET Core, それとUnityが価値あるものですよ、というところを多くの人に実感してもらえるように、やっていきます。そして困ったことがあればCysharpのお問い合わせフォームに投げてもらえればチャリンチャリンでウィンウィン。

MVPもメンツがだいぶ入れ替わってる感じで、それは非常に良いと思ってます。新陳代謝大事。そんな中で、私は古い方の人間に入るわけなので、居座ってる勢はただ単なる昔の成果の惰性で受賞続いているとかではなく、常に新しい成果でねじ伏せれるべきなんじゃあないでしょーか。私はしっかりやってると思ってましてよ。

そんなわけで引き続き、今年もよろしくお願いします。

Comment (1)

匿名 : (07/12 12:48)

ZeroFormatter……。

Trackback(0)
Write Comment

C#のOpenTelemetry事情とCollectorをMagicOnionに実装した話

を、してきました。昨日。OpenCensus/OpenTelemetry meetup vol.2にて。

Implements OpenTelemetry Collector in DotNet from Yoshifumi Kawai

もともとトレースとかメトリクスの標準化として、OpenCensus(Google)陣営とOpenTracing(CNCF)陣営がいて、正直どっちも流行ってる気配を感じなかったのですが、合流してOpenTelemetryが爆誕!これは本当に今年の頭に発表されたばかりで、仕様策定が完了するのが今年9月(予定)といった感じで、まだ練ってる最中というところです。ただ全体的にはOpenCensusベースでSDKが組まれているので、OpenCensusの時点で完成度がある程度高かったSDKは、割とそのままでも使えそうな雰囲気はあります。

個人的な意義とかはスライドにも書きましたが、まあ、流行って欲しいですね。概念はめっちゃ良いと思うので、きっちり浸透して使われるようになって欲しい。ぎっはぶスターだけが尺度ではないとはいえ、リファレンス実装のJava版の125が最大スター数とか、ワールドワイドで注目度弱すぎないか!?みたいな気は、あります。大丈夫かな。大丈夫ですよね……。一応、参画企業は名だたるところも多いし仕様分裂してるわけでもないので、乗っかる価値はあるんじゃないかと、思います。

.NET SDKの事情

opentelemetry-dotnetで、メインに開発してるのはMicrosoftの人間が一人やってますね。GitHubの草で見ても毎日張り付いてopentelemetry系のなにかでなにかやってるので、仕事として専任で頑張ってるんじゃないでしょうか、多分。クオリティ的には高くもなく低くもなくというところで、過度に期待しなきゃあそんなもんでしょーということで受け入れられそうです。もともとJavaがリファレンス実装になってて、他の言語は、まず基本的なAPIはそれを踏襲すること、というところもあるので、あまりブーブー言ってもしょうがないかもしれません。

Collectorの実装がちょっと面白くて、AspNetCoreのCollectorHttpClientのCollectorは、 DiagnosticSourceという比較的新しい仕組みから情報を取るようになっています。これによって、プロファイラAPIによるAuto Instrumentによるパフォーマンス低下などもなく、しかし特にユーザーはなにもせずに、メトリクスが取得できるようになっています。

ADO.NETのCollectorがないのでDB系が取れないんですが、多分まだADO.NETがDiagnosticSourceに対応していないので、それが対応するまではやらないみたいなつもりなんだと思います。さすがにADO.NETのCollectorがないと話にならないでしょー。

まとめ

MagicOnionの事情としては実装のPRは用意してますが、まだMergeしてません。ただまぁ、スライドに書いたのですが、結構これらを入れるだけで、撮って出しでもいい感じのダッシュボードが作れるんじゃないかと思います。このへんは前職でリリースしたゲームのダッシュボードを作り込んだ経験が生きてるかな、ってのはありますね。いやほんと。

ともあれというわけで、私はOpenTelemetryにベットするんで、みんなも是非やっていきましょう!ね!流行らせないと未来はない!

MagicOnion勉強会を開催しました

【Unity / .NET Core】 MagicOnion勉強会。正確には開催してもらいました、ですが!バーチャルキャストさん、ありがとうございました!

こちらは私のスライド、 The Usage and Patterns of MagicOnion になります。

The Usage and Patterns of MagicOnion from Yoshifumi Kawai

実際何に使えるの、というところについて(妄想の)繋ぎ方を紹介したりしました。まぁ、ようするになんでも使えます、ということですね。

MagicOnionはGitHub Starも1000超えたので、野良ぽっと出謎ライブラリからは、少し脱却したんじゃないかと思います。まだメジャー級とは言い難いですが。アングラ級?

私はP2P推すのどうかなーって思ってるわけなんですが、その理由はポジショントーク、じゃなくて自分がサーバー書けるから、ってのは勿論あるんですが、本当にP2Pでいいんすかねー、というのがあり。実際真面目に。リレーサーバー用意するんだったらもう自前でやる領域を秒速で超えちゃうし、P2P→Dedicated Serverだと、機能制限されたサーバーモデル(サーバーがリレーとしてしか機能できなくてロジック積んだりモロモロができない)になっちゃうので微妙に感じたり、結局自前でやるならP2Pでもマッチングどうすんねんであったり、まぁもろもろ色々と。信頼できるクライアント -> サーバーのRPCが一つあるだけで、色々すっきり解決できるんじゃないのかなー、ってのはずっと思っているところで。

MagicOnionに問題がないとは言わないんですが、特にネイティブDLLは問題の塊なのでPure C#実装に変えたいねえ、そうすればプラットフォームの制限もなくなるしねえ、とかもあったりはあったりはあったりはしますが、まぁそのうちなんとかします:) コード生成に関しては肯定的なんですが(リフレクション拒否した非コードジェネレーションのモデルは、やれることにかなり制約入りますですのです)、現状のヘボジェネレーターはよろしくないのでそれも早急に直しまうす。インフラ系はドキュメントとかの拡充でカバーですかね、知識がいるのは事実なので。

発表一覧

勉強会レポ : 【Unity / .NET Core】 MagicOnion勉強会さんのところにまとまっているのですが、こちらでも改めてリンク集で。

これだけトークが集まって、大感謝です。

第二回の開催、は(あるとしても)当面先だとは思いますが、実際MagicOnionを使用した開発に入っているプロジェクトは割とないわけではない(?)という感じですので、ご安心を(?)。一応歴史的にはかなりの負荷を捌いている実績もあるので……!Cysharpとしても、「会社として」力を入れているところがあるので、その辺も安心材料に含めていただければと思っています。最悪、本当に困ったらお問い合わせ下されば色々解決のお手伝いもできるかもしれません。

また、CEDEC 2019ではUnity C# × gRPC × サーバーサイドKotlinによる次世代のサーバー/クライアント通信 〜ハイパフォーマンスな通信基盤の開発とMagicOnionによるリアルタイム通信の実現〜と第して、アプリボットさんと共同でセッションを行うので、そちらも是非是非。

LitJWTに見るモダンなC#のbyte[]とSpan操作法

LitJWT、という超高速な認証ライブラリを作りました。

なんと今回はUnity用が、ない!どころか.NET Standardですら、ない!.NET Core専用になってます(今のとこ)。理由はパフォーマンス都合で現状.NET CoreにしかないAPIを使いすぎたので修正が面倒ということなので、そのうちなんとかするかもしれませんかもしれません。

5倍高速

image

そもそも認証ライブラリでパフォーマンス追求しているものなんてない!ので!まぁそりゃそうだという感じではある。実際、そこまで認証で必要か?というと疑問符が付くところなので、ただのオーバーエンジニアリングなのですが、とはいえ速いというのは良いことです。シンプルに。

JWTに関しては特に説明することもないので(セッションにでも何にでも使えばいいんじゃないかしら、実際、私はMagicOnionのステートレスセッションのために必要なので用意しました)、ここから先は実装の話をします。

モダンBase64(Url)

JWTは大雑把にはJSONをBase64Urlでエンコードして署名を引っ付けたもの、です。Base64UrlというのはBase64の亜種で、URLセーフになるように、使う文字列が少し異なります。性質上、GETでURLにトークンが引っ付いたりするかもですしね。なるほど。

さて、しかしそんなマイナーなBase64Urlをエンコードするメソッドは用意されていないので、普通はこんな風に書いてます。

Convert.ToBase64String(input)
    .TrimEnd('=')      // 新しいstringを作る
    .Replace('+', '-') // 新しいstringを作る
    .Replace('/', '_') // 新しいstringを作る

改めてBase64Urlは、ようするにパディング(4の倍数に収まらない場合に末尾につく)の=が不要で、+が-、/が_なBase64なので、置換!ただたんに置換!する、すなわち新規文字列を無駄に作成!無駄に検索して無駄に作成!なわけです。

実際、別にこのBase64の変換表の一部を差し替えるだけの話なのに。

無駄すぎて発狂しちゃうので、ここは普通に自前でBase64を実装することで大解決しましょう。実際それしか方法はない、しょうがない。

せっかく作るので、今風のAPIにしましょう。例えばデコードのAPIはこんな感じに。

public static bool TryFromBase64UrlString(string s, Span<byte> bytes, out int bytesWritten)
public static bool TryFromBase64UrlChars(ReadOnlySpan<char> chars, Span<byte> bytes, out int bytesWritten)
public static bool TryFromBase64UrlUtf8(ReadOnlySpan<byte> utf8, Span<byte> bytes, out int bytesWritten)

stringだけ受け入れるのではなくて、ReadOnlySpan<char>と、UTF8を直接受け入れられるようにReadOnlySpan<byte>のオーバーロードを用意しましょう(面倒くせえ……)。中身の実装はcharとbyteで似てるようで若干違うので今回は雑にコピペコードで済ませてます。コピペ最強。

ともあれこれでゼロアロケーションなデコードです。

ちなみにSystem.Security.Cryptographyも、こうしたSpan対応のAPIが(.NET Core 2.1なら)あります。.NET Standard 2.0にはありません。2.1から、なのでまだ先です。

bool TryComputeHash(ReadOnlySpan<byte> source, Span<byte> destination, out int bytesWritten)
bool TrySignData(ReadOnlySpan<byte> data, Span<byte> destination, HashAlgorithmName hashAlgorithm, RSASignaturePadding padding, out int bytesWritten)
bool VerifyData(ReadOnlySpan<byte> data, ReadOnlySpan<byte> signature, HashAlgorithmName hashAlgorithm, RSASignaturePadding padding)

今回の最初のリリースが.NETCore Appのみなのは、主にこの辺が理由です。迂回できないこともないんですけどねえ。

stackallocとArrayPoolをめっちゃ使う

先のBase64のデコード繋がりで説明すると、デコード先のbyte[]をどう用意するか、という話であり。headerのBase64とかsignatureのBase64とか、あまり大きくないのが確定しているので、stackallocをSpanで受けて、デコード先を作ります。

Span<byte> bytes = stackalloc byte[Base64.GetMaxBase64UrlDecodeLength(header.Length)];
if (!Base64.TryFromBase64UrlUtf8(header, bytes, out var bytesWritten))

Payloadは長さがわからない(そこそこ大きい可能性もある)ので、stackallocで受けるのは不安があるので、ArrayPoolを使いましょう。

var rentBytes = ArrayPool<byte>.Shared.Rent(Base64.GetMaxBase64UrlDecodeLength(payload.Length));
try
{
    Span<byte> bytes = rentBytes.AsSpan();
    if (!Base64.TryFromBase64UrlUtf8(payload, bytes, out var bytesWritten))
    {
        return DecodeResult.InvalidBase64UrlPayload;
    }
    bytes = bytes.Slice(0, bytesWritten);
 
    // ....
}
finally
{
    ArrayPool<byte>.Shared.Return(rentBytes);
}

ようするに、今どきnew byte[]なんてしたら殺されるぞ!

ReadOnlySpanの辞書を作る

ReadOnlySpan<byte>はref struct!つまりDictionaryのKeyにはできない!けどルックアップはしたい!

どーいうことかというと、例えば

image

HeaderのJSONを舐めて、デコードに使うアルゴリズムが何であるかあるかチェックしたいわけですが、まず、今どきはJSONをstringで検索したりはしません。UTF8のままやります(System.Text.Json(preview)やUtf8Jsonを使いましょう)。特に、今回はBase64Urlからデコードしてきたバイナリなので、更にstringにデコードしてしまうのは無駄の極みなので、絶対避けたいわけです。

そうして、algのvalue部分に相当するReadOnlySpanが切り出せたとしましょう。さて、じゃあこれが何であるか。HS256なのかRS512なのか、そして、それをキーにしてIJwtAlgorithmを取り出したいわけです。必要なデータ構造はDictionary<ReadOnlySpan<byte>, IJwtAlgorithm>>なわけです。が、それは無理。C#の言語仕様がそれを許してくれないのです。困ったねえ。

もちろん、答えは自作しましょう。今回はReadOnlyUtf8StringDictionaryというものを用意しました。Dictionary内部で持っておくキーは別にSpanである必要はないので、普通にbyte[]で確保しておきます。ルックアップだけ

public bool TryGetValue(ReadOnlySpan<byte> key, out TValue value)

というAPIを用意すればOKという寸法です。

実装において、byte[]の一致比較はSpanのSequenceEqualを使えば良いんですが、GetHashCodeの実装だけはどうにもなりません(Utf8Stringも控えてることだし、標準でいい感じのがそろそろ入るといいんですけどねえ)。私は延々と使いまわせいているFarmHashの実装をコピペで用意していますが、適当にxxHashを実装したり何かするといいと思います。適当に拾ってきたものを使うとパフォーマンス的に意味のないクソ実装の可能性もあるので、その辺は適当に気をつけましょう。

最後まで配列の切り出しをしない実装を作る

jwtEncoderのEncodeメソッドは、3つのオーバーロード(名前違い含む)を持ってます。

string Encode<T>(...)
byte[] EncodeAsUtf8Bytes<T>(...)
void Encode<T>(IBufferWriter<byte> writer, ...)

一番使うのは、stringだとは思います。Httpのヘッダーとかに埋めたりするケースが多いと思うので、stringが要求されるのでしょーがない。でも、byte[]を返すもののほうが高速です。内部的には全てUtf8 byte[]で処理しているので、stringへのエンコード処理をバイパスできるからです。例えばgRPCは(MagicOnionも)、バイナリヘッダーを許容しているので、stringヘッダーよりも高速に処理できます。

// gRPC Header
var metadata = new Metadata();
metadata.Add("auth-token-bin", encoder.EncodeAsUtf8Bytes());

さて、じゃあ最後の IBufferWriter<byte> はなにかというと、直接これに書き込みます。まぁ、Span<byte>,int bytesWrittenみたいなものですが、Span<byte>を渡すのが使えるのって、処理後の長さが概ね分かっているときで、JwtのエンコードはPayloadの処理とかあるので、基本的には処理が完了するまで分かりません。ので、bytesWritten形式のAPIは向いてません。

IBufferWriterはStreamみたいなもので、これに直接書き込みます。新しいI/O APIである System.IO.Pipelines で使われているAPIで、つまりは、一応それに対応しているということで。MessagePack-CSharpのv2(現在絶賛制作中)も、IBufferWriterが主役になっています。時代はダイレクトライト。

System.IdentityModel.Tokens.Jwtは最低

JWTの話は特にするつもりはなかったんですが、とにかくSystem.IdentityModel.Tokens.Jwtが最低だということは言っておきたい!とにかくAPIがヤバい!まぁ、これ、他の認証系も統合された抽象化の上に乗っているので、JWT的に不要で意味不明なものがいっぱいついているうえに、その抽象化がエンタープライズグレード(笑)の重厚長大な酷いもので、Microsoftの認証が難しいと感じるとしたら(実際難しい)、ただたんにライブラリのAPIが腐ってるから難しいだけですからね。

何かのフレームワークと統合されてて、ワンポチで導入される、とかだったらまだいいんですが、直接は触りたくないですねえ。誰が作ってんだかって感じですが(お、公開されてる先はAzure配下かな……)

まとめ

MagicOnionで――というのもありますが、認証系はJWT中心に、ちょっと色々考えてます。あとまぁ、さすがにパフォーマンスだけが差別化要因というのはしょっぱいので、Unity対応しよ。

MagicOnion Ver 2.1.0

MagicOnionのVer 2.1.0を出しました。前回が2月28日なので、3ヶ月ぶりで少し間が空いてしまった感じもありますが、色々良くなったので紹介していきまうまう。

StramingHubClientでメッセージが詰まるバグの修正

いきなり致命的な話なんですが、StreamingHubClientが1フレにつき1メッセージしか送信されないという、しょうもないバグが存在していました。このバグの原因が面白くて(?)、元はこんな感じのコードだったんですよ。

// readerはIAsyncEnumeratorというMoveNext, Currentでデータを取ってくる非同期イテレーター
while (await reader.MoveNext())
{
    var message = reader.Current; // byte[]
    OnBroadcastEvent(message);    // messageは実際にはヘッダ解析したり色々してます
}

gRPCはIAsyncEnumeratorというかっこつけたインターフェイスを採用しているので、awaitでサーバーからデータが届くのを非同期で待機できる。

で、このawaitが問題で、UnityだとUnitySynchronizationContext経由してawaitの先が実行されます。なので安全にメインスレッドでOnBroadcastEvent(これは最終的にユーザーが実装したインターフェイス定義のメソッドが呼ばれる)が呼ばれて嬉しい。のですが、reader自体は別スレッドで動いているので、awaitの度にメインスレッドへの同期を待っているのです。

正確にはUnitySynchronizationContextがawaitの度にメインスレッド上だろうがなんだろうが問答無用で次フレームに叩き込む仕様だから、なのですけれど。

何れにせよ、そんなわけで、サーバーから同一フレームで沢山のデータが送られてきたとしても、クライアント側は1フレームに1メッセージしか捌けないので、どんどん詰まっていくわけです。もちろん、バグです。仕様じゃなく。普通に。バグ。

var syncContext = SynchronizationContext.Current;
 
// ConfigureAwait(false)でSyncContextを外して、このループはずっと別スレッドで動かす
while (await reader.MoveNext().ConfigureAwait(false))
{
    var message = reader.Current;
    if (syncContext != null)
    {
        // 手動でPostする(待たない)
        syncContext.Post(() => OnBroadcastEvent(message));
    }
    else
    {
        OnBroadcastEvent(message);
    }
}

と、いうわけで、こんな具合に半手動でPostするコードに書き換えました(Postでラムダ式のキャプチャが発生する問題がありますがshoganai。正確にはobject stateが渡せるのですが、実際のデータでは複数の値が必要になるのでTupleを作る必要があって、余計なオブジェクトが必要という点で変わらない)。ConfigureAwait(false)をつけないことは意識して、意図してやったこと(同期コンテキストを維持してメインスレッド上でコールバックを飛ばす)だったんですが、そこまで意識しといてこういうバグにつなげちゃうのは完全に甘かった、ということで反省しきりです。

ともあれこれで詰まり問題は大解決です。

MagicOnion.Hosting

最初のサンプルがConsole.ReadLineで待っているコードなのでアレなのですが、普通に実開発ではMagicOnion.Hostingというプロジェクトを使って欲しいと思っています。

// using MagicOnion.Hosting
static async Task Main(string[] args)
{
    await MagicOnionHost.CreateDefaultBuilder()
        .UseMagicOnion(
            new MagicOnionOptions(isReturnExceptionStackTraceInErrorDetail: true),
            new ServerPort("localhost", 12345, ServerCredentials.Insecure))
        .RunConsoleAsync();
}

Hostingとは何かと言うと、Genric Hostという.NET Core時代の基盤フレームワークの上に乗っかっています。これは、こないだ作った MicroBatchFramework – クラウドネイティブ時代のC#バッチフレームワーク と同じ仕組みです。

.NET Generic Hostは、標準的な仕組みとしてロギング/コンフィグ読み込み/DIをサポートしています。これによりコンフィグのマッピング、ロギングなどを標準的な作法でフルサポートしています。

というわけで、何が嬉しいかと言うと、↑の件をフルサポートしてくれていることです。コンフィグとか何をどう読み込めばいいんですかー?という話は、Generic Hostの仕組みを使ってください、というのが答えになります。ドキュメントもMicrosoftのドキュメントサイトで沢山解説されていて、それがそっくりそのまま使えるので、良いことしかない!

また、これによってコンストラクタインジェクションでのDIも使えるようになりました。

static async Task Main(string[] args)
{
    await MagicOnionHost.CreateDefaultBuilder()
        .ConfigureServices((hostContext, services) =>
        {
            // DI, you can register types on this section.
 
            // mapping config json to IOption<MyConfig>
            // requires "Microsoft.Extensions.Options.ConfigurationExtensions" package
            services.Configure<MyConfig>(hostContext.Configuration);
        })
        .RunConsoleAsync();
}
 
public class MyFirstService : ServiceBase<IMyFirstService>, IMyFirstService
{
    IOptions<MyConfig> config;
    ILogger<MyFirstService> logger;
 
    public MyFirstService(IOptions<MyConfig> config, ILogger<MyFirstService> logger)
    {
        this.config = config;
        this.logger = logger;
    }
 
    // ...
}

好きな型を、ConfigureServicesのとこで追加してもらえれば、コンストラクタで設定されたのが入ってきます。

今後

v2のリリース告知から半年経って、かなり注目度が上がっているというのが肌感としてあります。GitHub Starも962まで来ていますし、海外からの問い合わせも国内からも来ていて、盛り上がりありますよ!時代はC#!かもしれない!

というわけかで、来月の6月4日に初のMagicOnion勉強会が開催されます。私も登壇しますので、ぜひぜひ来てください(今はもうキャンセル待ちですが……!)

開発的には、サーバーサイドゲームループ(まだ未サポート)などの追加を挟みつつ、もう少し野心的なものも狙っていますので、是非是非楽しみにしていただければと思います。コードジェネレーターの使い勝手が悪いのも、(MessagePack-CSharpともども)改善の最優先タスクの一つになってますので、なんとかします。

また、フィードバック超大事!なので、ぜひ使ってみて、Twitterでつぶやくなり(捕捉してます)、Qiitaに書いてくれるなり(やったー!)、Issueで報告してもらったりなどなどしてくれると嬉しいです。

CIや実機でUnityのユニットテストを実行してSlackに通知するなどする

前回(?)CircleCIでUnityをテスト/ビルドする、或いは.unitypackageを作るまででは、ユニットテストに関する部分がうまく行ってなくて放置でした。放置でいっかな、と思ってたんですが、改めてユニットテストをCIでがっつり実行したい、というかIL2CPPのテストをがっつしやりたい。という切実な要望が私の中で発生したので(N回目)、改めて取り組んでみました。

さて、オフィシャルな(?)ユニットテストのコマンドラインの実行の口は、Writing and executing tests in Unity Test Runnerの最後の方のRunning from the command lineの節に書いてありました(コマンドライン引数のほうのマニュアルにはリンクすら張ってなかったので気づかなかった……!)。つまり、こんなふうにやればいい、と。

Unity.exe -runTests -testResults C:\temp\results.xml -testPlatform StandaloneWindows64

そうすると、テストが失敗しても正常終了して(?) results.xml に結果が入ってるからそっち見ればOK、と。んー、いや、何か違うような。「Run all in player」で出てくるGUI画面も意味不明だし、Editor上のTest Runnerはいい感じなのだけれど、ビルドしてのテストだとイマイチ感がめっちゃ否めない。

と、いうわけで、なんとなく見えてきたのは、テストはUnity Test Runnerでそのまま書きたいしエディタ上でPlay Modeテストもしたい。それをそのままCIや実機でテストできるように、表示やパイプラインだけをいい具合に処理するビルドを作る何かを用意すればいいんじゃないか、と。

RuntimeUnitTestToolkit v2

ちょうどUnity Test Runnerがイマイチだった頃に作った俺々テストフレームワークがありました。ので、それを元にして、Unity Test RunnerのCLI/GUIのフロントエンドとして機能するようにリニューアルしました。コード的には全面書き換えですね……!

Unity Test RunnerのPlayModeで動くテストがあれば、それだけで他に何もする必要はありません。例えばこんなやつがあるとして

image

メニューのほうで適当にターゲットフレームワークとかIL2CPPがどうのとかを設定してもらって

image

BuildUnitTestを押すと、こんなような結果が得られます。

image

比較的ヒューマンリーダブルなログ!WindowsでもIL2CPPビルドができるようになったのがとっても捗るところで、検証用の小さめプロジェクトなら1分あればコード編集からチェックまで行けるので、リフレクションのキワイ部分をごりごり突いてもなんとかなる!昔のiOSでビルドして動かしてをやってたのは本当に死ぬほど辛かった……。

これはHeadless(CUI)でビルドしたものですが、GUIでのビルドも可能です。

image

イケてる画面かどうかでは微妙ですが、機能的には十二分です。Headlessだと上から下まで全部のテストを実行しちゃいますが、GUIだとピンポイントで実行するテストを選べるので(ただしメソッド単位ではなくクラス単位)、テストプロジェクトが大きくなっている場合はこっちのほうが便利ですね。

さて、Headlessでビルドしたものは、もちろんCIでそのまま実行できます。

image

これはNGが出ている例ですが、ちゃんと真っ赤にCIのパイプラインが止まるようになってます。止まればもちろんCIの通知設定で、Slackでもなんでもどこにでもサクッと飛ばせます。実に正しい普通で普遍なやり方でいいじゃないですか。はい。というわけでやりたかったことが完璧にできてるのでめでたしめでたし。

Linux ContainerとUnity

相変わらずCircleCIで色々トライしているのですが、Linuxコンテナ + Unityでの限界、というかUnityのLinux対応が後手に回ってる影響をくらってビミョーという現実がやっと見えてきました。まず、そもそもにLinux + IL2CPPはまだサポートされてないので、CI上でIL2CPPビルドしたものを実行してテスト、みたいなのはその時点でできない。残念。しゃーないのでWindows + IL2CPPビルドを作って、実行だけ手元でやるのでもいっか、と思ったらそもそもLinuxでIL2CPPビルドができない。なるほど、そりゃそうか、って気もしますが悲しみはある。

と、いうわけで、コンテナベースでやるとどうしてもLinuxの上でのパターンが中心になってしまうので、Unityだと結構厳しいところはありますよねえ、という。

さて、CircleCIの場合は(有料プランでは)Mac VMも使えるので、多少コンフィグの書き方も変わってきますが(マシンセットアップ部分が面倒くさくなる!)、動かせなくもないんちゃうんちゃうんといったところです。或いはAzure DevOpsなどを使えばWindowsマシンが使えるので、こちらもUnityのインストールなどのセットアップは必要ですが、安心感はありますね。どちらにせよWindowsでしかビルドできないもの(Hololensとか)もあるので、ちょっとちゃんと考えてみるのはいいのかなあ、と思ってます。

何れにせよ、VMでやるんだったらそりゃ普通にできますよね、という当たり前の結論に戻ってくるのが世の中きびすぃ。とりあえず私的にはIL2CPPビルドが実行できればいいので、Linux + IL2CPP対応をどうかどうか……。

RandomFixtureKit

ユニットテスト用にもう一個、RandomFixtureKitというライブラリを作りました。こちらは .NET Core用とUnity用の両対応です。

なにかというと、オブジェクトにランダムで適当な値を自動で詰め込むという代物です。当然リフレクションの塊で、これのIL2CPP対応に、先のRuntimeUnitTestToolkitが役に立ちました。

APIも単純でFixtureFactory.Createで取り出すだけ。

// get single value
var value = FixtureFactory.Create<Foo>();
 
// get array
var values = FixtureFactory.CreateMany<Bar>();
 
// get temporal value(you can use this values to use invoke target method)
var (x, y, z) = FixtureFactory.Create<(int, string, short)>();

テスト書いていてダミーのデータを延々と書くの面倒くせー、という局面はめっちゃあって、別に賢い名前なんて必要なくて(例えばAddressにはそれっぽい住所、Nameにはそれっぽい人名を入れてくれるとか)、全然ランダム英数でもいいから詰めてくれればそれでいいの!というところにピッタリはまります。

実用的には、私はシリアライザの入れ替えとか(なぜか)よくやるんですが、旧シリアライザと新シリアライザで互換性なくて壊れたりしないように、相互に値を詰めたりとかして、同一の結果が得られることを確認したりします。そのときに、dllをなめて対象になる数百の型を取って、RandomFixtureKitを使って、適当な値を詰めた上で、一致を比較するユニットテストを用意するとかやったりします。

面白い機能としては、ランダムな値ではなくて、エッジケースになり得る値だけを詰めるモードを用意しています。

たとえばintだったらint.MinValue, MaxValue, 0, -1, 1を。コレクションだったらnull, 長さ0, 長さ1, 長さ9の中からランダムで詰める、といったものですね。

こういうキワいデータが入ったときにー、みたいなことは想定しなきゃいけないし、テストも書いておかなきゃなのは分かってるけれど、毎回データ変えて流すのクソ面倒くさいんですよね(私はシリアライザを(なぜか)よく書くので、本当にこういうデータをいっぱい用意する必要が実際ある)。ので、CreateManyで1000個ぐらい作って流し込んでチェックすれば、多少はケースが埋まった状態になるでしょうというあれそれです。使ってみると意外と便利ですよ。

ところで

ゴールデンウィークの最終日なのですが、ほとんど何もやってない!始まる前は、MessagePack-CSharpやMagicOnionのタスクを潰しつつ、Pure C#のHTTP/2 Clientを作ってMagicOnionを強化するぜ、とか息巻いていたのですが全然できてない。副産物というか横道にそれたユニットテスト関連を仕上げて終わりとか、なんと虚しい……。

できなかった理由の半分はSwitchでCelesteを遊び始めたらめちゃくちゃハマって延々とやり続けちゃったせいなのですが、まぁそれはそれで面白いゲームをたっぷり楽しめたということで有意義なのでよしということにしておきます。

MagicOnionは6月4日に勉強会をやります。というわけで、やる気もかなりあるし、アップデートネタも溜まっているんですが、実際にアップデートはできてないので(Issueのヘンジはちゃんとやってます!)、GWでガッと手を入れておきたかったんですが、うーん、まぁ明けてからやりまうす。色々良い感じになっていると思います。いやほんと。

True Cloud Native Batch Workflow for .NET with MicroBatchFramework

AWS .NET Developer User Group 勉強会 #1にて、先日リリースしたMicroBatchFrameworkについて、話してきました。

True Cloud Native Batch Workflow for .NET with MicroBatchFramework from Yoshifumi Kawai

タイトルが英語的に怪しいですが、まぁいいでしょう(よくない)

MicroBatchFrameworkの概要については、リリース時にCygames Engineers’ BlogにてMicroBatchFramework – クラウドネイティブ時代のC#バッチフレームワークとして書かせていただきました。そう、最近はそっち(どっち)に書いてしまうのでこっち(あっち)に書かれなくなる傾向が!リポジトリの置き場としても、Cysharpオーガナイゼーション中心になってきています。これは会社としてメンテナンス体制とかもしっかり整えていくぞ、の現れなので基本的にはいいことです。

ちなみにCysharp、ページ下段にお問い合わせフォームが(ついに)付きました。興味ある方は応募していただいてもよろしくてよ?ビジネスのお問い合わせも歓迎です。別にゲームに限らずで.NET Coreの支援とかでもいいですよ。ただしオールドレガシーWindows案件はやりません。

クラウドネイティブ

これはセッションで口頭で言いましたが、バズワードだから付けてます。という側面は大いにあります。世の中マーケティングなのでしょーがないね。そもそも私はそういうのに乗っかるの、好きです。

そんな中身のないクラウドネイティブですが(真面目な定義はCNCFのDefinitionにちゃんとあります)、まぁコンテナ化です。ベンダー中立な。というのをコンテナ化ビリティの高さという表現に落としました。.NET Coreは結構いい線言ってると思いますよ。実際。

さて、そんなクラウドネイティブなふいんきのところでの、理想のバッチ処理ってなんやねん。というのを考えて、逆算でアプリケーション側で埋めるべきものを埋めるために作ったのがMicroBatchFrameworkです。インフラ側の欠けてるところはそのうちクラウド事業者が埋めてくれるか、現状でも全然実用レベルで回避はどうとでもなるでしょう。

私としてはC#が快適にかければなんだっていいんですが、なんだっていいというだけではなくC#としての自由の追求に関しては相当ラディカルなのですが、でも、それって割とクラウドネイティブの定義(ちゃんとしたほうの)通りなんですよね。別にコンテナに夢見てるわけじゃなくて、意外と堅実に正しく定義どおりのことやってるわけです。まー、FaaSのオーケストレーターは私の理想からベクトル真逆だし、FaaSのランタイムの重さ(実行が遅いという意味ではなくてシステムとしてのヘヴィさ)も受け入れ難いんで、世の中の正しい進化について正面から向かい合うのが結局一番ということで。

ところでMicroBatchFrameworkのウェブホスティング機能(MicroBatchFramework.WebHosting)はSwaggerによる実行可能なドキュメント生成、のほかに、HTTPをトリガーにする待ち受けという側面もあります。GCP Cloud Runの実行のためにはそういうの必要ですからね。毎回コンテナ起動みたいな夢見たモデルだけじゃなくて、割とちゃんと現実に即して機能は用意してます。意外と。割とちゃんと。そもそも、その辺は実用主義なので。

MicroBatchFrameworkはいい具合のバランス感覚で作れていると思うので、実際良いと思います。というわけで、是非試していただければですね。

CircleCIでUnityをテスト/ビルドする、或いは.unitypackageを作るまで

死ぬほどお久しぶりです!別にインターネット的には沈黙してるわけじゃなくTwitterにもいるし、会社(Cysharp)関連で露出あるかもないかもというわけで、決して沈黙していたわけでもないはずですが、しかしブログは完全に放置していました、あらあら。

C#的にも色々やっていて、CloudStructuresのv2を@xin9leさんとともにリリースしたり、多分、今日に詳細を書くつもりですがMicroBatchFrameworkというライブラリをリリースしたり、Ulidというライブラリをリリースしてたり、まぁ色々やってます。ちゃんと。実際。今月はそのMicroBatchFramework関連で、AWS .NET Developer User Group 勉強会 #1に登壇しますし。リブートしたMagicOnionも来月勉強会開催予定だったりで、めっちゃやる気です。

さて、そんなやる気に満ち溢れている私なのですが(実際Cysharpもいい感じに動き出せているので!お問い合わせフォームないけどお問い合わせ絶賛募集中!)、ブログは放置。よくないね。というわけで表題の件について。

目的と目標

CIの有効性について未だに言う必要なんてなにもないわけですが、しかし、.unitypackageを手作業で作っていたのです。今まで。私は。UniRxとかMessagePack-CSharpの。そして死ぬほど面倒くさいがゆえに更新もリリースも億劫になるという泥沼にハマったのです。やる気が満ち溢れている時は手作業でもやれるけれど、やる気が低下している時でも継続してリリースできなければならないし、そのためにCIはきっちりセットアップしておかなければならないのです。という真理にようやく至りました。なんで今さらなのかというと、私がアプリケーション書くマンであることと、CIとかそういうのは全部、部下に丸投げして自分は一切手を付けてこなかったマンだからです。しかし会社のこともあるので、いい加減にそれで済まなくなってきたので(今更やっとようやく)真面目に勉強しだしたのですね……!

で、CIにはCircleCIを使います。なんでCircleCIなのかというと、一つはUnity Cloud Buildだとunitypackageを作れない(多分)というのが一つ。もう一つは、私が.NET CoreのCIもCircleCIに寄せているので、統一して扱えるといいよねというところです。また、Linuxの他にMacでのビルドもできるので(有料プラン)、iOSに、とかも可能になってくるかもしれませんしね。あと、単純にCircleCIが昨今のCIサービスで王者なので、長いものに巻かれろ理論でもある。でも私自身も最近使っていてかなり気に入ってるので、実際良いかと良いかと。コンテナベースで記述するのがとても小気味よいわけです、モダンっぽいし。

ゴールは

  • リポジトリの一部ソース郡から.unitypackageを作る
  • EditorでUnitTestを行う
  • IL2CPP/Windowsでビルドする(↑のUnitTestのIL2CPP版を吐く)

となります。普通はAndroidやiOSビルドがしたいって話だと思うのですが、私はライブラリAuthorなので、まずそっちの要求のほうが先ということで(そのうちやりたいですけどね!)。Editorテストだけじゃなくて、IL2CPPで動作するか不安度もあるので、そっちのexeも吐ければ嬉しい。できればIL2CPPビルドのものも、ヘッドレスで起動して結果レポーティングまでやれればいいん&ちょっと作りこめばそこまで行けそうですが、とりあえずのゴールはビルドして生成物を保存するところまでにしておきましょう。そこまで書いてると記事長くなるし。

認証を通してUnityをCircleCI上で動かす

CircleCIということでコンテナで動かすんですが、まぁUnityのイメージを持ってきてbatchmodeで起動して成果を取り出すという、それだけの話です。適当にUnityのコマンドライン引数とにらめっこすれば良い、と。

コンテナイメージに関しては、幸い誰か(gablerouxさん)がgableroux/unity3d/tagsに公開してくれていて、綺麗にタグを振ってくれています。コンテナの良いところっていっぱいあると思いますが、コンテナレジストリが良い具合に抽象化されたファイル置き場として機能するのも素敵なとこですねえ。また、こうして公開してくれていれば、社内CIのUnityインストール管理とかしないで済むのも良いところです。大変よろしい。

で、Unityの実態は /opt/Unity/Editor/Unity にあるので、それを適当に -batchmode で叩けばいいんでしょって話ですが、しかし最大の関門はライセンス認証。それに関してはイメージを公開してくれているgablerouxさんのGabLeRoux/unity3d-ci-exampleや、そして日本語ではCircleCIでUnityのTest&Buildを雰囲気理解で走らせたに、手取り足取り乗っているので、基本的にはその通りに動かせば大丈夫です。

ただ、ちょっと情報が古いっぽくて、今のUnityだともう少し手順を簡単にできるので(というのを試行錯誤してたら苦戦してしまった!)、少しシンプルになったものを以下に載せます。

まず、ローカル上でライセンスファイルを作る必要があります。これはdockerイメージ上で行います。また、ここで使うイメージはCIで実際に使うイメージと同じバージョンでなければなりません。バージョン変わったらライセンス作り直しってことですね、しょーがない。そのうちここも自動化したくなるかもですが、今は手動でやりましょう。

docker run -it gableroux/unity3d:2018.3.11f1 bash
cd /opt/Unity/Editor
./Unity -quit -batchmode -nographics -logFile -createManualActivationFile
cat Unity_v2018.3.11f1.alf

イメージを落としてきて、 -quit -batchmode -nographics -logFile -createManualActivationFile でUnityを叩くと Unity_v***.alf という中身はXMLの、ライセンスファイルの元(まだuseridもpasswordも入力してないので、テンプレみたいなものです)が生成されます。こいつを、とりあえず手元(ホスト側)に持ってきます。docker cpでコンテナ->ホストにファイルを移動させてもいいんですが、まぁ1ファイルだけなのでcatしてコピペして適当に保存でもOK。

次にhttps://license.unity3d.com/manualを開いて、上記のalfファイルを上げると Unity_v2018.x.ulf ファイルがもらえます。これが実体です。生成過程でUnityのサイトにログインしているはずで、そのuserid/passwordが元になって、ライセンスファイルの実体が生成されました。中身はXMLです。

で、これは大事な情報なのでCircleCI上のEnvironment Variablesで秘匿しよう、という話になるんですが、改行の入った長いXMLなので、そのまんま中身をコピペるとファイルが、たいていどこか壊れて認証通らなくなります(散々通らないでなんでかなぁ、と悩みました!)。とはいえファイルそのものをリポジトリに上げるのはよろしくないので、CircleCIでUnityのTest&Buildを雰囲気理解で走らせたにあるとおり、暗号化したものをリポジトリに追加して、Environment VariablesにはKeyを追加しましょう。

openssl aes-256-cbc -e -in ./Unity_v2018.x.ulf -out ./Unity_v2018.x.ulf-cipher -k ${CIPHER_KEY}

${CIPHER_KEY}は、適当な文字列に置き換えてもらって、そしてこれをCircleCI上のEnvironment Variablesにも設定します。ファイルの置き場所は、とりあえず私は .circleci/Unity_v2018.x.ulf-cipher に置きました、CIでしか使わないものなので。

またはマルチラインキーの場合は base64を使うことが推奨されているようです => Encoding Multi-Line Environment Variables。こちらのほうが良さそうですね。

あとは .circleci/config.ymlを書くだけ、ということで、最小の構成はこんな感じになります。

version: 2.1
executors:
  unity:
    docker:
      # https://hub.docker.com/r/gableroux/unity3d/tags
      - image: gableroux/unity3d:2018.3.11f1
jobs:
  build-test:
    executor: unity
    steps:
      - checkout
      - run: openssl aes-256-cbc -d -in .circleci/Unity_v2018.x.ulf-cipher -k ${CIPHER_KEY} >> .circleci/Unity_v2018.x.ulf
      - run: /opt/Unity/Editor/Unity -quit -batchmode -nographics -silent-crashes -logFile -manualLicenseFile .circleci/Unity_v2018.x.ulf || exit 0
workflows:
  version: 2
  build:
    jobs:
      - build-test

-nographicsにすることでそのまま叩けるのと、-manualLicenseFileでライセンスファイルを渡してやるだけです。 認証する際の || exit 0 がお洒落ポイントで、認証が正常に済んでもexit code 1が返ってくるという謎仕様なので、とりあえずこのステップは強制的に正常終了扱いにしてあげることで、なんとかなります。なんか変ですが、まぁそんなものです。世の中。

まぁしかしGabLeRoux/unity3d-ci-exampleの(無駄に)複雑な例に比べれば随分すっきりしたのではないでしょうか。いやまぁ、Unityのイメージ作ってもらってるので感謝ではあるのですけれど、しかしサンプルが複雑なのは頂けないかなあ。私はサンプルは限りなくシンプルにすべき主義者なので。

.unitypackageを作る

バッチモードでは -executeMethod により特定のstatic methodが叩けるので、それでunitypackageを作るコードを用意します。 今回は Editor/PackageExport.cs に以下のようなファイルを。

using System;
using System.IO;
using System.Linq;
using UnityEditor;
using UnityEngine;
 
// namespaceがあると動かなさそうなので、グローバル名前空間に置く
public static class PackageExport
{
    // メソッドはstaticでなければならない
    [MenuItem("Tools/Export Unitypackage")]
    public static void Export()
    {
        // configure
        var root = "Scripts/CISample";
        var exportPath = "./CISample.unitypackage";
 
        var path = Path.Combine(Application.dataPath, root);
        var assets = Directory.EnumerateFiles(path, "*", SearchOption.AllDirectories)
            .Where(x => Path.GetExtension(x) == ".cs")
            .Select(x => "Assets" + x.Replace(Application.dataPath, "").Replace(@"\", "/"))
            .ToArray();
 
        UnityEngine.Debug.Log("Export below files" + Environment.NewLine + string.Join(Environment.NewLine, assets));
 
        AssetDatabase.ExportPackage(
            assets,
            exportPath,
            ExportPackageOptions.Default);
 
        UnityEngine.Debug.Log("Export complete: " + Path.GetFullPath(exportPath));
    }
}

ちょっとassetsを取るところが長くなってしまっているのですが、.cs以外をフィルタするコードを入れています。たまに割と入れたくないものが混ざっていたりするので。あとは、CIではライセンス認証のあとに、これを叩くコマンドと、artifactに保存するコマンドを載せれば良いでしょう。

version: 2.1
executors:
  unity:
    docker:
      # https://hub.docker.com/r/gableroux/unity3d/tags
      - image: gableroux/unity3d:2018.3.11f1
jobs:
  build-test:
    executor: unity
    steps:
      - checkout
      - run: openssl aes-256-cbc -d -in .circleci/Unity_v2018.x.ulf-cipher -k ${CIPHER_KEY} >> .circleci/Unity_v2018.x.ulf
      - run: /opt/Unity/Editor/Unity -quit -batchmode -nographics -silent-crashes -logFile -manualLicenseFile .circleci/Unity_v2018.x.ulf || exit 0
      - run: /opt/Unity/Editor/Unity -quit -batchmode -nographics -silent-crashes -noUpm -logFile -projectPath . -executeMethod PackageExport.Export
      - store_artifacts:
          path: ./CISample.unitypackage
          destination: ./CISample.unitypackage
workflows:
  version: 2
  build:
    jobs:
      - build-test

完璧です!

コマンドに関しては普通にWindowsのUnity.exeで試してから挑むのがいいわけですが、一つWindowsには難点があって、ログが標準出力ではなく %USERPROFILE%\AppData\Local\Unity\Editor\Editor.log にしか吐かれないということです。というわけで、Editor.logを開いてにらめっこしながらコマンドを作り込みましょう。めんどくせ。

EditorでUnitTestを行う

基本的に -runEditorTests をつけるだけなのですが、注意点としては -quit は外しましょう。ついてると正常に動きません(はまった)。

version: 2.1
executors:
  unity:
    docker:
      # https://hub.docker.com/r/gableroux/unity3d/tags
      - image: gableroux/unity3d:2018.3.11f1
jobs:
  build-test:
    executor: unity
    steps:
      - checkout
      - run: openssl aes-256-cbc -d -in .circleci/Unity_v2018.x.ulf-cipher -k ${CIPHER_KEY} >> .circleci/Unity_v2018.x.ulf
      - run: /opt/Unity/Editor/Unity -quit -batchmode -nographics -silent-crashes -logFile -manualLicenseFile .circleci/Unity_v2018.x.ulf || exit 0
 
      - run: /opt/Unity/Editor/Unity -quit -batchmode -nographics -silent-crashes -noUpm -logFile -projectPath . -executeMethod PackageExport.Export
      - store_artifacts:
          path: ./CISample.unitypackage
          destination: ./CISample.unitypackage
 
      - run: /opt/Unity/Editor/Unity -batchmode -nographics -silent-crashes -noUpm -logFile -projectPath . -runEditorTests -editorTestsResultFile ./test-results/results.xml
      - store_test_results:
          path: test_results
workflows:
  version: 2
  build:
    jobs:
      - build-test

editorTestsResultFile で指定し、store_test_resultsに格納することでCircleCI上でテスト結果を見ることができます。

と、思ったんですが、なんかテスト周りは全体的にうまく動かせてないんで後でまた調べて修正します……。或いは教えてくださいです。

IL2CPP/Windowsでビルドする

なぜWindowsかというと、私がWindowsを使っているからというだけなので、その他のビルドが欲しい場合はそれぞれのビルドをしてあげると良いんじゃないかと思います!

いい加減コンフィグも長くなってきましたが、-buildWindows64Playerでビルドして、zipで固めてぽんということです。

version: 2.1
executors:
  unity:
    docker:
      # https://hub.docker.com/r/gableroux/unity3d/tags
      - image: gableroux/unity3d:2018.3.11f1
jobs:
  build-test:
    executor: unity
    steps:
      - checkout
      - run: openssl aes-256-cbc -d -in .circleci/Unity_v2018.x.ulf-cipher -k ${CIPHER_KEY} >> .circleci/Unity_v2018.x.ulf
      - run: /opt/Unity/Editor/Unity -quit -batchmode -nographics -silent-crashes -logFile -manualLicenseFile .circleci/Unity_v2018.x.ulf || exit 0
 
      - run: /opt/Unity/Editor/Unity -quit -batchmode -nographics -silent-crashes -noUpm -logFile -projectPath . -executeMethod PackageExport.Export
      - store_artifacts:
          path: ./CISample.unitypackage
          destination: ./CISample.unitypackage
 
      - run: /opt/Unity/Editor/Unity -batchmode -nographics -silent-crashes -noUpm -logFile -projectPath . -runEditorTests -editorTestsResultFile ./test-results/results.xml
      - store_test_results:
          path: test_results
 
      - run: /opt/Unity/Editor/Unity -quit -batchmode -nographics -silent-crashes -noUpm -logFile -projectPath . -buildWindows64Player ./bin-win64/CISample.exe
      - run: apt-get update
      - run: apt-get install zip -y
      - run: zip -r CISampleWin64Binary.zip ./bin-win64
      - store_artifacts:
          path: ./CISampleWin64Binary.zip
          destination: ./CISampleWin64Binary.zip
workflows:
  version: 2
  build:
    jobs:
      - build-test

これで一旦は希望のものは全てできました!

以上な感じが最終結果になります。

CircleCIでUnityビルドはプロダクトで使えるか

今回の例のようなライブラリ程度だと、リソースもほとんどないしリポジトリも全然小さいんでいいんですが、実プロダクトで使えるかというと、どうでしょう。まずリポジトリのサイズの問題で、次にビルド時間の問題で。クソデカい&高級マシンでも焼き上がり1時間は普通とか、そういう世界ですものね。常識的に考えてこれをクラウドでやるのは難しそう。オンプレのCircleCI Enterpriseだったら行けそうな気もしますが、どうでしょうねえ。しかしJenkinsマンやるよりは、こちらのほうが夢があるのと、実際うまくクラスタを組めば、ばかばかコンテナ立ち上げて同時並列でー、というビルドキュー長蛇列で待ちぼうけも軽減できたりで、良い未来は感じます。試してみたさはあります、あまりJenkinsに戻りたくもないし。

一回構築してみれば、ymlもそこそこシンプルだし、(ライセンス認証以外は)ymlコピペで済むので、Unity Cloud Build使わなくてもいいかなー、色々自由にできるし。っていうのはあります。というわけで、是非一緒にUnityでCircleCI道を突き進んでみましょう:) 今回はAndroidビルドやiOSビルドという面倒くさいところには一切手を付けてませんが、まぁほとんどビルドできてるわけで、やりゃあできるでしょう。いや、でもiOSとか死ぬほど面倒くさ(そう)なので、そのへんよしなにやってくれつつマシンパワーもそこそこ用意してくれるUnity Cloud Buildは偉い。

ところでこのブログ、ymlのシンタックスハイライトがない模様。やべー。このブログのメンテこそが一番最重要な気がしてきた。

Comment (1)

スーギ・ノウコ自治区 : (11/30 16:35)

Unity2018.4.9f1で確認しましたが-executeMethodの引数に名前空間.クラス名.メソッド名を渡しても正常に動作することをGitHub ActionsのLinux環境において確認いたしました。

Trackback(0)
Write Comment

Prev |

Search/Archive

Category

Profile


Yoshifumi Kawai
Microsoft MVP for Developer Technologies(C#)

April 2011
|
July 2020

Twitter:@neuecc
GitHub:neuecc
ils@neue.cc