Table of Contents

Class TurnContext

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

Provides context for a turn of an Agent.

public class TurnContext : ITurnContext, IDisposable
Inheritance
TurnContext
Implements
Inherited Members

Remarks

Context provides information needed to process an incoming activity. The context object is created by a IChannelAdapter and persists for the length of the turn. TurnContext cannot be used after the turn is complete.

Constructors

TurnContext(IChannelAdapter, IActivity)

Initializes a new instance of the TurnContext class.

public TurnContext(IChannelAdapter adapter, IActivity activity)

Parameters

adapter IChannelAdapter

The adapter creating the context.

activity IActivity

The incoming activity for the turn; or null for a turn for a proactive message.

Remarks

For use by Adapter implementations only.

Exceptions

ArgumentNullException

activity or adapter is null.

TurnContext(ITurnContext, IActivity)

Initializes a new instance of the ITurnContext class from another TurnContext class to target an alternate Activity.

public TurnContext(ITurnContext turnContext, IActivity activity)

Parameters

turnContext ITurnContext

context to clone.

activity IActivity

activity to put into the new turn context.

Remarks

For supporting calling legacy systems that always assume ITurnContext.Activity is the activity should be processed. This class clones the TurnContext and then replaces the original.activity with the passed in activity.

Properties

Activity

Gets the activity associated with this turn; or null when processing a proactive message.

public IActivity Activity { get; }

Property Value

IActivity

The activity associated with this turn.

Adapter

Gets the Adapter that created this context object.

public IChannelAdapter Adapter { get; }

Property Value

IChannelAdapter

The Adapter that created this context object.

Identity 

public ClaimsIdentity Identity { get; }

Property Value

ClaimsIdentity

Responded

Gets a value indicating whether at least one response was sent for the current turn.

public bool Responded { get; }

Property Value

bool

true if at least one response was sent for the current turn.

Services

Gets the services registered on this context object.

public TurnContextStateCollection Services { get; }

Property Value

TurnContextStateCollection

The services registered on this context object.

StackState 

public TurnContextStateCollection StackState { get; }

Property Value

TurnContextStateCollection

StreamingResponse

Provides access to the IStreamingResponse to allow streaming of chunked messages (for example, via streaming AI responses).

public IStreamingResponse StreamingResponse { get; }

Property Value

IStreamingResponse

Methods

DeleteActivityAsync(ConversationReference, CancellationToken)

Deletes an existing activity.

public Task DeleteActivityAsync(ConversationReference conversationReference, CancellationToken cancellationToken = default)

Parameters

conversationReference ConversationReference

The conversation containing the activity to delete.

cancellationToken CancellationToken

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

Returns

Task

The conversation reference's Microsoft.Agents.Core.Models.ConversationReference.ActivityId indicates the activity in the conversation to delete.

Not all channels support this operation. For channels that don't, this call may throw an exception.

See Also

DeleteActivityAsync(string, CancellationToken)

Deletes an existing activity.

public Task DeleteActivityAsync(string activityId, CancellationToken cancellationToken = default)

Parameters

activityId string

The ID of the activity to delete.

cancellationToken CancellationToken

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

Returns

Task

Remarks

Not all channels support this operation. For channels that don't, this call may throw an exception.

See Also
DeleteActivityAsync(ConversationReference, CancellationToken)

Dispose()

Frees resources.

public void Dispose()

Dispose(bool)

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

Boolean value that determines whether to free resources or not.

OnDeleteActivity(DeleteActivityHandler)

Adds a response handler for delete activity operations.

public ITurnContext OnDeleteActivity(DeleteActivityHandler handler)

Parameters

handler DeleteActivityHandler

The handler to add to the context object.

Returns

ITurnContext

The updated context object.

Remarks

When the context's DeleteActivityAsync(string, CancellationToken) is called, the adapter calls the registered handlers in the order in which they were added to the context object.

Exceptions

ArgumentNullException

handler is null.

See Also
DeleteActivityAsync(ConversationReference, CancellationToken)

OnSendActivities(SendActivitiesHandler)

Adds a response handler for send activity operations.

public ITurnContext OnSendActivities(SendActivitiesHandler handler)

Parameters

handler SendActivitiesHandler

The handler to add to the context object.

Returns

ITurnContext

The updated context object.

Remarks

When the context's SendActivityAsync(IActivity, CancellationToken) or SendActivitiesAsync(IActivity[], CancellationToken) method is called, the adapter calls the registered handlers in the order in which they were added to the context object.

See Also

OnUpdateActivity(UpdateActivityHandler)

Adds a response handler for update activity operations.

public ITurnContext OnUpdateActivity(UpdateActivityHandler handler)

Parameters

handler UpdateActivityHandler

The handler to add to the context object.

Returns

ITurnContext

The updated context object.

Remarks

When the context's UpdateActivityAsync(IActivity, CancellationToken) is called, the adapter calls the registered handlers in the order in which they were added to the context object.

See Also

SendActivitiesAsync(IActivity[], CancellationToken)

Sends a set of activities to the sender of the incoming activity.

public Task<ResourceResponse[]> SendActivitiesAsync(IActivity[] activities, CancellationToken cancellationToken = default)

Parameters

activities IActivity[]

The activities to send.

cancellationToken CancellationToken

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

Returns

Task<ResourceResponse[]>

If the activities are successfully sent, the task result contains an array of Microsoft.Agents.Core.Models.ResourceResponse objects containing the IDs that the receiving channel assigned to the activities.

See Also

SendActivityAsync(IActivity, CancellationToken)

Sends an activity to the sender of the incoming activity.

public Task<ResourceResponse> SendActivityAsync(IActivity activity, CancellationToken cancellationToken = default)

Parameters

activity IActivity

The activity to send.

cancellationToken CancellationToken

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

Returns

Task<ResourceResponse>

If the activity is successfully sent, the task result contains a Microsoft.Agents.Core.Models.ResourceResponse object containing the ID that the receiving channel assigned to the activity.

See Also

SendActivityAsync(string, string, string, CancellationToken)

Sends a message activity to the sender of the incoming activity.

public Task<ResourceResponse> SendActivityAsync(string textReplyToSend, string speak = null, string inputHint = null, CancellationToken cancellationToken = default)

Parameters

textReplyToSend string
speak string

Optional, text to be spoken by your Agent on a speech-enabled channel.

inputHint string

Optional, indicates whether your Agent is accepting, expecting, or ignoring user input after the message is delivered to the client. Microsoft.Agents.Core.Models.InputHints defines the possible values. Default is Microsoft.Agents.Core.Models.InputHints.AcceptingInput.

cancellationToken CancellationToken

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

Returns

Task<ResourceResponse>

If the activity is successfully sent, the task result contains a Microsoft.Agents.Core.Models.ResourceResponse object that contains the ID that the receiving channel assigned to the activity.

See the channel's documentation for limits imposed upon the contents of text.

To control various characteristics of your Agent's speech such as voice, rate, volume, pronunciation, and pitch, specify speak in Speech Synthesis Markup Language (SSML) format.

See Also

TraceActivityAsync(string, object, string, string, CancellationToken)

Sends a trace activity to the IChannelAdapter for logging purposes.

public Task<ResourceResponse> TraceActivityAsync(string name, object value = null, string valueType = null, string label = null, CancellationToken cancellationToken = default)

Parameters

name string

The value to assign to the activity's Microsoft.Agents.Core.Models.Activity.Name property.

value object

The value to assign to the activity's Microsoft.Agents.Core.Models.Activity.Value property.

valueType string

The value to assign to the activity's Microsoft.Agents.Core.Models.Activity.ValueType property.

label string

The value to assign to the activity's Microsoft.Agents.Core.Models.Activity.Label property.

cancellationToken CancellationToken

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

Returns

Task<ResourceResponse>

If the adapter is being hosted in the Emulator, the task result contains a Microsoft.Agents.Core.Models.ResourceResponse object with the original trace activity's ID; otherwise, it contains a Microsoft.Agents.Core.Models.ResourceResponse object containing the ID that the receiving channel assigned to the activity.

UpdateActivityAsync(IActivity, CancellationToken)

Replaces an existing activity.

public Task<ResourceResponse> UpdateActivityAsync(IActivity activity, CancellationToken cancellationToken = default)

Parameters

activity IActivity

New replacement activity.

cancellationToken CancellationToken

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

Returns

Task<ResourceResponse>

If the activity is successfully sent, the task result contains a Microsoft.Agents.Core.Models.ResourceResponse object containing the ID that the receiving channel assigned to the activity.

Before calling this, set the ID of the replacement activity to the ID of the activity to replace.

Not all channels support this operation. For channels that don't, this call may throw an exception.

See Also
DeleteActivityAsync(ConversationReference, CancellationToken)

See Also

IAgent