Teams App Developer

question: "Your project has an existing BotBuilder bot. Do you want to use the compatibility layer for incremental migration, or do a full rewrite to SDK v2?"
header: "Strategy"
options:
  - label: "Full rewrite (Recommended)"
    description: "Rewrite all handlers directly in Teams SDK v2. Cleaner result, full access to streaming/plugins/MCP/A2A. Best for bots with <15 routes or when starting fresh."
  - label: "Compat layer (incremental)"
    description: "Use @microsoft/teams.botbuilder to run old and new handlers side by side. Migrate one handler at a time. Best for large bots (15+ routes) or tight timelines."
  - label: "You Decide Everything"
    description: "Accept recommended defaults for all decisions and skip remaining questions."
multiSelect: false

question: "Does your existing bot use BotBuilder dialogs (WaterfallDialog, ComponentDialog)?"
header: "Dialogs"
options:
  - label: "No dialogs"
    description: "Bot uses simple message handlers only. No dialog migration needed."
  - label: "Yes — replace with Adaptive Cards (Recommended)"
    description: "Replace dialog flows with Adaptive Card forms + dialog.open/submit routes. Modern Teams pattern."
  - label: "Yes — replace with AI conversation"
    description: "Replace dialog flows with ChatPrompt-driven AI conversation. Best for open-ended inputs."
multiSelect: false

question: "How is your existing bot managing state (ConversationState, UserState)?"
header: "State"
options:
  - label: "MemoryStorage (dev only)"
    description: "In-memory storage — no migration needed, just switch to SDK v2 IStorage."
  - label: "Azure Blob/Cosmos (Recommended)"
    description: "Persistent storage — migrate connection config to SDK v2 IStorage adapter. Data format is compatible."
  - label: "Custom storage provider"
    description: "Custom IStorage implementation — will need to be adapted to SDK v2's IStorage interface."
multiSelect: false

// --- BEFORE: Legacy BotBuilder pattern ---
// Uses TeamsActivityHandler, TurnContext, and method overrides

import { TeamsActivityHandler, TurnContext, MessageFactory } from 'botbuilder';

class LegacyBot extends TeamsActivityHandler {
  async onMessage(context: TurnContext): Promise<void> {
    const text = context.activity.text?.trim();
    if (text === '/help') {
      await context.sendActivity(MessageFactory.text('Here is how I can help...'));
    } else {
      await context.sendActivity(MessageFactory.text(`You said: "${text}"`));
    }
  }

  async onMembersAdded(context: TurnContext): Promise<void> {
    for (const member of context.activity.membersAdded || []) {
      if (member.id !== context.activity.recipient.id) {
        await context.sendActivity('Welcome!');
      }
    }
  }
}

// --- AFTER: Teams SDK v2 pattern ---
// Uses App, app.on(), app.message(), destructured context

import { App } from '@microsoft/teams.apps';
import { ConsoleLogger } from '@microsoft/teams.common';
import { DevtoolsPlugin } from '@microsoft/teams.dev';

const app = new App({
  logger: new ConsoleLogger('migrated-bot', { level: 'debug' }),
  plugins: [new DevtoolsPlugin()],
});

app.message('/help', async ({ send }) => {
  await send('Here is how I can help...');
});

app.on('message', async ({ send, activity }) => {
  await send(`You said: "${activity.text}"`);
});

app.on('install.add', async ({ send }) => {
  await send('Welcome!');
});

app.start(3978);

// When to use the compat layer (@microsoft/teams.botbuilder):
//
// 1. Existing BotBuilder bot with many handlers that cannot be rewritten at once
// 2. Dependencies on BotBuilder-specific libraries or middleware
// 3. Need to run old and new handlers side by side during transition
// 4. Legacy dialog flows (WaterfallDialog) that need time to redesign
//
// When to do a full rewrite (skip the compat layer):
//
// 1. Small bot with few handlers (< 10 routes)
// 2. Starting a new project (always use @microsoft/teams.apps directly)
// 3. Want access to SDK v2-only features:
//    - DevtoolsPlugin for debugging
//    - Plugin system (MCP, A2A, custom plugins)
//    - Streaming responses with stream.emit()
//    - Built-in OAuth with ctx.isSignedIn / ctx.signin()
//    - app.send() for proactive messaging
//    - ChatPrompt for AI integration
// 4. The existing bot has no complex dialog flows
//
// Feature mapping:
//   BotBuilder TeamsActivityHandler.onMessage()     -> app.on('message')
//   BotBuilder TeamsActivityHandler.onMembersAdded() -> app.on('install.add')
//   BotBuilder TurnContext.sendActivity()            -> ctx.send() / ctx.reply()
//   BotBuilder CardFactory.adaptiveCard()            -> raw attachment object
//   BotBuilder OAuthPrompt                           -> oauth in AppOptions + ctx.signin()
//   BotBuilder ConversationState / UserState          -> IStorage + LocalStorage
//   BotBuilder WaterfallDialog                       -> dialog.open/submit + Adaptive Cards
//   BotBuilder ActivityHandler.run() + Express        -> app.start(port)
//   BotBuilder proactiveMessage via ConversationRef   -> app.send(conversationId, message)

// Step 1: Install the compat package alongside existing botbuilder
//   npm install @microsoft/teams.botbuilder @microsoft/teams.apps

// Step 2: Wrap existing handler with compat layer
//   (Specific API depends on @microsoft/teams.botbuilder version --
//    refer to the package README for exact usage)

// Step 3: Incrementally move handlers to SDK v2 patterns
//   Move one handler at a time from the legacy class to app.on() / app.message()
//   Test each migration step independently

// Step 4: Remove compat layer when all handlers are migrated
//   Remove @microsoft/teams.botbuilder and botbuilder from package.json
//   Your final code should look like a standard SDK v2 app:

import { App } from '@microsoft/teams.apps';
import { ConsoleLogger } from '@microsoft/teams.common';
import { DevtoolsPlugin } from '@microsoft/teams.dev';

const app = new App({
  clientId: process.env.CLIENT_ID,
  clientSecret: process.env.CLIENT_SECRET,
  tenantId: process.env.TENANT_ID,
  logger: new ConsoleLogger('fully-migrated-bot', { level: 'debug' }),
  plugins: [new DevtoolsPlugin()],
});

// All handlers now use SDK v2 patterns
app.on('message', async ({ send, activity }) => {
  await send(`Echo: ${activity.text}`);
});

app.on('install.add', async ({ send }) => {
  await send('Welcome! Bot has been installed.');
});

app.on('card.action', async ({ activity, send }) => {
  const data = activity.value;
  await send(`Action received: ${JSON.stringify(data)}`);
});

app.start(process.env.PORT || 3978).catch(console.error);