Interface ITurnState

Namespace

Microsoft.Agents.Builder.State

Assembly

Microsoft.Agents.Builder.dll

TurnState represents the state for an Agent. State is composed of 1+ state scopes.

public interface ITurnState

Properties

Conversation

ConversationState Conversation { get; }

Property Value

ConversationState

Private

PrivateConversationState Private { get; }

Property Value

PrivateConversationState

Temp

TempState Temp { get; }

Property Value

TempState

User

UserState User { get; }

Property Value

UserState

Methods

ClearState(string)

Clears the state.

void ClearState(string scope)

Parameters

scope string

The scope name. eg "conversation", etc...

Remarks

This method clears the state cache. Call SaveChangesAsync(ITurnContext, bool, CancellationToken) to persist this change in the storage layer.

DeleteValue(string)

Delete a property.

void DeleteValue(string path)

Parameters

path string

The full path to the property: {scope}.{name}

GetScope(string)

IAgentState GetScope(string scope)

Parameters

scope string

Returns

IAgentState

GetScope<T>()

T GetScope<T>()

Returns

T

Type Parameters

T

GetValue<T>(string, Func<T>)

Get a property value.

T GetValue<T>(string path, Func<T> defaultValueFactory = null)

Parameters

path string

The full path to the property: {scope}.{name}

defaultValueFactory Func<T>

Defines the default value. Invoked when no value been set for the requested state property. If defaultValueFactory is defined as null in that case, the method returns null.

Returns

T

Type Parameters

T

HasValue(string)

Checks for the existence of a property.

bool HasValue(string path)

Parameters

path string

The full path to the property: {scope}.{name}

Returns

bool

LoadStateAsync(ITurnContext, bool, CancellationToken)

Populates all states from the storage layer.

Task LoadStateAsync(ITurnContext turnContext, bool force = false, CancellationToken cancellationToken = default)

Parameters

turnContext ITurnContext

The context object for this turn.

force bool

Optional, true to overwrite any existing state cache; or false to load state from storage only if the cache doesn't already exist.

cancellationToken CancellationToken

A cancellation token that can be used by other objects or threads to receive notice of cancellation.

Returns

Task

A task that represents the work queued to execute.

Remarks

LoadAsync loads State for the specified turn.

Exceptions

ArgumentNullException

turnContext is null.

SaveStateAsync(ITurnContext, bool, CancellationToken)

Writes all states to the storage layer.

Task SaveStateAsync(ITurnContext turnContext, bool force = false, CancellationToken cancellationToken = default)

Parameters

turnContext ITurnContext

The context object for this turn.

force bool

Optional, true to save the state cache to storage; or false to save state to storage only if a property in the cache has changed.

cancellationToken CancellationToken

A cancellation token that can be used by other objects or threads to receive notice of cancellation.

Returns

Task

A task that represents the work queued to execute.

Exceptions

ArgumentNullException

turnContext is null.

SetValue(string, object)

Set a property value.

void SetValue(string path, object value)

Parameters

path string

The full path to the property: {scope}.{name}

value object

The property value.