Direct Line App Service 拡張機能に接続する .NET クライアントを作成するCreate .NET Client to Connect to Direct Line App Service Extension

この記事では、Direct Line App Service 拡張機能に接続する .NET クライアントを C# で作成する方法について説明します。This article describes how to create a .NET client in C# which connects to the direct line app service extension. また、「拡張機能のための .NET ボットの構成」という関連記事もお読みください。Please, also read this companion article Configure .NET bot for extension.

Direct Line 拡張機能キーを収集するGather your Direct Line Extension keys

  1. ブラウザーで Azure portal に移動します。In your browser, navigate to the Azure portal

  2. Azure portal で、目的の Azure Bot Service リソースを見つけます。In the Azure portal, locate your Azure Bot Service resource

  3. [チャネル] をクリックして、ボットのチャネルを構成します。Click on Channels to configure the bot’s channels

  4. Direct Line チャネルがまだ有効になっていない場合は、クリックして有効にします。If it is not already enabled, click on the Direct Line channel to enable it.

  5. 既に有効になっている場合は、[Connect to channels](チャネルに接続) テーブルの Direct Line 行で [編集] リンクをクリックします。If it is already enabled, in the Connect to channels table click on the Edit link on the Direct Line row.

  6. [サイト] セクションまでスクロールします。Scroll to the Sites section. 通常、削除または名前を変更していない限り、既定のサイトがあります。There is typically a Default Site unless you have deleted or renamed it.

  7. [表示] リンクをクリックしていずれかのキーを表示し、その値をコピーして保存します。Click on the Show link to reveal one of the keys, then copy and save its value. 次のセクションでこの値を使用します。You will use this value in the next section.

    App Service 拡張機能キー

注意

この値は、Direct Line App Service 拡張機能に接続するために使用される Direct Line クライアントのシークレットです。This value is your direct line client secret used to connect to direct line app service extension. 必要に応じて追加のサイトを作成でき、それらのシークレット値も使用できます。You can create additional sites if you’d like and use those secret values as well.

プレビュー版の Nuget パッケージのソースを追加するAdd the Preview Nuget Package Source

C# Direct Line クライアントを作成するために必要なプレビュー版の NuGet パッケージは、NuGet フィードにあります。The preview NuGet packages needed to create a C# Direct line client can be found in a NuGet feed.

  1. Visual Studio で、 [ツール]->[オプション] メニュー項目に移動します。In Visual Studio navigate to the Tools->Options menu item.
  2. [NuGet パッケージ マネージャー]->[パッケージ ソース] 項目を選択します。Select the NuGet Package Manager->Package Sources item.
  3. [+] ボタンをクリックして、次の値を使って新しいパッケージを追加します。Click on the + button to add a new package source with these values:
  4. [更新] ボタンをクリックして値を保存します。Click on the Update button to save the values.
  5. [OK] をクリックして、パッケージ ソースの構成を終了します。Click OK to exit the Package Sources configuration.

C# Direct Line クライアントを作成するCreate a C# Direct Line Client

Direct Line App Service 拡張機能との対話は、従来の Direct Line とは異なる方法で行われます。これは、ほとんどの通信が WebSocket で行われるためです。Interactions with the direct line app service extension happen differently than traditional Direct Line because most communication happens over a WebSocket. 更新された Direct Line クライアントには、WebSocket の開始/終了、WebSocket 経由でのコマンドの送信、およびボットから返される Activity の受信のためのヘルパー クラスが含まれています。The updated direct line client includes helper classes for opening and closing a WebSocket, sending commands through the WebSocket, and receiving Activities back from the bot. このセクションでは、ボットと対話するための単純な C# クライアントを作成する方法について説明します。This section describes how to create a simple C# client to interact with a bot.

  1. Visual Studio で、新しい .NET Core 2.2 コンソール アプリケーション プロジェクトを作成します。Create a new .NET Core 2.2 console application project in Visual Studio.

  2. DirectLine クライアント NuGet をプロジェクトに追加しますAdd the DirectLine client NuGet to your project

    • [ソリューション] ツリーで [依存関係] をクリックしますClick on Dependencies in the Solution tree
    • [NuGet パッケージの管理] を選択しますSelect Manage Nuget Packages...
    • パッケージ ソースを、上で定義したもの (DL ASE Preview) に変更しますChange the Package source to the one you defined from above (DL ASE Preview)
    • パッケージ Microsoft.Bot.Connector.Directline バージョン v3.0.3-Preview1 以降を見つけます。Find the package Microsoft.Bot.Connector.Directline version v3.0.3-Preview1 or later.
    • [パッケージのインストール] をクリックします。Click on Install Package.
  3. クライアントを作成し、シークレットを使用してトークンを生成します。Create a client and generate a token using a secret. この手順は、次に示すように .bot/ パスが付加された、ボットで使用する必要があるエンドポイントを除き、他の C# Direct Line クライアントの構築と同じです。This step is the same as building any other C# Direct Line client except the endpoint you need use in your bot,appended with the .bot/ path as shown next. 末尾の / を忘れないでください。Do not forget the ending /.

    string endpoint = "https://<YOUR_BOT_HOST>.azurewebsites.net/.bot/";
    string secret = "<YOUR_BOT_SECRET>";
    
    var tokenClient = new DirectLineClient(
        new Uri(endpoint),
        new DirectLineClientCredentials(secret));
    var conversation = await tokenClient.Tokens.GenerateTokenForNewConversationAsync();
    

    次に注意してください。Notice the following:

    • エンドポイント値は、ボットを Azure にデプロイしたときに取得したボットの URL です。The endpoint value is the bot URL you obtained when you deployed the bot to Azure. 詳細については、「拡張機能のための .NET ボットの構成」を参照してください。For more information, see Configure .NET bot for extension.
    • YOUR_BOT_SECRET として表示されるシークレット値は、前に " [サイト] セクション" から保存した値です。The secret value shown as YOUR_BOT_SECRET is the value you saved earlier from the sites section.
  4. トークンの生成から会話の参照を取得したら、この会話 ID を使用して、DirectLineClient の新しい StreamingConversations プロパティで WebSocket を開くことができます。Once you have a conversation reference from generating a token, you can use this conversation ID to open a WebSocket with the new StreamingConversations property on the DirectLineClient. これを行うには、ボットが ActivitySets をクライアントに送信するときに呼び出されるコールバックを作成する必要があります。To do this you need to create a callback that will be invoked when the bot wants to send ActivitySets to the client:

    public static void ReceiveActivities(ActivitySet activitySet)
    {
        if (activitySet != null)
        {
            foreach (var a in activitySet.Activities)
            {
                if (a.Type == ActivityTypes.Message && a.From.Id.Contains("bot"))
                {
                    Console.WriteLine($"<Bot>: {a.Text}");
                }
            }
        }
    }
    
  5. これで、会話のトークン conversationIdReceiveActivities コールバックを使用して StreamingConversations プロパティで WebSocket を開く準備ができました。Now you are ready to open the WebSocket on the StreamingConversations property using the conversation’s token, conversationId, and your ReceiveActivities callback:

    var client = new DirectLineClient(
        new Uri(endpoint),
        new DirectLineClientCredentials(conversation.Token));
    
    await client.StreamingConversations.ConnectAsync(
        conversation.ConversationId,
        ReceiveActivities);
    
  6. これで、クライアントを使用して会話を開始し、Activities をボットに送信できるようになりました。The client can now be used to start a conversation and send Activities to the bot:

    
    var startConversation = await client.StreamingConversations.StartConversationAsync();
    var from = new ChannelAccount() { Id = "123", Name = "Fred" };
    var message = Console.ReadLine();
    
    while (message != "end")
    {
        try
        {
            var response = await client.StreamingConversations.PostActivityAsync(
                startConversation.ConversationId,
                new Activity()
                {
                    Type = "message",
                    Text = message,
                    From = from
                });
        }
        catch (OperationException ex)
        {
            Console.WriteLine(
                $"OperationException when calling PostActivityAsync: ({ex.StatusCode})");
        }
        message = Console.ReadLine();
    }