Interface IAgentState

Namespace

Microsoft.Agents.Builder.State

Assembly

Microsoft.Agents.Builder.dll

Defines a state management object and automates the reading and writing of associated state properties to a storage layer.

public interface IAgentState

Remarks

Each state management object defines a scope for a storage layer.

State properties are created within a state management scope, and the Agents SDK defines these scopes: ConversationState, UserState, and PrivateConversationState.

You can define additional scopes for your Agent.

Properties

Name

The scope name of the state.

string Name { get; }

Property Value

string

Methods

ClearState()

Clears the state.

void ClearState()

Remarks

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

DeleteStateAsync(ITurnContext, CancellationToken)

Deletes state in storage.

Task DeleteStateAsync(ITurnContext turnContext, CancellationToken cancellationToken = default)

Parameters

turnContext ITurnContext

The context object for this turn.

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.

DeleteValue(string)

Delete a property.

void DeleteValue(string name)

Parameters

name string

The name of the property.

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

Get a property value.

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

Parameters

name string

The name of the property.

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

Parameters

name string

The name of the property.

Returns

bool

IsLoaded()

True if state has been loaded.

bool IsLoaded()

Returns

bool

LoadAsync(ITurnContext, bool, CancellationToken)

Populates state from the storage layer.

Task LoadAsync(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.

SaveChangesAsync(ITurnContext, bool, CancellationToken)

Writes state to the storage layer.

Task SaveChangesAsync(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<T>(string, T)

Set a property value.

void SetValue<T>(string name, T value)

Parameters

name string

The name of the property.

value T

The property value.

Type Parameters

T