agents-sdk-dotnet-activityhandler-migration

Agents SDK ActivityHandler → AgentApplication Migration (.NET)

Overview

Upgrades a bot from the ActivityHandler compat layer to the modern AgentApplication routing pattern. This is ONLY for DotNet projects that already use Microsoft.Agents.* packages. If the project is still using Microsoft.Bot.* packages the bf-to-agents-sdk-dotnet-migration skill should be used first.

Two entry points:

• Standalone: The bot already uses Microsoft.Agents.* packages, namespaces, and appsettings — focus is on the bot class, Program.cs, and endpoint mapping.
• Second step after bf-to-agents-sdk-dotnet-migration: Packages, namespaces, and appsettings were converted in that step — this skill handles the AgentApplication conversion.

---

What Does NOT Need to Change

Verify each of these is already correct — do not modify unless broken:

Item	Expected State
Namespaces in bot class	Already Microsoft.Agents.* — only remove compat namespaces
appsettings.json	Already has Connections + TokenValidation sections
builder.Services.AddAgentAspNetAuthentication(...)	Already present — keep
AspNetExtensions.cs (if present)	Sample-provided auth helper — keep as-is
Custom DI in Program.cs	Preserve dialogs, adapters, custom services — but remove ConversationState and UserState (see Step 2)

⚠️ If beta packages are required: Tell the user explicitly: "This migration uses pre-release (-beta) Agents SDK packages, which are nightly builds and not suitable for production. Upgrade to a stable release before deploying."

---

Handler Mapping: ActivityHandler → AgentApplication

ActivityHandler Override	AgentApplication Registration
OnMessageActivityAsync(ITurnContext<IMessageActivity>, CT)	OnActivity(ActivityTypes.Message, handler, rank: RouteRank.Last)
OnMembersAddedAsync(IList<ChannelAccount>, ITurnContext<IConversationUpdateActivity>, CT)	OnConversationUpdate(ConversationUpdateEvents.MembersAdded, handler)
OnMembersRemovedAsync(...)	OnConversationUpdate(ConversationUpdateEvents.MembersRemoved, handler)
OnMessageUpdateActivityAsync(...)	OnActivity(ActivityTypes.MessageUpdate, handler)
OnMessageDeleteActivityAsync(...)	OnActivity(ActivityTypes.MessageDelete, handler)
OnReactionsAddedAsync(IList<MessageReaction>, ...)	OnMessageReactionsAdded(handler)
OnReactionsRemovedAsync(IList<MessageReaction>, ...)	OnMessageReactionsRemoved(handler)
OnEventAsync(ITurnContext<IEventActivity>, CT)	OnEvent(eventName, handler) or OnActivity(ActivityTypes.Event, handler)
OnInvokeActivityAsync(...) with adaptiveCard/action + verb switch	AdaptiveCards.OnActionExecute(verb, handler) — one registration per verb (preferred)
OnInvokeActivityAsync(...) with application/search	AdaptiveCards.OnSearch(dataset, handler) — one registration per choices.data.dataset value
OnInvokeActivityAsync(...) (other invoke types)	OnActivity(ActivityTypes.Invoke, handler)
OnTurnAsync(...) override (cross-cutting)	OnBeforeTurn(handler) / OnAfterTurn(handler)
OnInstallationUpdateActivityAsync(...)	OnActivity(ActivityTypes.InstallationUpdate, handler)
OnEndOfConversationActivityAsync(...)	OnActivity(ActivityTypes.EndOfConversation, handler)

Key difference: Handler signature changes from (ITurnContext<T>, CT) to (ITurnContext, ITurnState, CT). membersAdded, membersRemoved, messageReactions are no longer separate parameters — access via turnContext.Activity.*.

adaptiveCard/action invokes → AdaptiveCards.OnActionExecute

If the bot overrides OnInvokeActivityAsync and switches on a verb from adaptiveCard/action activities, replace it with per-verb AdaptiveCards.OnActionExecute registrations. AdaptiveCards is a property on AgentApplication (no RegisterExtension needed):

// Before: one OnInvokeActivityAsync with switch(verb)
protected override async Task<InvokeResponse> OnInvokeActivityAsync(ITurnContext<IInvokeActivity> ctx, CancellationToken ct)
{
    if (ctx.Activity.Name == "adaptiveCard/action")
    {
        var wrapper = JsonSerializer.Deserialize<AdaptiveCardInvokeValue>(ctx.Activity.Value.ToString());
        switch (wrapper.Action.Verb)
        {
            case "approve": return CreateInvokeResponse(GetApproveCard(wrapper.Action.Data));
            case "reject":  return CreateInvokeResponse(GetRejectCard(wrapper.Action.Data));
        }
    }
    return null;
}

// After: one registration per verb — framework filters and extracts action.data
public MyBot(AgentApplicationOptions options) : base(options)
{
    AdaptiveCards.OnActionExecute("approve", OnApproveAsync);
    AdaptiveCards.OnActionExecute("reject",  OnRejectedAsync);
}

// Handler receives action.data directly — NOT the full AdaptiveCardInvokeValue
// Return AdaptiveCardInvokeResponse directly — no CreateInvokeResponse() wrapper
private Task<AdaptiveCardInvokeResponse> OnApproveAsync(
    ITurnContext turnContext, ITurnState turnState, object data, CancellationToken ct)
{
    var actionData = ProtocolJsonSerializer.ToObject<MyDataModel>(data);  // data == action.data
    return Task.FromResult(new AdaptiveCardInvokeResponse
    {
        StatusCode = 200,
        Type = "application/vnd.microsoft.card.adaptive",
        Value = BuildCard(actionData)
    });
}

Key points:

• data parameter = invokeValue.Action.Data — deserialize as your data model, not as AdaptiveCardInvokeValue
• Return AdaptiveCardInvokeResponse directly — the framework wraps it in an InvokeResponse automatically
• CreateInvokeResponse() is a compat-layer helper that does not exist on AgentApplication
• Namespace: using Microsoft.Agents.Builder.App.AdaptiveCards;

---

Step 1-a: Convert Bot Class to AgentApplication (not using Dialogs)

• Remove using Microsoft.Agents.Builder.Compat; (ActivityHandler namespace)
• Remove using Microsoft.Agents.Extensions.Teams.Compat; (TeamsActivityHandler namespace)
• Keep all other using Microsoft.Agents.* statements — they are already correct

// Before: ActivityHandler compat layer
using Microsoft.Agents.Builder.Compat;         // REMOVE
using Microsoft.Agents.Extensions.Teams.Compat; // REMOVE if Teams
using Microsoft.Agents.Builder;
using Microsoft.Agents.Core.Models;

public class EchoBot : ActivityHandler  // or TeamsActivityHandler
{
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken ct)
    { /* business logic */
    }
}

// After: AgentApplication
using Microsoft.Agents.Builder;
using Microsoft.Agents.Builder.App;
using Microsoft.Agents.Core.Models;

public class EchoBot : AgentApplication
{
    public EchoBot(AgentApplicationOptions options) : base(options)
    {
        OnConversationUpdate(ConversationUpdateEvents.MembersAdded, OnMembersAddedAsync);
        OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last);
    }

    // Signature: (ITurnContext, ITurnState, CancellationToken)
    private async Task OnMessageAsync(ITurnContext ctx, ITurnState state, CancellationToken ct)
    { /* same business logic */ }
}

For Teams bots (TeamsActivityHandler) with Teams-specific handlers (messaging extensions, task modules, etc.), see Step 1-d below.

Step 1-b: Convert Bot Class to AgentApplication (using Dialogs)

• Remove using Microsoft.Agents.Builder.Compat; (ActivityHandler namespace)
• Remove using Microsoft.Agents.Extensions.Teams.Compat; (TeamsActivityHandler namespace)
• Keep all other using Microsoft.Agents.* statements — they are already correct

// Before: ActivityHandler compat layer
using Microsoft.Agents.Builder.Compat;         // REMOVE
using Microsoft.Agents.Builder;
using Microsoft.Agents.Builder.State;
using Microsoft.Agents.Core.Models;

public class EchoBot : ActivityHandler
{
    protected override Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken ct)
        => dialog.RunAsync(turnContext, conversationState, ct);
}

// After: AgentApplication
using Microsoft.Agents.Builder;
using Microsoft.Agents.Builder.App;
using Microsoft.Agents.Builder.State;
using Microsoft.Agents.Core.Models;

public class EchoBot : AgentApplication
{
    public EchoBot(AgentApplicationOptions options, MainDialog dialog) : base(options)
    {
        _dialog = dialog;
        OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last);
        // signin/verifyState and signin/tokenExchange are both matched by "signin/.*"
        OnActivity(
            (ctx, ct) => Task.FromResult(ctx.Activity.IsType(ActivityTypes.Invoke) && ctx.Activity.Name != null && Regex.IsMatch(ctx.Activity.Name, "signin/.*")),
            OnSigninInvokeStateAsync);
    }

    // Signature: (ITurnContext, ITurnState, CancellationToken) — NOT the ActivityHandler signature
    private Task OnMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken ct)
        => _dialog.RunAsync(turnContext, turnState.Conversation, ct);

    private Task OnSigninInvokeStateAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken ct)
        => _dialog.RunAsync(turnContext, turnState.Conversation, ct);
}

Key differences from non-dialog migration:

• Do not inject ConversationState into the bot — pass turnState.Conversation to Dialog.RunAsync instead
• Use InvokeRouteBuilder (not OnActivity(ActivityTypes.Invoke, ...)) to route signin invokes — the name pattern matches both signin/verifyState and signin/tokenExchange
• Remove ConversationState and UserState from DI entirely — see Step 2

⚠️ Generic DialogBot<T> base class pattern: Some projects use a two-level class hierarchy where a generic base class (e.g. DialogBot<T> : ActivityHandler) holds the dialog field, state injection, and OnTurnAsync state-saving override, and the concrete bot class (e.g. MyBot : DialogBot<MainDialog>) only adds routing. Collapse both classes into a single non-generic AgentApplication subclass — inject the concrete dialog type directly in the constructor. The generic type parameter is not needed. Remove OnTurnAsync entirely (AgentApplication manages state automatically).

---

Step 1-c: Remove State Management Boilerplate

Remove OnTurnBeginAsync / OnTurnEndAsync Overrides

ActivityHandler and TeamsActivityHandler bots sometimes manually load and save state in turn lifecycle overrides. Remove these entirely — AgentApplication handles state loading and saving automatically:

// REMOVE these overrides completely — AgentApplication does this automatically
protected override async Task OnTurnBeginAsync(ITurnContext turnContext, CancellationToken cancellationToken = default)
{
    await ConversationState.LoadAsync(turnContext, false, cancellationToken);
    await UserState.LoadAsync(turnContext, false, cancellationToken);
}

protected override async Task OnTurnEndAsync(ITurnContext turnContext, CancellationToken cancellationToken = default)
{
    await ConversationState.SaveChangesAsync(turnContext, false, cancellationToken);
    await UserState.SaveChangesAsync(turnContext, false, cancellationToken);
}

Also remove any ConversationState or UserState properties/fields that were injected for this purpose.

Migrate CloudAdapter OnTurnError to AgentApplication

If a custom CloudAdapter subclass injects ConversationState only to call DeleteStateAsync on error, move that logic to an AgentApplication.OnTurnError handler instead.

Before — in the custom adapter:

public MyAdapter(
    IChannelServiceClientFactory channelServiceClientFactory,
    IActivityTaskQueue activityTaskQueue,
    ILogger<CloudAdapter> logger,
    ConversationState conversationState)   // REMOVE this parameter
    : base(channelServiceClientFactory, activityTaskQueue, logger: logger)
{
    OnTurnError = async (turnContext, exception) =>
    {
        if (conversationState != null)
        {
            await conversationState.DeleteStateAsync(turnContext);  // REMOVE
        }
    };
}

After — remove ConversationState from the adapter:

public MyAdapter(
    IChannelServiceClientFactory channelServiceClientFactory,
    IActivityTaskQueue activityTaskQueue,
    ILogger<CloudAdapter> logger)
    : base(channelServiceClientFactory, activityTaskQueue, logger: logger)
{
    // OnTurnError can remain for logging; state deletion moves to AgentApplication
}

Add to the AgentApplication bot constructor:

public MyBot(AgentApplicationOptions options, ...) : base(options)
{
    OnTurnError(OnAgentTurnErrorAsync);
    // ... other route registrations
}

private async Task OnAgentTurnErrorAsync(ITurnContext turnContext, ITurnState turnState, Exception exception, CancellationToken cancellationToken)
{
    try
    {
        await turnState.Conversation.DeleteStateAsync(turnContext, cancellationToken);
    }
    catch(Exception ex)
    {
        Logger.LogError(ex, "Exception deleting conversation state after a turn error.");
    }
}

Customer-written classes that accept ConversationState or UserState as constructor parameters can remain unchanged for now. However, they will ultimately need to source their state from ITurnState.Conversation or ITurnState.User — flag this to the customer as a follow-up item.

application/search invokes → AdaptiveCards.OnSearch

If the bot overrides OnInvokeActivityAsync and handles activity.Name == "application/search" (adaptive card typeahead/dynamic search), replace it with per-dataset AdaptiveCards.OnSearch registrations. The dataset name comes from choices.data.dataset in the card JSON. The handler returns IList<AdaptiveCardsSearchResult> — the framework automatically wraps results in the application/vnd.microsoft.search.searchResponse format and sends the invoke response.

// Before: one OnInvokeActivityAsync checking activity.Name
protected override async Task<InvokeResponse> OnInvokeActivityAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken ct)
{
    if (turnContext.Activity.Name == "application/search")
    {
        var searchData = JsonSerializer.Deserialize<DynamicSearchCard>(turnContext.Activity.Value.ToString());
        // ... build results ...
        return new InvokeResponse { Status = 200, Body = searchResponseData };
    }
    return null;
}

// After: per-dataset OnSearch registrations
public ActivityBot(AgentApplicationOptions options) : base(options)
{
    AdaptiveCards.OnSearch("npmpackages", OnNpmSearchAsync);
    AdaptiveCards.OnSearch("cities", OnCitiesSearchAsync);
}

// Handler signature: (ITurnContext, ITurnState, Query<AdaptiveCardsSearchParams>, CT) → Task<IList<AdaptiveCardsSearchResult>>
private async Task<IList<AdaptiveCardsSearchResult>> OnNpmSearchAsync(
    ITurnContext turnContext, ITurnState turnState, Query<AdaptiveCardsSearchParams> query, CancellationToken ct)
{
    // query.Parameters.QueryText = search text typed by user
    // query.Parameters.Dataset  = "npmpackages"
    // ... fetch results ...
    return results.Select(r => new AdaptiveCardsSearchResult(r.Title, r.Value)).ToList();
}

Key differences:

• Return IList<AdaptiveCardsSearchResult> directly — no InvokeResponse wrapper
• AdaptiveCardsSearchResult(string title, string value) — constructor takes title and value
• query.Parameters.QueryText replaces searchData.queryText
• query.Parameters.Dataset contains the dataset name (same as the registration key)

⚠️ Dependent dropdown — associated inputs not in query: When a card uses "associatedInputs": "auto", the selected values of other inputs are sent in the data field of the raw invoke payload — NOT in query.Parameters. Access them directly: ProtocolJsonSerializer.ToObject<MyModel>(turnContext.Activity.Value) where MyModel maps the top-level data field.

private Task<IList<AdaptiveCardsSearchResult>> OnCitiesSearchAsync(
    ITurnContext turnContext, ITurnState turnState, Query<AdaptiveCardsSearchParams> query, CancellationToken ct)
{
    // Associated input (country selector) arrives in activity.Value's "data" field
    var card = ProtocolJsonSerializer.ToObject<DependantDropdownCard>(turnContext.Activity.Value);
    string country = card?.data?.choiceSelect?.ToLower() ?? "";
    // ... return cities for country ...
}

---

Step 1-d: Convert TeamsActivityHandler with Teams-Specific Handlers

For bots that override Teams-specific methods (messaging extensions, task modules, etc.), use RegisterExtension(new TeamsAgentExtension(this), ...) inside the constructor.

TeamsActivityHandler → TeamsAgentExtension handler mapping

Message Extensions — handlers return Task<MessagingExtensionResult> (not MessagingExtensionResponse):

TeamsActivityHandler Override	TeamsAgentExtension Registration	Handler Delegate
OnTeamsMessagingExtensionQueryAsync(ctx, MessagingExtensionQuery, CT)	teams.MessageExtensions.OnQuery(commandId, handler)	(ITurnContext, ITurnState, Query<IDictionary<string,object>>, CT) → Task<MessagingExtensionResult>
OnTeamsMessagingExtensionSelectItemAsync(ctx, JsonElement, CT)	teams.MessageExtensions.OnSelectItem(handler)	(ITurnContext, ITurnState, object item, CT) → Task<MessagingExtensionResult>
OnTeamsAppBasedLinkQueryAsync(ctx, AppBasedLinkQuery, CT)	teams.MessageExtensions.OnQueryLink(handler)	(ITurnContext, ITurnState, string url, CT) → Task<MessagingExtensionResult>
OnTeamsAnonymousAppBasedLinkQueryAsync(ctx, AppBasedLinkQuery, CT)	teams.MessageExtensions.OnAnonymousQueryLink(handler)	(ITurnContext, ITurnState, string url, CT) → Task<MessagingExtensionResult>
OnTeamsMessagingExtensionFetchTaskAsync(ctx, MessagingExtensionAction, CT)	teams.MessageExtensions.OnFetchTask(commandId, handler)	(ITurnContext, ITurnState, CT) → Task<TaskModuleResponse>
OnTeamsMessagingExtensionSubmitActionAsync(ctx, MessagingExtensionAction, CT)	teams.MessageExtensions.OnSubmitAction(commandId, handler)	(ITurnContext, ITurnState, object data, CT) → Task<MessagingExtensionActionResponse>
OnTeamsMessagingExtensionAgentMessagePreviewEditAsync(ctx, MessagingExtensionAction, CT)	teams.MessageExtensions.OnAgentMessagePreviewEdit(commandId, handler)	(ITurnContext, ITurnState, IActivity activityPreview, CT) → Task<MessagingExtensionActionResponse>
OnTeamsMessagingExtensionAgentMessagePreviewSendAsync(ctx, MessagingExtensionAction, CT)	teams.MessageExtensions.OnAgentMessagePreviewSend(commandId, handler)	(ITurnContext, ITurnState, IActivity activityPreview, CT) → Task
OnTeamsMessagingExtensionConfigurationQuerySettingUrlAsync(ctx, MessagingExtensionQuery, CT)	teams.MessageExtensions.OnQueryUrlSetting(handler)	(ITurnContext, ITurnState, CT) → Task<MessagingExtensionResult>
OnTeamsMessagingExtensionConfigurationSettingAsync(ctx, JsonElement, CT)	teams.MessageExtensions.OnConfigureSettings(handler)	(ITurnContext, ITurnState, object settings, CT) → Task
OnTeamsMessagingExtensionCardButtonClickedAsync(ctx, JsonElement, CT)	teams.MessageExtensions.OnCardButtonClicked(handler)	(ITurnContext, ITurnState, object cardData, CT) → Task

Task Modules:

TeamsActivityHandler Override	TeamsAgentExtension Registration	Handler Delegate
OnTeamsTaskModuleFetchAsync(ctx, TaskModuleRequest, CT)	teams.TaskModules.OnFetch(verb, handler)	(ITurnContext, ITurnState, object data, CT) → Task<TaskModuleResponse>
OnTeamsTaskModuleSubmitAsync(ctx, TaskModuleRequest, CT)	teams.TaskModules.OnSubmit(verb, handler)	(ITurnContext, ITurnState, object data, CT) → Task<TaskModuleResponse>

⚠️ Task Module verb matching: OnFetch and OnSubmit match by looking for a verb field inside activity.Value.data. If the submitted data has no verb field, use the RouteSelector overload instead:

teams.TaskModules.OnSubmit(
    (ctx, ct) => Task.FromResult(
        string.Equals(ctx.Activity.Type, ActivityTypes.Invoke, StringComparison.OrdinalIgnoreCase) &&
        string.Equals(ctx.Activity.Name, "task/submit", StringComparison.OrdinalIgnoreCase)),
    OnTaskModuleSubmitAsync);

⚠️ data parameter in submit handler: The data parameter passed to SubmitHandlerAsync is taskModuleAction.Value from a CardAction deserialization of the payload. For task/submit payloads where the top-level JSON has no "value" key (only "data" and "context"), this will be null. Access the submitted data via turnContext.Activity.Value directly:

private async Task<TaskModuleResponse> OnTaskModuleSubmitAsync(
    ITurnContext turnContext, ITurnState turnState, object data, CancellationToken cancellationToken)
{
    // data parameter is null when payload has no top-level "value" key — use Activity.Value instead
    var request = ProtocolJsonSerializer.ToObject<TaskModuleRequest>(turnContext.Activity.Value);
    var feedback = ProtocolJsonSerializer.ToObject<MySubmitModel>(request.Data);
    // ...
    return null; // null dismisses the task module
}

Meetings:

TeamsActivityHandler Override	TeamsAgentExtension Registration	Handler Delegate
OnTeamsMeetingStartAsync(MeetingStartEventDetails, ctx, CT)	teams.Meetings.OnStart(handler)	(ITurnContext, ITurnState, MeetingStartEventDetails, CT) → Task
OnTeamsMeetingEndAsync(MeetingEndEventDetails, ctx, CT)	teams.Meetings.OnEnd(handler)	(ITurnContext, ITurnState, MeetingEndEventDetails, CT) → Task
OnTeamsMeetingParticipantsJoinAsync(MeetingParticipantsEventDetails, ctx, CT)	teams.Meetings.OnParticipantsJoin(handler)	(ITurnContext, ITurnState, MeetingParticipantsEventDetails, CT) → Task
OnTeamsMeetingParticipantsLeaveAsync(MeetingParticipantsEventDetails, ctx, CT)	teams.Meetings.OnParticipantsLeave(handler)	(ITurnContext, ITurnState, MeetingParticipantsEventDetails, CT) → Task

Messages (edit/delete):

TeamsActivityHandler Override	TeamsAgentExtension Registration
OnTeamsMessageEditAsync(ctx, CT)	teams.OnMessageEdit(handler)
OnTeamsMessageUndeleteAsync(ctx, CT)	teams.OnMessageUndelete(handler)
OnTeamsMessageSoftDeleteAsync(ctx, CT)	teams.OnMessageDelete(handler)
OnTeamsReadReceiptAsync(ReadReceiptInfo, ctx, CT)	teams.OnTeamsReadReceipt(handler)

File Consent:

TeamsActivityHandler Override	TeamsAgentExtension Registration
OnTeamsFileConsentAcceptAsync(ctx, FileConsentCardResponse, CT)	teams.OnFileConsentAccept(handler)
OnTeamsFileConsentDeclineAsync(ctx, FileConsentCardResponse, CT)	teams.OnFileConsentDecline(handler)

Bot Config:

TeamsActivityHandler Override	TeamsAgentExtension Registration
OnTeamsConfigFetchAsync(ctx, JsonElement, CT)	teams.OnConfigFetch(handler)
OnTeamsConfigSubmitAsync(ctx, JsonElement, CT)	teams.OnConfigSubmit(handler)

Channels, Teams, Members — all route through teams.OnConversationUpdate(eventName, handler) with constants from TeamsConversationUpdateEvents:

TeamsActivityHandler Override	Event Constant
OnTeamsMembersAddedAsync	ConversationUpdateEvents.MembersAdded
OnTeamsMembersRemovedAsync	ConversationUpdateEvents.MembersRemoved
OnTeamsChannelCreatedAsync	TeamsConversationUpdateEvents.ChannelCreated
OnTeamsChannelDeletedAsync	TeamsConversationUpdateEvents.ChannelDeleted
OnTeamsChannelRenamedAsync	TeamsConversationUpdateEvents.ChannelRenamed
OnTeamsChannelRestoredAsync	TeamsConversationUpdateEvents.ChannelRestored
OnTeamsTeamArchivedAsync	TeamsConversationUpdateEvents.TeamArchived
OnTeamsTeamUnarchivedAsync	TeamsConversationUpdateEvents.TeamUnarchived
OnTeamsTeamDeletedAsync	TeamsConversationUpdateEvents.TeamDeleted
OnTeamsTeamHardDeletedAsync	TeamsConversationUpdateEvents.TeamHardDeleted
OnTeamsTeamRenamedAsync	TeamsConversationUpdateEvents.TeamRenamed
OnTeamsTeamRestoredAsync	TeamsConversationUpdateEvents.TeamRestored

Other:

TeamsActivityHandler Override	TeamsAgentExtension Registration
OnTeamsO365ConnectorCardActionAsync(ctx, O365ConnectorCardActionQuery, CT)	teams.OnO365ConnectorCardAction(handler)
OnTeamsSigninVerifyStateAsync(ctx, CT)	On AgentApplication directly: OnActivity((ctx, ct) => Task.FromResult(ctx.Activity.IsType(ActivityTypes.Invoke) && Regex.IsMatch(ctx.Activity.Name, "signin/.*")), handler)
OnTeamsTabFetchAsync(ctx, TabRequest, CT)	No direct equivalent — use OnActivity(ActivityTypes.Invoke, handler) with a name filter
OnTeamsTabSubmitAsync(ctx, TabSubmit, CT)	No direct equivalent — use OnActivity(ActivityTypes.Invoke, handler) with a name filter

Handler signature changes

Query handler — return type changes from Task<MessagingExtensionResponse> to Task<MessagingExtensionResult>:

// Before
protected override async Task<MessagingExtensionResponse> OnTeamsMessagingExtensionQueryAsync(
    ITurnContext<IInvokeActivity> turnContext, MessagingExtensionQuery query, CancellationToken ct)
{
    var text = query?.Parameters?[0]?.Value?.ToString();  // index-based parameter access
    // ...
    return new MessagingExtensionResponse { ComposeExtension = new MessagingExtensionResult { ... } };
}

// After — registered as: teams.MessageExtensions.OnQuery("commandId", OnQueryAsync)
private async Task<MessagingExtensionResult> OnQueryAsync(
    ITurnContext turnContext, ITurnState turnState,
    Query<IDictionary<string, object>> query, CancellationToken ct)
{
    // Named parameter access — value is a JsonElement
    string text = string.Empty;
    if (query.Parameters.TryGetValue("paramName", out var val) && val is JsonElement el)
        text = el.GetString() ?? string.Empty;
    // ...
    return new MessagingExtensionResult { Type = "result", AttachmentLayout = "list", Attachments = attachments };
    // NOTE: return MessagingExtensionResult directly — no MessagingExtensionResponse wrapper
}

SelectItem handler — item is now object (cast to JsonElement):

// Before
protected override Task<MessagingExtensionResponse> OnTeamsMessagingExtensionSelectItemAsync(
    ITurnContext<IInvokeActivity> turnContext, JsonElement query, CancellationToken ct)
{
    string id = query.GetProperty("packageId").GetString();
    return Task.FromResult(new MessagingExtensionResponse { ComposeExtension = new MessagingExtensionResult { ... } });
}

// After — registered as: teams.MessageExtensions.OnSelectItem(OnSelectItemAsync)
private Task<MessagingExtensionResult> OnSelectItemAsync(
    ITurnContext turnContext, ITurnState turnState, object item, CancellationToken ct)
{
    JsonElement query = (JsonElement)item;
    string id = query.GetProperty("packageId").GetString();
    return Task.FromResult(new MessagingExtensionResult { Type = "result", ... });
    // NOTE: return MessagingExtensionResult directly — no MessagingExtensionResponse wrapper
}

Full registration pattern

using Microsoft.Agents.Builder.App;             // AgentApplication
using Microsoft.Agents.Builder.App.AdaptiveCards; // Query<T>
using Microsoft.Agents.Builder.State;            // ITurnState
using Microsoft.Agents.Extensions.Teams.App;    // TeamsAgentExtension
using Microsoft.Agents.Extensions.Teams.Models; // MessagingExtensionResult, etc.
// REMOVE: using Microsoft.Agents.Extensions.Teams.Compat;

public class MyTeamsBot : AgentApplication
{
    public MyTeamsBot(AgentApplicationOptions options) : base(options)
    {
        RegisterExtension(new TeamsAgentExtension(this), teams =>
        {
            teams.MessageExtensions.OnQuery("searchCommandId", OnQueryAsync);
            teams.MessageExtensions.OnSelectItem(OnSelectItemAsync);
        });
    }
}

Key differences:

• Helper methods that returned MessagingExtensionResponse must be changed to return MessagingExtensionResult — drop the outer new MessagingExtensionResponse { ComposeExtension = ... } wrapper
• MessagingExtensionQuery.Parameters[index].Value → Query<IDictionary<string,object>>.Parameters.TryGetValue("name", out var val) where val is a JsonElement
• commandId in OnQuery(commandId, ...) must match the command id in the Teams app manifest

---

Step 2: Update Program.cs

Add AddAgentApplicationOptions

Add this call before builder.AddAgent<T>() — it is required for AgentApplication and was absent in ActivityHandler-based bots:

builder.AddAgentApplicationOptions();  // ADD THIS — required for AgentApplication
builder.AddAgent<EchoBot>();           // existing line — keep

Ensure IStorage Is Registered

AgentApplication always requires an IStorage registration — even if the bot has no dialogs or explicit state usage. If it is not already present, add it:

builder.Services.AddSingleton<IStorage, MemoryStorage>(); // always required by AgentApplication

Remove ConversationState and UserState from DI

AgentApplication manages state internally via ITurnState. Remove these registrations entirely:

// REMOVE both of these — AgentApplication does not use them
// builder.Services.AddSingleton<ConversationState>();
// builder.Services.AddSingleton<UserState>();

builder.Services.AddSingleton<IStorage, MemoryStorage>(); // keep — required by AgentApplication
builder.Services.AddSingleton<MainDialog>();               // keep — dialog class itself is still needed
builder.Services.AddSingleton<IMyService, MyService>();    // keep all custom services

Preserve All Other Custom DI

Keep dialogs, storage, adapters, and custom services. Only ConversationState and UserState are removed.

TeamsSSOTokenExchangeMiddleware

If the ActivityHandler bot registered TeamsSSOTokenExchangeMiddleware, remove it — it is not required and should not be used with AgentApplication. Remove it from DI and from any IMiddleware[] array registration.

---

Step 3: Update Endpoint Mapping

Identify which endpoint pattern the existing bot uses, then apply the corresponding change.

Pattern A: app.MapControllers() + BotController.cs (most common in Agents SDK compat samples)

// Before Program.cs
builder.Services.AddControllers();           // needed for MapControllers
// ...
app.MapControllers().AllowAnonymous();       // dev
app.MapControllers();                        // prod

// After Program.cs
// Remove AddControllers() ONLY IF no other MVC controllers exist in the project
// Add authentication middleware if not already present:
app.UseAuthentication();
app.UseAuthorization();
app.MapAgentRootEndpoint();                                              // optional GET "/"
app.MapAgentApplicationEndpoints(requireAuth: !app.Environment.IsDevelopment());

Delete BotController.cs. Check first that it contains no custom logic beyond calling adapter.ProcessAsync — if it does, preserve that logic.

If the project uses Razor Pages (AddRazorPages() / MapRazorPages()): keep both — they serve web UI pages unrelated to the bot endpoint. Remove AddControllers(), AddMvc(), and any MapControllerRoute() / MapControllers() calls, but leave the Razor Pages registrations in place:

// Keep — serves Razor Pages for web UI
builder.Services.AddRazorPages();
// ...
app.UseAuthentication();
app.UseAuthorization();
app.MapRazorPages();                   // keep
app.MapAgentRootEndpoint();
app.MapAgentApplicationEndpoints(requireAuth: !app.Environment.IsDevelopment());

Also remove the dev branch app.MapControllers().AllowAnonymous() pattern — auth is now handled by requireAuth on MapAgentApplicationEndpoints.

Pattern B: app.MapAgentEndpoints()

// Before
app.MapAgentEndpoints(requireAuth: !app.Environment.IsDevelopment());

// After
app.MapAgentRootEndpoint();
app.MapAgentApplicationEndpoints(requireAuth: !app.Environment.IsDevelopment());

Pattern C: app.MapPost(...) (older minimal API)

Offer to switch. If accepted:

// Remove:
app.MapPost("/api/messages", async (HttpRequest req, HttpResponse res, IAgentHttpAdapter adapter, IAgent bot, CancellationToken ct)
    => await adapter.ProcessAsync(req, res, bot, ct)).AllowAnonymous();

// Add:
app.UseAuthentication();
app.UseAuthorization();
app.MapAgentRootEndpoint();
app.MapAgentApplicationEndpoints(requireAuth: !app.Environment.IsDevelopment());

Step 4 or at the very end of the migration: Ask user if they would like to write the learnings from this migration to a markdown file they could submit to use to help us improve the skill.

---

Development URL

If the existing bot had app.Urls.Add("http://localhost:3978") inside an IsDevelopment() check, keep it. If it was missing, add it:

if (app.Environment.IsDevelopment())
{
    app.Urls.Add("http://localhost:3978");
}

---

Middleware Replacements

Some Bot Framework middleware has a direct equivalent in AgentApplication configuration.

ShowTypingMiddleware → StartTypingTimer

Drop the ShowTypingMiddleware registration and enable the built-in typing timer instead:

// Remove from adapter setup:
// adapter.Use(new ShowTypingMiddleware());

// appsettings.json — add to AgentApplication section:
"AgentApplication": {
  "StartTypingTimer": true
}

AutoSaveStateMiddleware

AgentApplication loads and saves state automatically on every turn. Always remove AutoSaveStateMiddleware — it is no longer needed and must not be used with AgentApplication.

// REMOVE — always:
// new AutoSaveStateMiddleware(...)
// adapter.Use(new AutoSaveStateMiddleware(...));

If removing it empties the IMiddleware[] DI registration, remove that registration entirely as well.

NormalizeMentionsMiddleware → NormalizeMentions / RemoveRecipientMention

Drop the NormalizeMentionsMiddleware registration and enable the equivalent settings instead:

// Remove from adapter setup:
// adapter.Use(new NormalizeMentionsMiddleware());

// appsettings.json — add to AgentApplication section:
"AgentApplication": {
  "NormalizeMentions": true,
  "RemoveRecipientMention": true
}

---

Files to Delete

File	When to delete
BotController.cs	Always when switching to MapAgentApplicationEndpoints — unless it has custom logic beyond ProcessAsync
Controllers/ folder	After deleting BotController.cs, if no other controllers remain

Do not delete AspNetExtensions.cs — if present it is providing the AddAgentAspNetAuthentication extension and must be kept.

---

Common Mistakes

Mistake	Fix
Forgot builder.AddAgentApplicationOptions()	Add before builder.AddAgent<T>()
Removed custom DI (dialogs, state, services)	Restore — never remove developer-added registrations
Added [Agent] attribute to AgentApplication class	Not required — MapAgentApplicationEndpoints discovers AgentApplication subclasses without it
Left using Microsoft.Agents.Builder.Compat	Remove — ActivityHandler is gone
Left using Microsoft.Agents.Extensions.Teams.Compat on main class	Remove — TeamsActivityHandler is gone; use RegisterExtension(new TeamsAgentExtension(this), ...) instead
Teams MessageExtension handler returns MessagingExtensionResponse	Change return type to MessagingExtensionResult — the framework no longer uses the ComposeExtension wrapper; return the inner result directly
Teams query parameter accessed by index (query.Parameters[0].Value)	Use named access: query.Parameters.TryGetValue("paramName", out var val) where val is a JsonElement; parameter name comes from the Teams app manifest command definition
Teams SelectItem handler uses JsonElement parameter	In OnSelectItem, the parameter type is object; cast it: JsonElement query = (JsonElement)item
Missing Microsoft.Agents.Extensions.Teams.App namespace for TeamsAgentExtension	Add using Microsoft.Agents.Extensions.Teams.App; — TeamsAgentExtension is not in the Compat namespace
Missing Microsoft.Agents.Builder.App.AdaptiveCards namespace for Query<T>	Add using Microsoft.Agents.Builder.App.AdaptiveCards; — required for Query<IDictionary<string, object>> handler parameter
AdaptiveCard is ambiguous after adding using Microsoft.Agents.Builder.App.AdaptiveCards	Conflict with AdaptiveCards.AdaptiveCard from the AdaptiveCards NuGet package. Use an alias instead: using AgentAdaptiveCards = Microsoft.Agents.Builder.App.AdaptiveCards; then reference AgentAdaptiveCards.Query<IDictionary<string, object>> in the handler signature
Kept builder.Services.AddControllers() but deleted all controllers	Remove — no longer needed without MVC controllers
Missing app.UseAuthentication() / app.UseAuthorization() after switching from MapControllers	Add them before MapAgentApplicationEndpoints
Injected ConversationState into bot constructor for dialogs	Remove from bot — use turnState.Conversation in Dialog.RunAsync calls instead
Left ConversationState registered in DI	Remove — AgentApplication manages state internally via ITurnState
Left UserState registered in DI	Remove — AgentApplication does not use it
Left AutoSaveStateMiddleware registered	Remove entirely — AgentApplication saves state automatically; never keep it
Left ConversationState injected in custom adapter OnTurnError for DeleteStateAsync	Remove the parameter; move DeleteStateAsync into an AgentApplication.OnTurnError handler using turnState.Conversation.DeleteStateAsync
Left OnTurnBeginAsync/OnTurnEndAsync overrides that load/save state	Remove entirely — AgentApplication handles this automatically
Kept generic DialogBot<T> base class as a separate file	Collapse both classes into a single non-generic AgentApplication subclass; inject the concrete dialog type directly; delete the generic base class file
Left TeamsSSOTokenExchangeMiddleware in DI or IMiddleware[]	Remove — not required and should not be used with AgentApplication
Manually calling SaveChangesAsync in AgentApplication handlers	Remove — state is saved automatically
Left ShowTypingMiddleware registration	Drop it; set "AgentApplication": { "StartTypingTimer": true } in appsettings.json
Left NormalizeMentionsMiddleware registration	Drop it; set NormalizeMentions and/or RemoveRecipientMention to true in AgentApplication appsettings
Handler accesses membersAdded as a parameter	Use turnContext.Activity.MembersAdded instead — it is no longer passed as a parameter
Used ProjectReference to local SDK source instead of NuGet packages	Always use NuGet packages — customers don't have access to the SDK source repo
Custom adapter constructor uses ILogger<IAgentHttpAdapter>	Change to ILogger<CloudAdapter> — CloudAdapter base constructor requires the concrete type, not the interface
Changed business logic during migration	Do not — only change structure/registration/routing
Missing IStorage registration	Add builder.Services.AddSingleton<IStorage, MemoryStorage>(); — always required by AgentApplication, not just for dialog bots
Used OnActivity(ActivityTypes.Invoke, ...) for adaptiveCard/action verbs	Use AdaptiveCards.OnActionExecute(verb, handler) instead — it's built into AgentApplication, matches by verb, and handles the invoke response automatically
Called CreateInvokeResponse(...) in an OnActionExecute handler	CreateInvokeResponse is a compat-layer helper — it doesn't exist on AgentApplication. Return AdaptiveCardInvokeResponse directly; the framework wraps it
Deserialized data as AdaptiveCardInvokeValue in OnActionExecute handler	The data parameter is already invokeValue.Action.Data — deserialize directly as your data model, not as the full invoke value wrapper
teams.TaskModules.OnSubmit(verb, ...) never triggers	Default filter matches activity.Value.data.verb — if the submitted data has no verb field, use the RouteSelector overload with a custom selector that checks ctx.Activity.Name == "task/submit"
data parameter is null in SubmitHandlerAsync	The data parameter is taskModuleAction.Value (CardAction), which is null when the payload has no top-level "value" key. Parse the submitted data directly: ProtocolJsonSerializer.ToObject<TaskModuleRequest>(turnContext.Activity.Value).Data
Removed AddRazorPages() / MapRazorPages() when deleting BotController	Keep them — they serve web UI pages unrelated to the bot; only remove AddControllers(), AddMvc(), and MapControllers()/MapControllerRoute()
Used OnActivity(ActivityTypes.Invoke, ...) for application/search	Use AdaptiveCards.OnSearch(dataset, handler) instead — routes by choices.data.dataset value, handles invoke response automatically, handler returns IList<AdaptiveCardsSearchResult>
OnSearch handler returns InvokeResponse	Return IList<AdaptiveCardsSearchResult> — the framework wraps results in application/vnd.microsoft.search.searchResponse and sends the invoke response
Looked for associated input values (dependent dropdown) in query.Parameters	Associated inputs from "associatedInputs": "auto" arrive in the data field of the raw invoke payload, not in query.Parameters. Read them via ProtocolJsonSerializer.ToObject<MyModel>(turnContext.Activity.Value)