UserState class

Package:

botbuilder-core

Reads and writes user state for your bot to storage.

Extends

BotState

Remarks

Each user your bot communicates with will have its own isolated storage object that can be used to persist information about the user across all of the conversation you have with that user.

const { UserState, MemoryStorage } = require('botbuilder');

const userState = new UserState(new MemoryStorage());

Constructors

UserState(Storage, string)

Creates a new UserState instance.

Methods

getStorageKey(TurnContext)

Returns the storage key for the current user state.

Inherited 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

UserState(Storage, string)

Creates a new UserState instance.

new UserState(storage: Storage, namespace?: string)

Parameters

storage

Storage

Storage provider to persist user state to.

namespace

string

(Optional) namespace to append to storage keys. Defaults to an empty string.

Method Details

getStorageKey(TurnContext)

Returns the storage key for the current user state.

function getStorageKey(context: TurnContext): string | undefined

Parameters

context

TurnContext

Context for current turn of conversation with the user.

Returns

string | undefined

The storage key for the current user state.

Inherited 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);

Inherited From BotState.clear

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.

Inherited From BotState.createProperty

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);

Inherited From BotState.delete

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);

Inherited From BotState.get

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);

Inherited From BotState.load

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);

Inherited From BotState.saveChanges