Share via

TurnState class

Package:
@microsoft/agents-hosting

Base class defining a collection of turn state scopes.

Remarks

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

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

Properties

conversation

Gets the conversation-scoped state. This state is shared by all users in the same conversation.
isLoaded

Gets whether the state has been loaded from storage
temp

Gets the temporary state for the current turn. This state is not persisted between turns.
user

Gets the user-scoped state. This state is unique to each user and persists across conversations.

Methods

deleteConversationState()

Marks the conversation state for deletion. The state will be deleted from storage on the next call to save().
deleteTempState()

Marks the temporary state for deletion. Since temporary state is not persisted, this just clears the in-memory object.
deleteUserState()

Marks the user state for deletion. The state will be deleted from storage on the next call to save().
deleteValue(string)

Deletes a value from state by dot-notation path. Format: "scope.property" or just "property" (defaults to temp scope)
getScope(string)

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

Gets a value from state by dot-notation path. Format: "scope.property" or just "property" (defaults to temp scope)
hasValue(string)

Checks if a value exists in state by dot-notation path. Format: "scope.property" or just "property" (defaults to temp scope)
load(TurnContext, Storage, boolean)

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

Saves state changes to storage. Only changed scopes will be persisted.
setValue(string, unknown)

Sets a value in state by dot-notation path. Format: "scope.property" or just "property" (defaults to temp scope)

Property Details

conversation

Gets the conversation-scoped state. This state is shared by all users in the same conversation.

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. This state is not persisted between turns.

TTempState temp

Property Value

TTempState

The temporary state object

user

Gets the user-scoped state. This state is unique to each user and persists across conversations.

TUserState user

Property Value

TUserState

The user state object

Method Details

deleteConversationState()

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

function deleteConversationState()

deleteTempState()

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

function deleteTempState()

deleteUserState()

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

function deleteUserState()

deleteValue(string)

Deletes a value from state by dot-notation path. Format: "scope.property" or just "property" (defaults to temp scope)

function deleteValue(path: string)

Parameters

path

string

The path to the value to delete

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. Format: "scope.property" or just "property" (defaults to temp scope)

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

Parameters

path

string

The path to the value

Returns

TValue

The value at the specified path

hasValue(string)

Checks if a value exists in state by dot-notation path. Format: "scope.property" or just "property" (defaults to temp scope)

function hasValue(path: string): boolean

Parameters

path

string

The path to check

Returns

boolean

True if the value exists, false otherwise

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. Only changed scopes will be persisted.

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

setValue(string, unknown)

Sets a value in state by dot-notation path. Format: "scope.property" or just "property" (defaults to temp scope)

function setValue(path: string, value: unknown)

Parameters

path

string

The path to set

value

unknown

The value to set