BotState class

Package:

botbuilder-core

Base class for the frameworks state persistance scopes.

Remarks

This class will read and write state, to a provided storage provider, for each turn of conversation with a user. Derived classes, like ConversationState and UserState, provide a StorageKeyFactory which is used to determine the key used to persist a given storage object.

The state object thats loaded will be automatically cached on the context object for the lifetime of the turn and will only be written to storage if it has been modified.

Constructors

BotState(Storage, StorageKeyFactory)

Creates a new BotState instance.

Methods

clear(TurnContext)	Clears the current state object for a turn.
createProperty<T>(string)	Creates a new property accessor for reading and writing an individual property to the bot states storage object.
delete(TurnContext)	Delete the backing state object for the current turn.
get(TurnContext)	Returns a cached state object or undefined if not cached.
load(TurnContext, boolean)	Reads in and caches the backing state object for a turn.
saveChanges(TurnContext, boolean)	Saves the cached state object if it's been changed.

Constructor Details

BotState(Storage, StorageKeyFactory)

Creates a new BotState instance.

new BotState(storage: Storage, storageKey: StorageKeyFactory)

Parameters

storage

Storage

Storage provider to persist the state object to.

storageKey

StorageKeyFactory

Function called anytime the storage key for a given turn needs to be calculated.

Method Details

clear(TurnContext)

Clears the current state object for a turn.

function clear(context: TurnContext): Promise<void>

Parameters

context

TurnContext

Context for current turn of conversation with the user.

Returns

Promise<void>

A promise representing the async operation.

Remarks

The cleared state object will not be persisted until saveChanges() has been called.

await botState.clear(context);
await botState.saveChanges(context);

createProperty<T>(string)

Creates a new property accessor for reading and writing an individual property to the bot states storage object.

function createProperty<T>(name: string): StatePropertyAccessor<T>

Parameters

name

string

Name of the property to add.

Returns

StatePropertyAccessor<T>

An accessor for the property.

delete(TurnContext)

Delete the backing state object for the current turn.

function delete(context: TurnContext): Promise<void>

Parameters

context

TurnContext

Context for current turn of conversation with the user.

Returns

Promise<void>

A promise representing the async operation.

Remarks

The state object will be removed from storage if it exists. If the state object has been read in and cached, the cache will be cleared.

await botState.delete(context);

get(TurnContext)

Returns a cached state object or undefined if not cached.

function get(context: TurnContext): any | undefined

Parameters

context

TurnContext

Context for current turn of conversation with the user.

Returns

any | undefined

A cached state object or undefined if not cached.

Remarks

This example shows how to synchronously get an already loaded and cached state object:

const state = botState.get(context);

load(TurnContext, boolean)

Reads in and caches the backing state object for a turn.

function load(context: TurnContext, force?: boolean): Promise<any>

Parameters

context

TurnContext

Context for current turn of conversation with the user.

force

boolean

(Optional) If true the cache will be bypassed and the state will always be read in directly from storage. Defaults to false.

Returns

Promise<any>

The cached state.

Remarks

Subsequent reads will return the cached object unless the force flag is passed in which will force the state object to be re-read.

This method is automatically called on first access of any of created property accessors.

const state = await botState.load(context);

saveChanges(TurnContext, boolean)

Saves the cached state object if it's been changed.

function saveChanges(context: TurnContext, force?: boolean): Promise<void>

Parameters

context

TurnContext

Context for current turn of conversation with the user.

force

boolean

(Optional) if true the state will always be written out regardless of its change state. Defaults to false.

Returns

Promise<void>

A promise representing the async operation.

Remarks

If the force flag is passed in the cached state object will be saved regardless of whether its been changed or not and if no object has been cached, an empty object will be created and then saved.

await botState.saveChanges(context);