Bf To Agents SDK Dotnet Migration

Bot Framework to Agents SDK Migration (.NET)

Overview

Migrates a Bot Framework SDK bot to Microsoft 365 Agents SDK using the ActivityHandler/TeamsActivityHandler compat layer — minimal code changes, original class names preserved.

This skill stops at the compat layer. After completing this migration, ask the user whether to also convert to AgentApplication (see final step).

Agents DotNet SDK repository: https://github.com/microsoft/agents-for-net

Bot Framework DotNet SDK repository: https://github.com/microsoft/botbuilder-dotnet

Core Rules

• Retain the original bot class name. Do not rename or create a new class — renaming breaks git history.
• Only change what is required for a clean migration. Do not refactor, restructure, or improve beyond what is needed to compile and run on Agents SDK.

Package Replacements

Version: Always use the latest stable (non-beta) version of Agents SDK packages by default.

| Remove (Bot Framework) | Add (Agents SDK) |

|------------------------|------------------|

| Microsoft.Bot.Builder.Integration.AspNet.Core | Microsoft.Agents.Hosting.AspNetCore |

| Microsoft.Bot.Builder | Microsoft.Agents.Builder |

| Microsoft.Bot.Builder.Teams | Microsoft.Agents.Extensions.Teams |

| Microsoft.Bot.Builder.Dialogs | Microsoft.Agents.Builder.Dialogs |

| Microsoft.Bot.Connector | Microsoft.Agents.Connector |

| Microsoft.Bot.Connector.Authentication / MSAL auth packages | Microsoft.Agents.Authentication.Msal |

Deprecated Packages — No Agents SDK Equivalent

The following Bot Framework packages have no equivalent in the Agents SDK and are not supported. There is no recommended replacement. Remove them from the .csproj, but do not attempt to migrate the code that uses them — it will cause build errors that cannot be resolved within the Agents SDK migration. Flag this to the customer.

| Deprecated Package |

|--------------------|

| Microsoft.Bot.Builder.AI.Luis |

| Microsoft.Bot.Builder.AI.Orchestrator |

| Microsoft.Bot.Builder.AI.QnA |

| Microsoft.Bot.Builder.Azure.Queues |

| Microsoft.Bot.Builder.Dialogs.Adaptive |

| Microsoft.Bot.Builder.Dialogs.Adaptive.Runtime |

| Microsoft.Bot.Builder.Dialogs.Adaptive.Testing |

| Microsoft.Bot.Builder.Dialogs.Debugging |

| Microsoft.Bot.Builder.LanguageGeneration |

| Microsoft.Bot.Builder.TemplateManager |

| Microsoft.Bot.Configuration |

| Microsoft.Bot.Connector.Streaming |

| Microsoft.Bot.Streaming |

| Microsoft.Bot.Builder.Parsers.LU |

| AdaptiveExpressions |

Migration still proceeds — complete all other migration steps. The build errors from unmigrated code must be communicated to the customer as out-of-scope blockers.

Namespace Replacements

| Old | New |

|-----|-----|

| Microsoft.Bot.Builder | Microsoft.Agents.Builder |

| Microsoft.Bot.Builder (ActivityHandler) | Microsoft.Agents.Builder.Compat |

| Microsoft.Bot.Builder (AutoSaveStateMiddleware) | Microsoft.Agents.Builder.Compat |

| Microsoft.Bot.Builder.Teams (TeamsActivityHandler) | Microsoft.Agents.Extensions.Teams.Compat |

| Microsoft.Bot.Schema | Microsoft.Agents.Core.Models |

| Microsoft.Bot.Schema.Teams | Microsoft.Agents.Extensions.Teams.Models |

| Microsoft.Bot.Builder.Dialogs | Microsoft.Agents.Builder.Dialogs |

| Microsoft.Bot.Builder.Dialogs (PromptValidatorContext, PromptValidatorContext\<T\>) | Microsoft.Agents.Builder.Dialogs.Prompts |

| Microsoft.Bot.Builder.Integration.AspNet.Core | Microsoft.Agents.Hosting.AspNetCore |

| Microsoft.Bot.Builder.TraceExtensions | *(remove)* — TraceActivityAsync is built into ITurnContext |

Migration Steps

Step 1: Update packages and namespaces (see tables above)

Step 2: Keep bot class — retain original class name, only update using statements

ActivityHandler and TeamsActivityHandler exist unchanged in the Compat namespace. All override methods keep the same signatures. Do not rename the class.

// Before
using Microsoft.Bot.Builder;
using Microsoft.Bot.Schema;
public class EchoBot : ActivityHandler { /* unchanged */ }

// After — only using directives change; class name stays EchoBot
using Microsoft.Agents.Builder;
using Microsoft.Agents.Builder.Compat;    // ActivityHandler lives here
using Microsoft.Agents.Core.Models;        // IMessageActivity, ChannelAccount, etc.
public class EchoBot : ActivityHandler { /* unchanged */ }

For Teams:

// Before
using Microsoft.Bot.Builder.Teams;
using Microsoft.Bot.Schema.Teams;
public class MyBot : TeamsActivityHandler { /* unchanged */ }

// After — class name stays MyBot
using Microsoft.Agents.Extensions.Teams.Compat;   // TeamsActivityHandler lives here
using Microsoft.Agents.Extensions.Teams.Models;    // TeamsChannelAccount, TeamInfo, etc.
public class MyBot : TeamsActivityHandler { /* unchanged */ }

Step 3: State management for dialog bots

If the bot overrides OnTurnAsync to call SaveChangesAsync, both patterns work — keep whichever the bot already uses:

// Option A: Keep existing pattern in OnTurnAsync (works as-is)
public override async Task OnTurnAsync(ITurnContext ctx, CancellationToken ct)
{
    await base.OnTurnAsync(ctx, ct);
    await ConversationState.SaveChangesAsync(ctx, false, ct);
    await UserState.SaveChangesAsync(ctx, false, ct);
}

// Option B: Use AutoSaveStateMiddleware (register in adapter setup)
// adapter.Use(new AutoSaveStateMiddleware(conversationState, userState));

Step 4: New Program.cs

Delete BotController.cs and AdapterWithErrorHandler.cs. Create Program.cs:

using Microsoft.Agents.Hosting.AspNetCore;
using Microsoft.Agents.Storage;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpClient();
builder.Services.AddControllers();

// Register bot — AddAgent works because ActivityHandler implements IAgent
// DO NOT call AddAgentApplicationOptions() — that is only for AgentApplication
builder.AddAgent<MyBot>();

// Storage — always required by the Agents SDK
builder.Services.AddSingleton<IStorage, MemoryStorage>();

// Preserve all customer-specific DI registrations:
// builder.Services.AddSingleton<ConversationState>();
// builder.Services.AddSingleton<UserState>();
// builder.Services.AddSingleton<MyDialog>();
// builder.Services.AddSingleton<IMyService, MyService>();

// AddAgentAspNetAuthentication is defined in AspNetExtensions.cs — copy from any Agents SDK sample
builder.Services.AddAgentAspNetAuthentication(builder.Configuration);

WebApplication app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();
app.MapAgentRootEndpoint();

// ActivityHandler bots use MapAgentEndpoints — NOT MapAgentApplicationEndpoints
// MapAgentApplicationEndpoints only works for AgentApplication subclasses
app.MapAgentEndpoints(requireAuth: !app.Environment.IsDevelopment());

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

app.Run();

If customer had custom logic in BotController, preserve it using the process delegate:

app.MapAgentEndpoints(
    requireAuth: !app.Environment.IsDevelopment(),
    process: async (request, response, adapter, agent, ct) =>
    {
        // Custom controller logic here
        await adapter.ProcessAsync(request, response, agent, ct);
    });

Step 5 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.

appsettings.json Changes

Remove Bot Framework auth config and add Agents SDK config. The shape of Connections:ServiceConnection depends on the value of MicrosoftAppType in the existing appsettings.

In all cases: remove MicrosoftAppId, MicrosoftAppPassword, MicrosoftAppType, and MicrosoftAppTenantId — their values are carried forward into the new structure.

Case 1: MicrosoftAppType = "SingleTenant"

{
  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "ClientSecret",
        "AuthorityEndpoint": "https://login.microsoftonline.com/{MicrosoftAppTenantId}",
        "ClientId": "{MicrosoftAppId}",
        "ClientSecret": "{MicrosoftAppPassword}",
        "Scopes": ["https://api.botframework.com/.default"]
      }
    }
  },
  "ConnectionsMap": [
    {
      "ServiceUrl": "*",
      "Connection": "ServiceConnection"
    }
  ],
  "TokenValidation": {
    "Enabled": true,
    "Audiences": ["{MicrosoftAppId}"],
    "TenantId": "{MicrosoftAppTenantId}"
  }
}

Case 2: MicrosoftAppType = "UserAssignedMSI"

{
  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "UserManagedIdentity",
        "ClientId": "{MicrosoftAppId}",
        "Scopes": ["https://api.botframework.com/.default"]
      }
    }
  },
  "ConnectionsMap": [
    {
      "ServiceUrl": "*",
      "Connection": "ServiceConnection"
    }
  ],
  "TokenValidation": {
    "Enabled": true,
    "Audiences": ["{MicrosoftAppId}"],
    "TenantId": "{MicrosoftAppTenantId}"
  }
}

Case 3: MicrosoftAppType = "MultiTenant", missing, or null

{
  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "ClientSecret",
        "AuthorityEndpoint": "https://login.microsoftonline.com/botframework.com",
        "ClientId": "{MicrosoftAppId}",
        "TenantId": "{MicrosoftAppTenantId}",
        "ClientSecret": "{MicrosoftAppPassword}",
        "Scopes": ["https://api.botframework.com/.default"]
      }
    }
  },
  "ConnectionsMap": [
    {
      "ServiceUrl": "*",
      "Connection": "ServiceConnection"
    }
  ],
  "TokenValidation": {
    "Enabled": true,
    "Audiences": ["{MicrosoftAppId}"],
    "TenantId": "{MicrosoftAppTenantId}"
  }
}

Case 4: Any other MicrosoftAppType value

Do not generate Connections:ServiceConnection. Complete all other migration steps, then at the end inform the user:

> "The MicrosoftAppType value {value} is not a standard type recognized by this migration. The Connections:ServiceConnection block was not changed — additional manual configuration will be required. See: https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/microsoft-authentication-library-configuration-options"

Custom BotAdapter

If the source bot subclasses BotAdapter, migrate it to ChannelAdapter (Microsoft.Agents.Builder).

Class hierarchy to choose from

| Use when | Subclass |

|----------|----------|

| Custom transport / non-Azure channel | ChannelAdapter (abstract, minimal pipeline) |

| Azure Bot Service connectivity with custom behavior | CloudAdapter (Microsoft.Agents.Hosting.AspNetCore) |

Most custom BotAdapter subclasses fall into the CloudAdapter case. Prefer that unless the adapter is implementing a completely custom transport.

API mapping

| Bot Framework BotAdapter | Agents SDK |

|---------------------------|------------|

| using Microsoft.Bot.Builder; | using Microsoft.Agents.Builder; |

| : BotAdapter | : ChannelAdapter or : CloudAdapter |

| Activity[] in SendActivitiesAsync | IActivity[] in SendActivitiesAsync |

| BotCallbackHandler callback delegate | AgentCallbackHandler |

| abstract UpdateActivityAsync(...) | virtual UpdateActivityAsync(...) (throws NotImplementedException if not overridden) |

| abstract DeleteActivityAsync(...) | virtual DeleteActivityAsync(...) (throws NotImplementedException if not overridden) |

| protected RunPipelineAsync(ctx, BotCallbackHandler, ct) | protected RunPipelineAsync(ctx, AgentCallbackHandler, ct) |

Registration

Register the custom adapter via the two-type overload of AddAgent. Note AddAgent<TAgent, TAdapter> requires TAdapter : CloudAdapter:

builder.AddAgent<MyBot, MyCustomAdapter>();

If the custom adapter subclasses ChannelAdapter directly (not CloudAdapter), register manually:

builder.AddAgentCore();  // registers IConnections, IChannelServiceClientFactory
builder.Services.AddSingleton<IChannelAdapter, MyCustomAdapter>();
builder.Services.AddSingleton<IAgentHttpAdapter>(sp => (IAgentHttpAdapter)sp.GetRequiredService<IChannelAdapter>());
builder.Services.AddTransient<IAgent, MyAgent>();

Custom IMiddleware

If the source bot implements Microsoft.Bot.Builder.IMiddleware, retain the class and update its namespaces:

| Old | New |

|-----|-----|

| Microsoft.Bot.Builder.IMiddleware | Microsoft.Agents.Builder.IMiddleware |

| Microsoft.Bot.Builder.ITurnContext | Microsoft.Agents.Builder.ITurnContext |

| Microsoft.Bot.Builder.NextDelegate | Microsoft.Agents.Builder.NextDelegate |

The OnTurnAsync(ITurnContext, NextDelegate, CancellationToken) signature is unchanged.

Register custom middleware via a CloudAdapter subclass. Delete AdapterWithErrorHandler.cs only if it has no custom middleware — if it does, rename it or keep it as a custom adapter:

// CustomAdapter.cs
using Microsoft.Agents.Builder;
using Microsoft.Agents.Hosting.AspNetCore;
using Microsoft.Agents.Hosting.AspNetCore.BackgroundQueue;
using Microsoft.Extensions.Logging;

public class CustomAdapter : CloudAdapter
{
    public CustomAdapter(
        IChannelServiceClientFactory channelServiceClientFactory,
        IActivityTaskQueue activityTaskQueue,
        ILogger<CloudAdapter> logger = null)
        : base(channelServiceClientFactory, activityTaskQueue, logger: logger)
    {
        Use(new MyCustomMiddleware());
        // Use(new AnotherMiddleware(...));
    }
}

Register the custom adapter in Program.cs:

builder.AddAgent<MyBot, CustomAdapter>();

Files to Add

Every migrated project needs AspNetExtensions.cs — the AddAgentAspNetAuthentication() extension method is not in any NuGet package; it is a sample-provided file. Copy it from the Agents SDK shared samples (https://github.com/microsoft/Agents-for-net/blob/main/src/samples/Shared/AspNetExtensions.cs).

Files to Delete

Always delete these from the source project:

• AdapterWithErrorHandler.cs — delete if it only has OnTurnError logic (Agents SDK handles errors internally); retain and rename if it contains custom Use() middleware registrations (see Custom IMiddleware section above)
• BotController.cs (unless it has custom logic — see preservation note above)
• Any Startup.cs (merge into Program.cs)

Common Mistakes

| Mistake | Fix |

|---------|-----|

| Renamed the bot class or created a new class | Restore the original class name — renaming breaks git history |

| Changed more than needed (refactored, restructured) | Revert — only change what is required to compile and run |

| Called AddAgentApplicationOptions() for ActivityHandler bot | Remove — only for AgentApplication |

| Used MapAgentApplicationEndpoints() for ActivityHandler bot | Use MapAgentEndpoints() — former only works for AgentApplication |

| Left services.AddTransient<IBot, MyBot>() | Replace with builder.AddAgent<MyBot>() |

| Left services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>() | Delete — handled by AddAgent<>() |

| Left ConfigurationBotFrameworkAuthentication | Delete — use AddAgentAspNetAuthentication() |

| Missing IStorage registration | Add builder.Services.AddSingleton<IStorage, MemoryStorage>(); — always required, not just for dialog bots |

| Left old Bot Framework appsettings (MicrosoftAppId etc.) | Replace with Connections + TokenValidation — shape depends on MicrosoftAppType (see appsettings.json Changes section) |

| Used the wrong Connections:ServiceConnection shape | Check MicrosoftAppType: SingleTenant→ClientSecret+tenant authority; UserAssignedMSI→UserManagedIdentity (no secret); MultiTenant/missing→ClientSecret+botframework.com authority |

| Left BotAdapter as base class of custom adapter | Change to ChannelAdapter or CloudAdapter; update Activity[] → IActivity[], BotCallbackHandler → AgentCallbackHandler |

| Deleted AdapterWithErrorHandler.cs that contained custom Use() calls | Retain it (renamed if needed) as a CloudAdapter subclass; register via builder.AddAgent<TBot, TAdapter>() |

| Left Microsoft.Bot.Builder.IMiddleware namespace in custom middleware | Update to Microsoft.Agents.Builder.IMiddleware |

| Attempted to migrate code using a deprecated package (Luis, QnA, Adaptive, etc.) | Stop — no Agents SDK equivalent exists. Remove the package reference, leave the code in place, and flag build errors to the customer |

| Forgot to add AspNetExtensions.cs | Copy from any Agents SDK sample — AddAgentAspNetAuthentication is not in any NuGet package |

| Left conversationState.DeleteAsync(...) in adapter | Rename to conversationState.DeleteStateAsync(...) — method was renamed in Agents SDK |

| New Program.cs fails to compile (WebApplication, AddSingleton, IsDevelopment not found) | BF projects don't have <ImplicitUsings>enable</ImplicitUsings> — add explicit using for Microsoft.AspNetCore.Builder, Microsoft.Extensions.DependencyInjection, Microsoft.Extensions.Hosting |

After Migration: Optional AgentApplication Upgrade

Once the compat-layer migration is complete and the build is clean, ask the user:

> "The bot is now running on Agents SDK using the ActivityHandler compat layer. Would you like to also migrate to the modern AgentApplication routing pattern? This involves converting the bot class to subclass AgentApplication and updating Program.cs — it is handled by the agents-sdk-dotnet-activityhandler-migration skill."

If yes, invoke agents-sdk-dotnet-activityhandler-migration.

If no, migration is complete.