v4 ボットで .NET v3 ユーザー状態を使用するUsing .NET v3 user state in a v4 bot

適用対象: SDK v4APPLIES TO: SDK v4

この記事では、v4 ボットで v3 ユーザー状態情報の読み取り、書き込み、および削除の各操作を実行する方法の例を示します。This article shows an example of how a v4 bot can perform read, write, and delete operations on v3 user state information. ボットは、ユーザーに質問する間、MemoryStorage を使用して会話の状態を維持し、会話を追跡および制御します。The bot maintains conversation state using MemoryStorage to track and direct the conversation while asking the user questions. V3V4Storage というカスタムの IStorage クラスを使用して、v3 形式で ユーザー状態 を保持し、ユーザーの回答を追跡します。It maintains the user state in the v3 format to track the user's answers by utilizing a custom IStorage class called V3V4Storage. このクラスの引数の 1 つは IBotDataStore です。One of the arguments to this class is an IBotDataStore. v3 SDK コード ベースが Bot.Builder.Azure.V3V4 にコピーされており、3 つすべての v3 SDK ストレージ プロバイダー (Azure SQL、Azure Table、Cosmos DB) が含まれています。The v3 SDK code base was copied into Bot.Builder.Azure.V3V4 and contains all three v3 SDK storage providers (Azure Sql, Azure Table, and Cosmos Db). その目的は、既存の v3 ユーザー状態 を移行済みの v4 ボットに取り込めるようにすることです。The intent is to allow the existing v3 user state to be brought into a migrated v4 bot.

このコードサンプルは、 v3 プロバイダーの v4 状態ボットにあります。The code sample can be found in v4 state bot from v3 providers.

前提条件Prerequisites

セットアップSetup

  1. リポジトリの複製Clone the repository

    git clone https://github.com/microsoft/botbuilder-samples.git
    
  2. 端末で、Migration/MigrationV3V4/CSharp/V4StateBotFromV3Providers に移動します。In a terminal, navigate to Migration/MigrationV3V4/CSharp/V4StateBotFromV3Providers

    cd BotBuilder-Samples/Migration/MigrationV3V4/CSharp/V4StateBotFromV3Providers
    
  3. 端末または Visual Studio からボットを実行し、オプション A または B を選択します。Run the bot from a terminal or from Visual Studio, choose option A or B.

    • 端末からFrom a terminal

      # run the bot
      dotnet run
      
    • Visual Studio からOr from Visual Studio

      • Visual Studio を起動し、[ファイル] -> [開く] -> [プロジェクト/ソリューション] を選択します。Launch Visual Studio File -> Open -> Project/Solution
      • BotBuilder-Samples/Migration/MigrationV3V4/CSharp/V4StateBotFromV3Providers フォルダーに移動します。Navigate to BotBuilder-Samples/Migration/MigrationV3V4/CSharp/V4StateBotFromV3Providers folder
      • V4StateBot.sln ファイルを選択します。Select V4StateBot.sln file
      • F5 キーを押して、プロジェクトを実行します。Press F5 to run the project

ストレージ プロバイダーのセットアップStorage Provider setup

既存の v3 状態ストアが構成され、使用されていることを前提とします。It is assumed that you have an existing v3 state store configured and in use. この場合、次に示すように、この例では既存の状態ストアを使用するように設定するときに、ストレージ プロバイダーの接続情報を web.config ファイルに追加するだけですみます。In this case, setting up this example to use the existing state store simply involve adding the storage provider's connection information to web.config file as shown next.

  • Cosmos DBCosmos DB
  "v3CosmosEndpoint": "https://yourcosmosdb.documents.azure.com:443/",
  "v3CosmosKey": "YourCosmosDbKey",
  "v3CosmosDatataseName": "v3botdb",
  "v3CosmosCollectionName": "v3botcollection",
  • Azure SQLAzure Sql
 "ConnectionStrings": {
    "SqlBotData": "Server=YourServer;Initial Catalog=BotData;Persist Security Info=False;User ID=YourUserName;Password=YourUserPassword;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=True;Connection Timeout=30;"
  },
  • Azure テーブルAzure Table
 "ConnectionStrings": {
    "AzureTable": "DefaultEndpointsProtocol=https;AccountName=YourAccountName;AccountKey=YourAccountKey;EndpointSuffix=core.windows.net"
  },
  • ボットのストレージ プロバイダーの設定Set the bot's storage provider

    V4V3StateBot プロジェクトのルートにある Startup.cs ファイルを開きます。Open the Startup.cs file in the V4V3StateBot project root. ファイルの中間部分 (おおよそ 52 から 76 行) に、各ストレージ プロバイダーの構成があります。Towards the middle of the file (lines ~52-76) you will see configurations for each storage provider. web.config から構成値が読み込まれます。They read in the config values from the web.config.

    Uri docDbEmulatorUri = new Uri(Configuration["v3CosmosEndpoint"]);
    var documentDbBotDataStore = new DocumentDbBotDataStore(docDbEmulatorUri,
                Configuration["v3CosmosKey"],
                databaseId: Configuration["v3CosmosDatataseName"],
                collectionId: Configuration["v3CosmosCollectionName"]);
    
    // SqlBotDataStore for V3V4 User State
    //var sqlConnectionString = Configuration.GetConnectionString("SqlBotData");
    //var sqlBotDataStore = new SqlBotDataStore(sqlConnectionString);
    
    // TableBotDataStore for V3V4 User State
    //var tableConnectionString = Configuration.GetConnectionString("AzureTable");
    //var tableBotDataStore = new TableBotDataStore(tableConnectionString);
    
    // TableBotDataStore2 for V3V4 User State            
    //var tableBotDataStore2 = new TableBotDataStore2(tableConnectionString);
    
    
    // Create the V3V4Storage layer bridge, providing a V3 storage.
    // Then use that storage to create a V3V4State, and inject as a singleton
    var v3v4Storage = new V3V4Storage(documentDbBotDataStore);
    //var v3v4Storage = new V3V4Storage(sqlBotDataStore);
    //var v3v4Storage = new V3V4Storage(tableBotDataStore);
    //var v3v4Storage = new V3V4Storage(tableBotDataStore2);
    services.AddSingleton<V3V4State>(new V3V4State(v3v4Storage));
    

    選択したインスタンスの対応する行をコメント解除することで、ボットでどのストレージ プロバイダーを使用するかを指定します。Specify which storage provider you want your bot to use by un-commenting the corresponding lines for the instance of your choice. プロバイダーが適切に構成された後、プロバイダー クラスが V3V4Storage に渡されることを確認します (おおよそ 72 から 75 行)。Once the provider is properly configured, assure that the provider class is passed to V3V4Storage (lines ~72-75).

    var v3v4Storage = new V3V4Storage(documentDbBotDataStore);
    //var v3v4Storage = new V3V4Storage(sqlBotDataStore);
    //var v3v4Storage = new V3V4Storage(tableBotDataStore);
    //var v3v4Storage = new V3V4Storage(tableBotDataStore2);
    

    Cosmos DB (以前の Document DB) は既定で設定されています。Cosmos DB (formerly Document DB) is set by default. 指定できる値は、The possible values are:

    documentDbBotDataStore
    tableBotDataStore
    tableBotDataStore2
    sqlBotDataStore
    
  • アプリケーションを起動します。Start the application.

V3V4 ストレージ クラスと状態クラスV3V4 Storage and State Classes

V3V4StorageV3V4Storage

V3V4Storage クラスには、主要なストレージ マッピング機能が含まれます。The V3V4Storage class contains the main storage mapping functionality. このクラスにより、v4 IStorage インターフェイスが実装され、ストレージ プロバイダーのメソッド (読み取り、書き込み、および削除) が v3 ストレージ プロバイダーのクラスにマップされます。これにより、v3 形式のユーザー状態を v4 ボットから使用できます。It implements the v4 IStorage interface and maps the storage provider methods (read, write and delete) back to the v3 storage provider classes so that v3-formatted user state can be used from a v4 bot.

V3V4StateV3V4State

このクラスは、v4 BotState クラスを継承しており、v3 形式のキー (IAddress) を使用します。This class inherits from the v4 BotState class, and uses a v3-style key (IAddress). これにより、v3 状態ストレージの通常の操作方法と同じ方法で、v3 ストレージに対して読み取り、書き込み、および削除の各操作を実行できます。This allows reads, writes & deletes to v3 storage in the same way V3 state storage has always worked.

Bot Framework Emulator を使用したボットのテストTesting the bot using Bot Framework Emulator

Bot Framework Emulator は、ボット開発者がローカルホストで、またはトンネルを介したリモート実行でボットをテストおよびデバッグできるデスクトップ アプリケーションです。Bot Framework Emulator is a desktop application that allows bot developers to test and debug their bots on localhost or running remotely through a tunnel.

Bot Framework Emulator を使用したボットへの接続Connect to the bot using Bot Framework Emulator

  • Bot Framework Emulator を起動します。Launch Bot Framework Emulator
  • [File] -> [Open Bot](ボットを開く) を選択します。File -> Open Bot
  • ボットの URL として http://localhost:3978/api/messages を入力します。Enter a Bot URL of http://localhost:3978/api/messages

関連項目Further reading