BEACHSIDE BLOG

MicrosoftとかC#を好むレンジャーの個人的メモ

Bot Builder V4 (4.0.1-preview) 開発入門 : C# : 準備編(Azure Bot Service / Microsoft Bot Framework)

2019-10追記: 2018年9月末に GA したバージョン V4.0.7 で、破壊的変更が多かったためこのバージョンと互換の無い部分があります。バージョンにご注意くださいね。

2018年7月時点で Bot Builder v4 は プレビュー中(Microsoft.Bot.Builder.Core v4.0.1-preview)ですので、またがっつり変わる可能性もありますが書いていきましょう♪

Overview

環境

すごーくざっくり雑に書きますが以下です。

  • Visual Studio 2017 エディション不問で最新版!
    BotASP.NET Core でできている、Azureとの連携を将来的にするので、インストール時にワークロード「ASP.NET と Web 開発」「Azure の開発 」は必要なはず。
  • Windows 10 も最新

1-1. 準備

準備として以下2つを行います。

Visual Studio 2017 に プロジェクトのテンプレートをインストール

Visual Studio の Marketplace からインストールしてもよいのですが、あえてVS2017からやりましょう。Update の通知きたときに「これな」って覚えてもらえるように...。

Visual Studio 2017 を起動して、上部のメニューから ツール > 拡張機能と更新プログラム をクリックします。

f:id:beachside:20180718150714p:plain


「変更機能と更新プログラム」ウインドウが表示されます。左ペインで オンライン をクリックし、右側の検索するところに 「Bot Builder V4」 と入力してしまいましょう。「Bot Builder V4 SDK Template for Visual Studio」が表示されるはず。ダウンロードをクリックし、インストールしましょう(一度 VS 2017 を落とすと、インストーラーが起動してインストールが開始するやつです)。

f:id:beachside:20180718121654p:plain

これで、プロジェクトを作成するときに Bot Builder のテンプレートが表示されるようになります。


エミュレーターをインストール

開発するボットは、いわば、ただの WebAPI なので、デバッグするときにクライアントが必要になります。それを担ってくれるのが Bot Emulator になります。

以前(V3)まではローカルデバッグしている Bot とかに接続して、通信している Json の値を見たりできましたが、V4の Emulator からは、そのほかに色々な機能が付き、便利になりました。(詳しくは公式ドキュメントにて

まずはインストールしておきましょう。現時点では、こちらのGitHub のリポジトリーから Download してねって感じです。現時点(4.0.15-alpha)では以下の種類がありますが、Windows であれば、「botframework-emulator-setup-4.0.15-alpha.exe」でよいでしょう。

f:id:beachside:20180718121704p:plain


インストールし終わったら、Windows のメニューで Bot と入力すると、「Bot Framework Emulator (V4 PREVIEW)」が表示されるでしょうか。迷子にならないように「スタートにピン留めする」をしておくとよいかもですね。

f:id:beachside:20180718122254p:plain

(私の Windows のメニューは左に配置してるのです....)
デスクトップにアイコンってできましたっけ?(インストールは昔にしたから記憶がない...)個人的な趣味の話になりますが、私はデスクトップに何かのアイコンがあるのが嫌なので削除してます....


これで準備完了。ちょっと動かしてみましょう。

1-2. Echo Bot の作成とデバッグ

プロジェクトの作成

Visual Studio 2017 でプロジェクトを作成していきましょう。スタートページが開いている場合は、真ん中下あたりの「新しいプロジェクトの作成」をクリックしましょう(開いてなければ、左上の ファイル > 新規作成 > プロジェクト というクソ面倒な手順でプロジェクトを作成します)。

f:id:beachside:20180718121724p:plain


左ペインで「Bot Framework」がありますでしょうか?なけば、最初に行った「Visual Studio 2017 に プロジェクトのテンプレートをインストール」の作業に問題がありますのでそちらを確認しましょう。

Bot Builder Echo Bot V4」を選択します("V4" とついていなければ V3の可能性があり、全く別物です)。名前やソリューション名も適当につけて(ここでは「EchoV4Sample」とつけました)、 OK をクリックしましょう。プロジェクトが作成されます。

f:id:beachside:20180718121734p:plain


プロジェクトができたらすぐにデバッグして Echo を返すボットが実行できますが、ちょっとだけ解説しておきましょう。

プチ解説:Echo Bot のプロジェクト構成

プロジェクト自体は、ASP.NET Core 2.0 でできてます。(つまりは 2.1 に今後あがるでしょうね...)

つまりは、主に Startup.cs の中で ASP.NET Core あるあるの Middleware とか設定をするってやつですね。

ASP.NET Core の仕組みも多少なりとも理解があるとよいかと思いますが、まぁなくても多少は生きていけるでしょう(と勝手に思っています)。

Bot Builder が ASP.NET Core の Middleware の設定としてどんなことをしているかというと、Startup.csConfigureServices メソッドでの各種設定により、Bot のエンドポイント api/messages への POST があった時に、EchoBot クラス の OnTurn メソッドが呼ばれるようにしてくれています。

もうちょっと詳しくは、以前のブログでざっくりまとめました。自分用なので雑に書いてるので意味不明かもしれませんが、興味のある方はご参照ください♪

プチ解説:EchoBot クラス

Startup.csConfigureServices メソッドでのデフォルトのコードのおかげで、なんだかんだの設定はせずとも、EchoBot クラスの OnTurn メソッドが呼ばれます。

SDK の実装の進捗を見るかぎり、そのうちメソッド名が OnTurnAsync に変わるはずです。)

あとは、以前のV3の Controller でやっていたのと流れは一緒です。会話やユーザーの状態が格納された ITurnContext インターフェースの引数 context からデータを読み書きしたり、ユーザーに会話を返します。

プロジェクトテンプレートから作成されたコードでは、会話するごとにカウントをアップしながらエコーするというコードになってますね。デバッグして動作を確認しつつ、Emulator を使ってみましょう。

Debug with Emulator

プロジェクトのフォルダ直下に <プロジェクト名>.bot (今回だと「EchoV4Sample.bot」)というファイルが生成されます。プロジェクトを VS2017 で開くとソリューションエクスプローラーをみても表示されていますね。
これは、Emulator からデバッグ実行中の Web API に接続するのを楽にしてくれる構成ファイルのようなものです。ファイルを開くとエンドポイントとかが書かrていますね。

まずVS 2017 でこのプロジェクトをデバッグしてみましょう。F5 キーをクリック(または 画面上部のデバッグのボタンをポチ)しましょう。

f:id:beachside:20180718121744p:plain


余談ですが、デフォルトでは IIS Express でのデバッグですね。そんな重いもん使わず Kestrel じゃーって変更する場合、デバッグ時のポート番号がかわりますので「EchoV4Sample.bot」の中に書かれている endpoint の値も変更しておきましょう(これが「は?」という場合は素直に IIS Expressでデバッグしましょう)。


先ほどインストールしたエミュレーターを起動しましょう。Botに接続するには、エンドポイントを直接入力するか .bot のファイルを読み込むかですがので、Welcome タブの Open Bot をクリックし、現在いじってるボットのプロジェクトの .bot ファイル(今回の私のだと「EchoV4Sample.bot」)を選択します。

(画面上部のメニュー File > Open Bot でも開けます)

f:id:beachside:20180718121752p:plain


.bot ファイルどこにあんねん?となった場合は、プロジェクト名を右クリックして「エクスプローラーでフォルダーを開く」をクリックすると、パスがわかるでしょう。

f:id:beachside:20180718121801p:plain


ボットに接続できたら、適当に会話するとエコーされますね。ソースコードブレークポイントを置きながら確認をしつつ、レスポンスのJSONをチェックするってのもできますね。そこはいままで通りって感じ。

f:id:beachside:20180718121811p:plain


終わりに

ユーザーからメッセージを受け取ってから返すまでの部分はサクッとできてしまいますので、ボットの会話ロジックの開発に集中することができますね。

今回はここまでとします。次回は、Azure のデプロイと Channel への登録とかを整理します。

beachside.hatenablog.com

そのあとは開発あるあるの基本的な部分を整理できたらなーと思っています。