Bot framework v4 での入門Tips。2018年11月（Microsoft.Bot.Builder V4.1.5 時点）での情報です。 文字が潰れていたのでフォントを変更してアップロードしなおしました。

1. Bot Framework V4 開発 Tips 2018-11
V4 開発で最初に知っておきたいポイント
2018-11
Cogbot #18

2. ABOUT ME
横浜 篤
よこはま あつし
C#, ASP.NET Core, Azure, Cognitive Services, Bot Framework….
開発者募集しています♪
C#er
Cogbot
コミュニティ
@BEACH_SIDE
http://beachside.hatenablog.com/
BEACHSIDE BLOG
株式会社アイティーブレーン
Edge Technology and Projects 部
部長

3. 本日のゴール
Bot Framework V4 で開発をする上で把握しておきたいと
(私個人的に）感じたことを共有
2018年11月末時点ノ情報デスWARNING
• Bot Framework V4 をこれから触りたい人向け
• Bot Framework V3 で開発はしてたけど、まだV4触ってない人に向け
• 主に C# 版のお話

4. アジェンダ
1. Bot File の存在
2. Middleware の有効活用
3. Accessor
4. Dialog と Waterfall
5. Adaptive Cards
6. その他

5. 1. Bot File の存在
正しく使い方は…

6. Bot File とは (1)
リソースの管理用ファイル
• 使用する言語やプラットフォームに関係なくリソース管理するために存在
• 格納されている情報の例として、Application Insights のキー情報や Blob
Storage の接続文字列など
• 環境ごと（ローカルホスト、Azure Bot Serviceの本番環境など）のエンドポイントの記載があり、Bot
Emulator で容易にアクセス可能
公式ドキュメント: https://docs.microsoft.com/ja-jp/azure/bot-service/bot-file-basics?view=azure-bot-service-4.0

7. Bot File とは (2)
暗号化 / 複合化
• Azure Bot Service で作成されたソースコードのBot File は、キーや接続文字
列は、暗号化されて格納されている。暗号化キー（BotFileSecret）は、Azure Bot
Service（Web Apps）のアプリケーション設定の中にある
• 暗号化された情報を見るには、Bot Emulator でみる、または、”MSBot
Command Line tool” で複合化を行う
• ”MSBot Command Line tool” で複合化して編集した後、再び暗号化する
には新規に暗号化キーを生成する必要がある
公式ドキュメント: https://github.com/Microsoft/botbuilder-tools/tree/master/packages/MSBot

8. セキュアな情報はどこに保存すべきか
キー情報の保存先は複数存在
• Bot File
• appsettings.json または、appsettigs.{ environmentName }.json
• UserSecrets （ローカル開発用）
• Azure Bot Service（Web Apps）のアプリケーション設定
• Azure の Key Vault

9. プログラム実行時の躓きポイント(1)
Bot File のファイル名にまつわるカオス
初期値が色々な箇所で設定されている
設定されている箇所 ファイル名
Azure Bot Service で作成されたソースコードの Bot File のファイル名 {プロジェクト名}.bot
Azure Bot Service で作成されたソースコードの appsettings 内の値 コメントの文字列
VS 2017 でプロジェクトテンプレートからソースコードを作成した場合のファイル名 BotConfiguration.bot
VS 2017 でプロジェクトテンプレートからソースコードを作成した場合のappsettings 内の値 BotConfiguration.bot
ソースコード内（Startup.cs）で、環境変数/設定ファイルから値が取得できなかった時のデフォ
ルト値
BotConfiguration.bot
Azure Bot Service（Web Apps）の「アプリケーション設定」でのデフォルト値 {プロジェクト名}.bot

10. プログラム実行時の躓きポイント(2)
Bot File の複合キーを取得してローカルに保存が必要
• Azure Bot Serviceで生成されたソースコードの
場合、 Azure Bot Service (Web Apps) のア
プリケーション設定で、「BotFileSecret」の値を
取得しappsetting.json 等へ設定が必要
• 「BotFileSecret」の値を appsettings に書くの
はナンセンス…ローカルならUserSecrets に保存
がベター。

11. Bot File を見てみる
MSBot CLI で複合化 / 暗号化
Emulator で確認
DEMO

12. Bot File に情報を保存する際に気にしておきたいこと
変更があると BotFileSecret の値が新しくなる
• UserSecrets に保存してる場合、開発者全員更新が必要
• 環境が複数ある場合（Dev/Staging/Production など）、すべての環境で
更新が必要
• 実運用中なら、更新するためのオペレーションが面倒なことになりかねない

13. 2. Middleware の有効活用
やつらはライブラリ内に既にいる

14. Middleware を介した処理フロー

15. 会話ログの保存
TranscriptLoggerMiddleware
• Startup.cs に組み込むだけで、会話のログを保存してくれる
• ログの内容は、Bot Emulator で見れる Json の内容と同様
• 詳細はこちら:
https://github.com/Microsoft/botbuilder-dotnet/blob/master/libraries/Microsoft.Bot.Builder/TranscriptLoggerMiddleware.cs

16. State の保存
AutoSaveStateMiddleware
• Startup.cs に組み込むだけで、State を保存してくれる
• 詳細はこちら:
https://github.com/Microsoft/botbuilder-dotnet/blob/master/libraries/Microsoft.Bot.Builder/AutoSaveStateMiddleware.cs

17. Typing の表示
ShowTypingMiddleware
• Startup.cs に組み込むだけで、デフォルトで0.5秒以上 の delay があると
Typing を表示してくれる
• 詳細はこちら:
https://github.com/Microsoft/botbuilder-dotnet/blob/master/libraries/Microsoft.Bot.Builder/ShowTypingMiddleware.cs

18. Middleware の実装
DEMO

19. 3. Accessor
State の保存はすべてここから

20. Bot Framework におけるステート管理
ステート管理の必要性
• ステートがなければ、一問一答しかできない
• ステートを持つことで会話フローを実現
ステートの種類
• User State
ユーザーの個々の情報（名前とか）を管理し、会話に活かす
• Conversation State / Private Conversation State
直前の会話で何を答えたか、会話フローの中でどの会話をしているかなど

21. Accessor という概念を利用したステートの管理
property accessors の利用でプログラムが汎用化
• 独自のステートのシリアライズ/デシリアライズ
• キャッシュへの読み書き、データストアへの保存
• 公式ドキュメントで概要を確認して利用しましょう
https://docs.microsoft.com/ja-jp/azure/bot-service/bot-builder-concept-state?view=azure-bot-service-4.0
• 実装もほぼ固定のパターンなのでサンプルを参照しましょう
https://docs.microsoft.com/ja-jp/azure/bot-service/bot-builder-howto-v4-state?view=azure-bot-service-4.0&tabs=csharp

22. 4. Dialog と Waterfall
会話フロー構築のためのオブジェクトの概要

23. ダイアログライブラリの階層
一連の会話の責務単位
1度の会話の単位 一連の会話フローの単位
回答のデータ型に
応じたプロンプト

24. Dialog と Waterfall の棲み分け
Dialog
• 単一または一連の会話フロー単位がベター
• Dialog 間を行き来しやすい（Waterfall だと難しい）
• 再利用可能な Component Dialog として作ると便利
Waterfall
• 会話が一方通行で決まったフローの場合に有用。
• 一方通行ではなく戻るようなフローには不向き（できないことはないが…）

25. 5. Adaptive Cards
これさえあれば何もいらない
とはならないけど….

26. Adaptive Cards
積極的に利用して UI / UX の改善へ
• 公式サイト(https://adaptivecards.io/)でサンプルも充実
• 公式サイトの Web上でデザイン可能
• プログラムで動的な生成も可能

27. その他

28. 公式ドキュメント
日本語ドキュメントは、古い可能性がある
• 2018年9月に V4 が GA したため、まだ翻訳ができていない部分がある（10
月に比べたらだいぶ良くなった）
• 更新日が2018年9月以前のものは、古い可能性高いため、英語版と更新
日を見比べて、必要に応じて英語版を見ましょう
• 古いのを見つけたら…文句を言うのではなくコントリビュートしましょう…

29. Bot Builder tools の存在
開発における便利ツール群
• 公式のサイト（GitHub: https://github.com/Microsoft/botbuilder-tools ）にてどんなものがあるか
チェックしておきましょう。

30. Microsoft App ID
Microsoft App ID には有効期限がある
• Azure Bot Service で自動生成されたID/Passwordは、有効期限が2年間
に設定されている
• 必要に応じて有効期限を設定しましょう。Azure ポータルからの設定・確認方
法２パターンは以下
• Bot Service のリソース > 設定 > Microsoft App ID の欄にある「管理」のリンクをクリック
• Azure Active Directory > アプリ登録（プレビュー） > 対象のアプリのIDを選択

31. Slot 機能でデプロイメントの効率化
Web Apps の Slot 機能で Staging / Production をスワップ運用
• Azure Bot Service とは、Web Apps, Bot Channel Registration, Blob,
Application Insights の集合体
• Web Apps は一つ、その他のリソースを手作業で作成することで Slot 機能を
活用できる
• Web Apps と Bot Channel Registration の紐づけは、 Azure ポータルより
設定
• Bot Channel Registration リソース > 設定 > メッセージングエンドポイント

32. おわりに

33. • ASP.NET Core 化で、モダンなフレームワークに進化
• “開発者にとっては” よりフレームワーク化しやすい構造に
• 人がやりにくい仕事をボットで代替することで、人がよりクリエイ
ティブで楽しいことに集中できる世界を作りましょう
Let’s enjoy Bot Framework V4 !

34. … .. . ..
Happy Coding !!
Cogbot #18