Share via

TurnState class

Package:
@microsoft/agents-hosting

Base class defining a collection of turn state scopes.

Example

class MyTurnState extends TurnState {
  protected async onComputeStorageKeys(context) {
    const keys = await super.onComputeStorageKeys(context);
    keys['myScope'] = `myScopeKey`;
    return keys;
  }

  public get myScope() {
    const scope = this.getScope('myScope');
    if (!scope) {
      throw new Error(`MyTurnState hasn't been loaded. Call load() first.`);
    }
    return scope.value;
  }

  public set myScope(value) {
    const scope = this.getScope('myScope');
    if (!scope) {
      throw new Error(`MyTurnState hasn't been loaded. Call load() first.`);
    }
    scope.replace(value);
  }
}

Remarks

Developers can create a derived class that extends TurnState to add additional state scopes.

Properties

conversation

Gets the conversation-scoped state.
isLoaded

Gets whether the state has been loaded from storage
temp

Gets the temporary state for the current turn.
user

Gets the user-scoped state.

Methods

deleteConversationState()

Marks the conversation state for deletion.
deleteTempState()

Marks the temporary state for deletion.
deleteUserState()

Marks the user state for deletion.
deleteValue(string)

Deletes a value from state by dot-notation path.
getScope(string)

Gets a specific state scope by name.
getValue<TValue>(string)

Gets a value from state by dot-notation path.
hasValue(string)

Checks if a value exists in state by dot-notation path.
load(TurnContext, Storage, boolean)

Loads state from storage into memory.
save(TurnContext, Storage)

Saves state changes to storage.
setValue(string, unknown)

Sets a value in state by dot-notation path.

Property Details

conversation

Gets the conversation-scoped state.

TConversationState conversation

Property Value

TConversationState

The conversation state object

isLoaded

Gets whether the state has been loaded from storage

boolean isLoaded

Property Value

boolean

True if the state has been loaded, false otherwise

temp

Gets the temporary state for the current turn.

TTempState temp

Property Value

TTempState

The temporary state object

user

Gets the user-scoped state.

TUserState user

Property Value

TUserState

The user state object

Method Details

deleteConversationState()

Marks the conversation state for deletion.

function deleteConversationState()

Remarks

The state will be deleted from storage on the next call to save().

deleteTempState()

Marks the temporary state for deletion.

function deleteTempState()

Remarks

Since temporary state is not persisted, this just clears the in-memory object.

deleteUserState()

Marks the user state for deletion.

function deleteUserState()

Remarks

The state will be deleted from storage on the next call to save().

deleteValue(string)

Deletes a value from state by dot-notation path.

function deleteValue(path: string)

Parameters

path

string

The path to the value to delete

Remarks

Format: "scope.property" or just "property" (defaults to temp scope)

getScope(string)

Gets a specific state scope by name.

function getScope(scope: string): undefined | TurnStateEntry

Parameters

scope

string

The name of the scope to retrieve

Returns

undefined | TurnStateEntry

The state entry for the scope, or undefined if not found

getValue<TValue>(string)

Gets a value from state by dot-notation path.

function getValue<TValue>(path: string): TValue

Parameters

path

string

The path to the value

Returns

TValue

The value at the specified path

Remarks

Format: "scope.property" or just "property" (defaults to temp scope)

hasValue(string)

Checks if a value exists in state by dot-notation path.

function hasValue(path: string): boolean

Parameters

path

string

The path to check

Returns

boolean

True if the value exists, false otherwise

Remarks

Format: "scope.property" or just "property" (defaults to temp scope)

load(TurnContext, Storage, boolean)

Loads state from storage into memory.

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

Parameters

context
TurnContext

The turn context

storage
Storage

Optional storage provider (if not provided, state will be in-memory only)

force

boolean

If true, forces a reload from storage even if state is already loaded

Returns

Promise<boolean>

Promise that resolves to true if state was loaded, false if it was already loaded

save(TurnContext, Storage)

Saves state changes to storage.

function save(context: TurnContext, storage?: Storage): Promise<void>

Parameters

context
TurnContext

The turn context

storage
Storage

Optional storage provider (if not provided, state changes won't be persisted)

Returns

Promise<void>

Promise that resolves when the save operation is complete

Remarks

Only changed scopes will be persisted.

setValue(string, unknown)

Sets a value in state by dot-notation path.

function setValue(path: string, value: unknown)

Parameters

path

string

The path to set

value

unknown

The value to set

Remarks

Format: "scope.property" or just "property" (defaults to temp scope)