Using .NET v3 user state in a v4 bot
APPLIES TO: SDK v4
This article shows an example of how a v4 bot can perform read, write, and delete operations on v3 user state information.
The bot maintains conversation state using MemoryStorage to track and direct the conversation while asking the user questions. It maintains the user state in the v3 format to track the user's answers by utilizing a custom IStorage class called V3V4Storage. One of the arguments to this class is an IBotDataStore. 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). The intent is to allow the existing v3 user state to be brought into a migrated v4 bot.
The code sample can be found in v4 state bot from v3 providers.
Prerequisites
.NET Core SDK version 2.1
# determine dotnet version dotnet --version
Setup
Clone the repository
git clone https://github.com/microsoft/botbuilder-samples.gitIn a terminal, navigate to
Migration/MigrationV3V4/CSharp/V4StateBotFromV3Providerscd BotBuilder-Samples/Migration/MigrationV3V4/CSharp/V4StateBotFromV3ProvidersRun the bot from a terminal or from Visual Studio, choose option A or B.
From a terminal
# run the bot dotnet runOr from Visual Studio
- Launch Visual Studio File -> Open -> Project/Solution
- Navigate to
BotBuilder-Samples/Migration/MigrationV3V4/CSharp/V4StateBotFromV3Providersfolder - Select
V4StateBot.slnfile - Press F5 to run the project
Storage Provider setup
It is assumed that you have an existing v3 state store configured and in use. 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 DB
"v3CosmosEndpoint": "https://yourcosmosdb.documents.azure.com:443/",
"v3CosmosKey": "YourCosmosDbKey",
"v3CosmosDatataseName": "v3botdb",
"v3CosmosCollectionName": "v3botcollection",
- Azure 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 Table
"ConnectionStrings": {
"AzureTable": "DefaultEndpointsProtocol=https;AccountName=YourAccountName;AccountKey=YourAccountKey;EndpointSuffix=core.windows.net"
},
Set the bot's storage provider
Open the
Startup.csfile in theV4V3StateBotproject root. Towards the middle of the file (lines ~52-76) you will see configurations for each storage provider. 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. 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 (formerly Document DB) is set by default. The possible values are:
documentDbBotDataStore tableBotDataStore tableBotDataStore2 sqlBotDataStoreStart the application.
V3V4 Storage and State Classes
V3V4Storage
The V3V4Storage class contains the main storage mapping functionality. 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.
V3V4State
This class inherits from the v4 BotState class, and uses a v3-style key (IAddress). This allows reads, writes & deletes to v3 storage in the same way V3 state storage has always worked.
Testing the bot using 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.
- Install the Bot Framework Emulator, version 4.3.0 or later.
Connect to the bot using Bot Framework Emulator
- Launch Bot Framework Emulator
- File -> Open Bot
- Enter a Bot URL of
http://localhost:3978/api/messages