宣言型アダプティブ ダイアログを使用してボットを作成するCreate a bot using declarative adaptive dialogs  

適用対象: 対象 SDK v4 対象外 SDK v3 APPLIES TO: yesSDK v4 no SDK v3

この記事では、宣言型の方法を使用してアダプティブ ダイアログを組み込んだボットを作成する方法について説明します。This article shows how to create a bot that incorporates an Adaptive dialog using the declarative approach.

前提条件Prerequisites

宣言型アダプティブ ダイアログをボットに追加するための準備手順Preliminary steps to add a declarative adaptive dialog to a bot

ボットで宣言型ダイアログを読み込んで使用するには、次の手順を実行する必要があります。You must follow these steps to load and use a declarative dialog in a bot.

  1. すべての Bot Builder NuGet パッケージをバージョン 4.9.x に更新します。Update all Bot Builder NuGet packages to version 4.9.x.
  2. 宣言ファイルを作成します。Create the declarative files.
  3. 必要なパッケージと参照をボット プロジェクトに追加します。Add the required packages and references to your bot project.
  4. アダプティブ ダイアログ用の Bot Framework の宣言コンポーネントを登録します。Register the Bot Framework's declarative components for adaptive dialogs.
  5. ボット コードのダイアログ マネージャーを使用して、ターンごとにルート ダイアログを開始または続行します。Use a dialog manager in the bot code to start or continue the root dialog each turn.
  6. ボット コードでリソース エクスプローラーを作成して、宣言のリソースを読み込みます。Create a resource explorer in the bot code to load the declarative resources.

サンプルについてAbout the sample

このサンプルは Bot Framework アダプティブ ダイアログの宣言型エコー ボットであり、ユーザーからの入力を受け入れてエコー バックする、宣言的に定義されたアダプティブ ダイアログの使用方法を示しています。This sample, the Bot Framework Adaptive Dialog declarative Echo bot, demonstrates using a declaratively-defined adaptive dialog that accepts input from the user and echoes it back.

宣言ファイルを作成するCreate the declarative files

宣言型ダイアログのファイルは、ダイアログの要素が宣言された、言語に依存しない JSON ファイルです。つまり、ボットの作成に使用する言語に関係なく同じです。Declarative dialog files are language-agnostic JSON files that declare the elements of a dialog, meaning that they are the same regardless which language you use to create your bot. 通常は、.dialog の拡張子です。They typically have an extension of .dialog. EchoBot サンプルには、UnknownIntent イベントを処理するトリガーを備えた 1 つのアダプティブ ダイアログのみが含まれています。これが起動すると、次のような内容がエコーされるメッセージがユーザーに送信されます。 "You said '${turn.activity.text}'" (あなたは '${turn.activity.text}' と言いました)The EchoBot sample only contains one adaptive dialog with a trigger to handle the UnknownIntent event, which when it fires it sends a message to the user that echos what they said: "You said '${turn.activity.text}'".

ヒント

Bot Framework Composer は、開発者や複数の学問分野にまたがるチームがボットの構築に使用できる統合開発ツールです。Bot Framework Composer is an integrated development tool that developers and multi-disciplinary teams can use to build bots. Bot Framework Composer によって作成されるボットは、宣言型の方法を使用して構築されます。The bots created by Bot Framework Composer are built using the declarative approach.

EchoBot サンプルの宣言ファイル (C# | JavaScript):The declarative file (C# | JavaScript) for the EchoBot sample:

{
  "$schema": "../app.schema",
  "$kind": "Microsoft.AdaptiveDialog",
  "triggers": [
    {
      "$kind": "Microsoft.OnUnknownIntent",
      "actions": [
        {
          "$kind": "Microsoft.SendActivity",
          "activity":  "You said '${turn.activity.text}'"
        }
      ]
    }
  ]
}

注意

宣言ファイルは dialogs という名前のサブフォルダーに保存することをお勧めしますが、任意の場所に配置できます。It is generally a good practice to keep your declarative files in a sub-folder named dialogs, however they can be anywhere. これらは、ResourceExplorer.GetResources() メソッドを使用してボットに読み込みます。You load them into your bot using the ResourceExplorer.GetResources() method.

スキーマ ファイルの作成Creating the schema file

"$schema キーワードから参照されるスキーマ ファイルには、ボットによって使用されるすべてのコンポーネントのスキーマが含まれています。The schema file referenced by the "$schema keyword contains the schemas of all the components that are consumed by your bot. .dialog ファイルで参照される "$schema キーワードとスキーマ ファイルの詳細については、「アダプティブ ダイアログでの宣言型アセットの使用」の記事を参照してください。For information on the "$schema keyword and schema file referenced in .dialog files, see the Using declarative assets in adaptive dialogs article.

.dialog ファイルで参照されるスキーマ ファイルを作成するには、Bot Framework コマンドライン インターフェイス (BF CLI) が必要です。To create the schema file referenced in the .dialog file you need the Bot Framework Command-Line Interface (BF CLI). これをまだインストールしていない場合は、コマンド ラインから BF CLI をインストールできます。If you do not already have this installed, you can install the BF CLI from the command line:

npm i -g @microsoft/botframework-cli

コマンド ラインで Bot Framework コマンド ライン インターフェイス (BF CLI) を使用して、プロジェクトのルート ディレクトリから bf dialog:merge <filename.csproj> を実行します。Using the Bot Framework Command-Line Interface (BF CLI) in the command line, from the root directory of your project run bf dialog:merge <filename.csproj>:

bf dialog:merge EchoBot.csproj

これにより、コマンドが実行されたディレクトリに App.Schema という名前のファイルが作成されます。This creates a file named App.Schema in the same directory that the command was executed in.

ヒント

"$schema キーワードがないか、無効なファイルまたは存在しないファイルを指している場合、警告やエラーは発生せず、実行時にボットの機能には影響しませんが、有効な App.Schema ファイルが必要です。ただし、IntelliSense などの "インテリジェントなコード補完" ツールでいずれかの宣言型アセットを操作するには、有効な App.Schema ファイルが必要です。If the "$schema keyword is missing, or points to an invalid or non-existent file you will not get any warnings or errors and it will not impact the functionality of your bot when running, however a valid App.Schema file is required for Intelligent code completion tools such as IntelliSense to work with any of the declarative assets.

宣言型コンポーネントに参照を追加するAdd references to declarative components

宣言型は、アダプティブ ダイアログでのみ機能します。Declarative only works with adaptive dialogs. ボットでアダプティブを有効にするには、Microsoft.Bot.Builder.Dialogs.Adaptive NuGet パッケージをインストールしてから、Startup.cs のコードに次の参照を作成します。To enable adaptive in your bot install the Microsoft.Bot.Builder.Dialogs.Adaptive NuGet package, then create the following references in your code in Startup.cs:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Bot.Builder;
using Microsoft.Bot.Builder.BotFramework;
using Microsoft.Bot.Builder.Dialogs;
using Microsoft.Bot.Builder.Dialogs.Adaptive;
using Microsoft.Bot.Builder.Dialogs.Declarative;
using Microsoft.Bot.Builder.Dialogs.Declarative.Resources;
using Microsoft.Bot.Builder.Integration.AspNet.Core;
using Microsoft.Bot.Connector.Authentication;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

EchoBot.cs でも次のようにします。Also in EchoBot.cs:

using System.Linq;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Bot.Builder;
using Microsoft.Bot.Builder.Dialogs;
using Microsoft.Bot.Builder.Dialogs.Adaptive;
using Microsoft.Bot.Builder.Dialogs.Declarative.Resources;

アダプティブ ダイアログの宣言型コンポーネントを登録するRegister declarative components for adaptive dialogs

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc();

    // Register dialog. This sets up memory paths for adaptive.
    ComponentRegistration.Add(new DialogsComponentRegistration());

    // Register adaptive component
    ComponentRegistration.Add(new AdaptiveComponentRegistration());

    // Register to use language generation.
    ComponentRegistration.Add(new LanguageGenerationComponentRegistration());

    // Register declarative components for adaptive dialogs.
    ComponentRegistration.Add(new DeclarativeComponentRegistration());

    // Create the credential provider to be used with the Bot Framework Adapter.
    services.AddSingleton<ICredentialProvider, ConfigurationCredentialProvider>();

    // Create the Bot Framework Adapter with error handling enabled.
    services.AddSingleton<IBotFrameworkHttpAdapter, EchoBotAdapter>();

    // Create the storage we'll be using for User and Conversation state. (Memory is great for testing purposes.)
    services.AddSingleton<IStorage, MemoryStorage>();

    // Create the User state. (Used in this bot's Dialog implementation.)
    services.AddSingleton<UserState>();

    // Create the Conversation state. (Used by the Dialog system itself.)
    services.AddSingleton<ConversationState>();

    var resourceExplorer = new ResourceExplorer().LoadProject(this.HostingEnvironment.ContentRootPath);
    services.AddSingleton(resourceExplorer);

    // Create the bot  In this case the ASP Controller is expecting an IBot.
    services.AddSingleton<IBot, EchoBot>();
}

宣言してダイアログを作成するCreate the dialog declaratively

宣言型ダイアログは一般的なコード ファイルではありません。Declarative dialogs are not typical code files. リソース エクスプローラーでは、リソースを解釈し、記述されたダイアログのインスタンスを生成できます。The resource explorer can interpret the resource and generate an instance of the described dialog. リソース エクスプローラーを使用して、実行時にそれらを読み込みます。Use a resource explorer to load them at run time.

ボットで使用する ResourceExplorerDialogManager のプロパティを作成します。Create properties for the ResourceExplorer and DialogManager your bot will use. 依存関係の挿入を使用して、リソース エクスプローラーを EchoBot コンストラクターに設定します。Use dependency injection to set the resource explorer in the EchoBot constructor.

public class EchoBot : ActivityHandler
{
    private IStatePropertyAccessor<DialogState> dialogStateAccessor;
    private readonly ResourceExplorer resourceExplorer;
    private DialogManager dialogManager;

    public EchoBot(ConversationState conversationState, ResourceExplorer resourceExplorer)
    {
        this.dialogStateAccessor = conversationState.CreateProperty<DialogState>("RootDialogState");
        this.resourceExplorer = resourceExplorer;

必要に応じて、resourceExplorer.Changed メソッドを使用して、基になる .dialog ファイルが変更されるたびに新しい設定で更新されるようにダイアログを設定できます。You can optionally set the dialog to update with new settings anytime the underlying .dialog file changes using the resourceExplorer.Changed method:

// auto reload dialogs when file changes
this.resourceExplorer.Changed += (e, resources) =>
{
    if (resources.Any(resource => resource.Id.EndsWith(".dialog")))
    {
        Task.Run(() => this.LoadRootDialogAsync());
    }
};

最後に、宣言型ダイアログ リソースを作成して、他のアダプティブ ダイアログと同じようにダイアログ マネージャーに読み込みます。Finally, you create a declarative dialog resource that you load into the dialog manager like you would any other adaptive dialog.

var resource = this.resourceExplorer.GetResource("main.dialog");
dialogManager = new DialogManager(resourceExplorer.LoadType<AdaptiveDialog>(resource));
dialogManager.UseResourceExplorer(resourceExplorer);
dialogManager.UseLanguageGeneration();

リソース エクスプローラーの GetResource メソッドを使用して、宣言ファイルをリソース オブジェクトに読み込み、その LoadType メソッドでリソースを AdaptiveDialog オブジェクトにキャストします。The resource explorer's GetResource method reads the declarative file into a resource object, and its LoadType method casts the resource to an AdaptiveDialog object. この場合、これは main.dialog ファイルです。Here, this is the main.dialog file. これで、他のアダプティブ ダイアログの場合と同じようにダイアログ マネージャーを作成できるようになります。You can then create a dialog manager as you would for any other adaptive dialog. ダイアログは、コードで定義されるのではなく、宣言ファイルから読み取られ、作成されます。the dialog is being read in and created from the declarative file instead of defined in code.

ダイアログ マネージャーの UseResourceExplorer メソッドを使用して、リソース エクスプローラーを登録します。これにより、後でダイアログ マネージャーから必要に応じてリソース エクスプローラーを使用できるようになります。The dialog manager's UseResourceExplorer method registers the resource explorer so that the dialog manager can make use of it later, as necessary. UseLanguageGeneration メソッドを使用して、使用する言語ジェネレーターをダイアログ マネージャーに指示します。The UseLanguageGeneration method tells the dialog manager which language generator to use.

この場合、言語生成 (LG) テンプレート ファイルが用意されておらず、このプロジェクトには main.lg の既定の LG ファイルが含まれていないため、ダイアログ マネージャーでは、定義済みのテンプレートなしで既定の言語ジェネレーターが使用されます。In this case, since no language generation (LG) template file is provided, and this project does not include a main.lg default LG file, the dialog manager will use the default language generator, without any predefined templates. ただし、エコー ボットには、ダイアログで使用されるインライン LG テンプレートが含まれています。However, the echo bot includes an in-line LG template used in the dialog. これは、main.dialog で定義されています。It is defined in main.dialog.

{
  "$schema": "../app.schema",
  "$kind": "Microsoft.AdaptiveDialog",
  "triggers": [
    {
      "$kind": "Microsoft.OnUnknownIntent",
      "actions": [
        {
          "$kind": "Microsoft.SendActivity",
          "activity":  "You said '${turn.activity.text}'"
        }
      ]
    }
  ]
}

ボットのテストTest the bot

  1. Bot Framework Emulator をインストールします (まだインストールしていない場合)。If you have not done so already, install the Bot Framework Emulator.
  2. ご自身のマシンを使ってローカルでサンプルを実行します。Run the sample locally on your machine.
  3. 以下に示すように、エミュレーターを起動し、お使いのボットに接続して、メッセージを送信します。Start the Emulator, connect to your bot, and send messages as shown below.

EchoBot 宣言型ダイアログ コード サンプルの実行例