Table of Contents

Class AgentState

Namespace
Microsoft.Agents.Builder.State
Assembly
Microsoft.Agents.Builder.dll

Base class for AgentState key/value state.

public abstract class AgentState : IPropertyManager, IAgentState
Inheritance
AgentState
Implements
Derived
Inherited Members

Constructors

AgentState(IStorage, string)

Initializes a new instance of the AgentState class.

public AgentState(IStorage storage, string stateName)

Parameters

storage IStorage

The storage layer this state management object will use to store and retrieve state.

stateName string

The key for the state cache for this AgentState.

Remarks

This constructor creates a state management object and associated scope. The object uses storage to persist state property values. The object uses the stateName to cache state within the context for each turn.

Exceptions

ArgumentNullException

storage or stateName is null.

See Also

Properties

Name

The scope name of the state.

public string Name { get; }

Property Value

string

Methods

ClearState()

Clears the state.

public virtual void ClearState()

Remarks

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

CreateProperty<T>(string)

Creates a named state property within the scope of a AgentState and returns an accessor for the property.

[Obsolete("Use AgentState.GetValue and AgentsState.SetValue")]
public IStatePropertyAccessor<T> CreateProperty<T>(string name)

Parameters

name string

The name of the property.

Returns

IStatePropertyAccessor<T>

An accessor for the property.

Type Parameters

T

The value type of the property.

Exceptions

ArgumentNullException

name is null.

DeletePropertyValue(string)

Deletes a property from the state cache for this AgentState.

protected void DeletePropertyValue(string propertyName)

Parameters

propertyName string

The name of the property.

DeleteStateAsync(ITurnContext, CancellationToken)

Deletes state in storage.

public virtual 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.

public void DeleteValue(string name)

Parameters

name string

The name of the property.

GetPropertyValue<T>(string)

Gets the value of a property from the state cache for this AgentState.

protected T GetPropertyValue<T>(string propertyName)

Parameters

propertyName string

The name of the property.

Returns

T

A task that represents the work queued to execute.

Type Parameters

T

The value type of the property.

Remarks

If the task is successful, the result contains the property value, otherwise it will be default(T).

GetStorageKey(ITurnContext)

When overridden in a derived class, gets the key to use when reading and writing state to and from storage.

protected abstract string GetStorageKey(ITurnContext turnContext)

Parameters

turnContext ITurnContext

The context object for this turn.

Returns

string

The storage key.

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

Get a property value.

public 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.

public bool HasValue(string name)

Parameters

name string

The name of the property.

Returns

bool

IsLoaded()

True if state has been loaded.

public bool IsLoaded()

Returns

bool

LoadAsync(ITurnContext, bool, CancellationToken)

Populates state from the storage layer.

public virtual 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.

public virtual 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.

SetPropertyValue(string, object)

Sets the value of a property in the state cache for this AgentState.

protected void SetPropertyValue(string propertyName, object value)

Parameters

propertyName string

The name of the property to set.

value object

The value to set on the property.

SetValue<T>(string, T)

Set a property value.

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

Parameters

name string

The name of the property.

value T

The property value.

Type Parameters

T

TryGetValue<T>(string, out T) 

public bool TryGetValue<T>(string name, out T result)

Parameters

name string
result T

Returns

bool

Type Parameters

T

See Also

IStorage