Class ChannelAdapter

Namespace

Microsoft.Agents.Builder

Assembly

Microsoft.Agents.Builder.dll

This is the base implementation of an IChannelAdapter.

public abstract class ChannelAdapter : IChannelAdapter

Inheritance

object

ChannelAdapter

Implements

IChannelAdapter

Derived

ChannelServiceAdapterBase

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

This would not normally be used by the creator of an Agent except in cases where a custom Adapter is being implemented.

Constructors

ChannelAdapter(ILogger)

public ChannelAdapter(ILogger logger = null)

Parameters

logger ILogger

Fields

InvokeResponseKey

The key value for any InvokeResponseActivity that would be on the TurnState.

public const string InvokeResponseKey = "ChannelAdapterInvokeResponse"

Field Value

string

Properties

MiddlewareSet

Gets the collection of middleware in the adapter's pipeline.

public IMiddlewareSet MiddlewareSet { get; }

Property Value

IMiddlewareSet

The middleware collection for the pipeline.

OnTurnError

Gets or sets an error handler that can catch exceptions in the middleware or application.

public Func<ITurnContext, Exception, Task> OnTurnError { get; set; }

Property Value

Func<ITurnContext, Exception, Task>

An error handler that can catch exceptions in the middleware or application.

Methods

ContinueConversationAsync(ClaimsIdentity, ConversationReference, AgentCallbackHandler, CancellationToken)

Sends a proactive message to a conversation.

public virtual Task ContinueConversationAsync(ClaimsIdentity claimsIdentity, ConversationReference reference, AgentCallbackHandler callback, CancellationToken cancellationToken)

Parameters

claimsIdentity ClaimsIdentity

A ClaimsIdentity for the conversation.

reference ConversationReference

A reference to the conversation to continue.

callback AgentCallbackHandler

The method to call for the resulting Agent turn.

cancellationToken CancellationToken

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

Returns

Task

Remarks

Call this method to proactively send a message to a conversation. Most channels require a user to initiate a conversation with an Agent before the Agent can send activities to the user.

ContinueConversationAsync(ClaimsIdentity, ConversationReference, string, AgentCallbackHandler, CancellationToken)

Sends a proactive message to a conversation.

public virtual Task ContinueConversationAsync(ClaimsIdentity claimsIdentity, ConversationReference reference, string audience, AgentCallbackHandler callback, CancellationToken cancellationToken)

Parameters

claimsIdentity ClaimsIdentity

A ClaimsIdentity for the conversation.

reference ConversationReference

A reference to the conversation to continue.

audience string

A value signifying the recipient of the proactive message.

callback AgentCallbackHandler

The method to call for the resulting Agent turn.

cancellationToken CancellationToken

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

Returns

Task

Remarks

Call this method to proactively send a message to a conversation. Most channels require a user to initiate a conversation with an Agent before the Agent can send activities to the user.

ContinueConversationAsync(ClaimsIdentity, IActivity, AgentCallbackHandler, CancellationToken)

Sends a proactive message to a conversation.

public virtual Task ContinueConversationAsync(ClaimsIdentity claimsIdentity, IActivity continuationActivity, AgentCallbackHandler callback, CancellationToken cancellationToken)

Parameters

claimsIdentity ClaimsIdentity

A ClaimsIdentity for the conversation.

continuationActivity IActivity

An Microsoft.Agents.Core.Models.Activity with the appropriate Microsoft.Agents.Core.Models.ConversationReference with which to continue the conversation.

callback AgentCallbackHandler

The method to call for the resulting Agent 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.

Remarks

Call this method to proactively send a message to a conversation. Most channels require a user to initiate a conversation with an Agent before the Agent can send activities to the user.

ContinueConversationAsync(ClaimsIdentity, IActivity, string, AgentCallbackHandler, CancellationToken)

Sends a proactive message to a conversation.

public virtual Task ContinueConversationAsync(ClaimsIdentity claimsIdentity, IActivity continuationActivity, string audience, AgentCallbackHandler callback, CancellationToken cancellationToken)

Parameters

claimsIdentity ClaimsIdentity

A ClaimsIdentity for the conversation.

continuationActivity IActivity

An Microsoft.Agents.Core.Models.Activity with the appropriate Microsoft.Agents.Core.Models.ConversationReference with which to continue the conversation.

audience string

A value signifying the recipient of the proactive message.

callback AgentCallbackHandler

The method to call for the resulting Agent turn.

cancellationToken CancellationToken

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

Returns

Task

Remarks

Call this method to proactively send a message to a conversation. Most _channels require a user to initiate a conversation with an Agent before the Agent can send activities to the user.

ContinueConversationAsync(string, ConversationReference, AgentCallbackHandler, CancellationToken)

Sends a proactive message to a conversation.

public virtual Task ContinueConversationAsync(string agentId, ConversationReference reference, AgentCallbackHandler callback, CancellationToken cancellationToken)

Parameters

agentId string

The application ID of the Agent.

reference ConversationReference

A reference to the conversation to continue.

callback AgentCallbackHandler

The method to call for the resulting Agent turn.

cancellationToken CancellationToken

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

Returns

Task

Remarks

Call this method to proactively send a message to a conversation. Most _channels require a user to initiate a conversation with an Agent before the Agent can send activities to the user.

ContinueConversationAsync(string, IActivity, AgentCallbackHandler, CancellationToken)

Sends a proactive message to a conversation.

public virtual Task ContinueConversationAsync(string agentId, IActivity continuationActivity, AgentCallbackHandler callback, CancellationToken cancellationToken)

Parameters

agentId string

The application ID of the Agent.

continuationActivity IActivity

An Microsoft.Agents.Core.Models.Activity with the appropriate Microsoft.Agents.Core.Models.ConversationReference with which to continue the conversation.

callback AgentCallbackHandler

The method to call for the resulting Agent turn.

cancellationToken CancellationToken

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

Returns

Task

Remarks

Call this method to proactively send a message to a conversation. Most channels require a user to initiate a conversation with an Agent before the Agent can send activities to the user.

CreateConversationAsync(string, string, string, string, ConversationParameters, AgentCallbackHandler, CancellationToken)

Creates a conversation on the specified channel.

public virtual Task CreateConversationAsync(string agentAppId, string channelId, string serviceUrl, string audience, ConversationParameters conversationParameters, AgentCallbackHandler callback, CancellationToken cancellationToken)

Parameters

agentAppId string

TThe application ID of the Agent.

channelId string

The ID for the channel.

serviceUrl string

The channel's service URL endpoint.

audience string

The audience for the connector.

conversationParameters ConversationParameters

The conversation information to use to create the conversation.

callback AgentCallbackHandler

The method to call for the resulting Agent turn.

cancellationToken CancellationToken

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

Returns

Task

Remarks

To start a conversation, your Agent must know its account information and the user's account information on that channel. Most channels only support initiating a direct message (non-group) conversation.

The adapter attempts to create a new conversation on the channel, and then sends a conversationUpdate Activity through its middleware pipeline to the callback method.

If the conversation is established with the specified users, the ID of the activity's Microsoft.Agents.Core.Models.Activity.Conversation will contain the ID of the new conversation.

DeleteActivityAsync(ITurnContext, ConversationReference, CancellationToken)

When overridden in a derived class, deletes an existing activity in the conversation.

public virtual Task DeleteActivityAsync(ITurnContext turnContext, ConversationReference reference, CancellationToken cancellationToken)

Parameters

turnContext ITurnContext

The context object for the turn.

reference ConversationReference

Conversation reference for 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

The Microsoft.Agents.Core.Models.ConversationReference.ActivityId of the conversation reference identifies the activity to delete.

See Also

OnDeleteActivity(DeleteActivityHandler)

ProcessActivityAsync(ClaimsIdentity, IActivity, AgentCallbackHandler, CancellationToken)

Creates a turn context and runs the middleware pipeline for an incoming TRUSTED activity.

public virtual Task<InvokeResponse> ProcessActivityAsync(ClaimsIdentity claimsIdentity, IActivity activity, AgentCallbackHandler callback, CancellationToken cancellationToken)

Parameters

claimsIdentity ClaimsIdentity

A ClaimsIdentity for the request.

activity IActivity

The incoming activity.

callback AgentCallbackHandler

The code to run at the end of the adapter's middleware pipeline.

cancellationToken CancellationToken

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

Returns

Task<InvokeResponse>

If an Invoke Activity was received, an Microsoft.Agents.Core.Models.InvokeResponse, otherwise null.

ProcessProactiveAsync(ClaimsIdentity, IActivity, IAgent, CancellationToken, string)

public virtual Task ProcessProactiveAsync(ClaimsIdentity claimsIdentity, IActivity continuationActivity, IAgent agent, CancellationToken cancellationToken, string audience = null)

Parameters

claimsIdentity ClaimsIdentity

continuationActivity IActivity

agent IAgent

cancellationToken CancellationToken

audience string

Returns

Task

ProcessProactiveAsync(ClaimsIdentity, IActivity, string, AgentCallbackHandler, CancellationToken)

The implementation for continue conversation.

public virtual Task ProcessProactiveAsync(ClaimsIdentity claimsIdentity, IActivity continuationActivity, string audience, AgentCallbackHandler callback, CancellationToken cancellationToken)

Parameters

claimsIdentity ClaimsIdentity

A ClaimsIdentity for the conversation.

continuationActivity IActivity

The continuation Microsoft.Agents.Core.Models.Activity used to create the ITurnContext.

audience string

The audience for the call.

callback AgentCallbackHandler

The method to call for the resulting Agent turn.

cancellationToken CancellationToken

Cancellation token.

Returns

Task

RunPipelineAsync(ITurnContext, AgentCallbackHandler, CancellationToken)

Starts activity processing for the current Agent turn.

protected Task RunPipelineAsync(ITurnContext turnContext, AgentCallbackHandler callback, CancellationToken cancellationToken)

Parameters

turnContext ITurnContext

The turn's context object.

callback AgentCallbackHandler

A callback method to run at the end of the pipeline.

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

The adapter calls middleware in the order in which you added it. The adapter passes in the context object for the turn and a next delegate, and the middleware calls the delegate to pass control to the next middleware in the pipeline. Once control reaches the end of the pipeline, the adapter calls the callback method. If a middleware component doesn't call the next delegate, the adapter does not call any of the subsequent middleware’s OnTurnAsync(ITurnContext, NextDelegate, CancellationToken) methods or the callback method, and the pipeline short circuits.

When the turn is initiated by a user activity (reactive messaging), the callback method will be a reference to the Agent's OnTurnAsync(ITurnContext, CancellationToken) method. When the turn is initiated by a call to ContinueConversationAsync(string, ConversationReference, AgentCallbackHandler, CancellationToken) (proactive messaging), the callback method is the callback method that was provided in the call.

Exceptions

ArgumentNullException

turnContext is null.

SendActivitiesAsync(ITurnContext, IActivity[], CancellationToken)

When overridden in a derived class, sends activities to the conversation.

public abstract Task<ResourceResponse[]> SendActivitiesAsync(ITurnContext turnContext, IActivity[] activities, CancellationToken cancellationToken)

Parameters

turnContext ITurnContext

The context object for the turn.

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

OnSendActivities(SendActivitiesHandler)

UpdateActivityAsync(ITurnContext, IActivity, CancellationToken)

When overridden in a derived class, replaces an existing activity in the conversation.

public virtual Task<ResourceResponse> UpdateActivityAsync(ITurnContext turnContext, IActivity activity, CancellationToken cancellationToken)

Parameters

turnContext ITurnContext

The context object for the turn.

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.

See Also

OnUpdateActivity(UpdateActivityHandler)

Use(IMiddleware)

Adds middleware to the adapter's pipeline.

public IChannelAdapter Use(IMiddleware middleware)

Parameters

middleware IMiddleware

The middleware to add.

Returns

IChannelAdapter

The updated adapter object.

Remarks

Middleware is added to the adapter at initialization time. For each turn, the adapter calls middleware in the order in which you added it.