Skip to main content

From SDK 2.0 to 2.1

info

Use this guide to move an existing Teams SDK for .NET 2.0 app to SDK 2.1.

If you're starting a new app, target SDK 2.1 directly — no migration needed.

Migration highlights​

AreaSDK 2.0SDK 2.1 (current)
App modelPlugin-orientedStandard ASP.NET Core app
Startupbuilder.AddTeams() + app.UseTeams()builder.Services.AddTeamsBotApplication() + app.UseTeamsBotApplication()
Auth configTeams:* settingsMSAL-native AzureAd + BotFramework sections
Messaging helpersSend/Reply/Quote, MessageActivity, app.Send/app.ReplySendAsync/ReplyAsync/QuoteAsync, MessageActivityInput, app.SendAsync/app.ReplyAsync
Cross-cutting pipelinePlugin/event-bus patternsITurnMiddleware + DI
Local unauthenticated devskipAuth: trueAzureAd:DangerouslyAllowUnauthenticatedRequests=true

1. Move to SDK 2.1 packages​

Update package references to use SDK 2.1 packages.

Example .csproj change:

<ItemGroup>
<PackageReference Include="Microsoft.Teams.Apps" Version="2.1.*" />
</ItemGroup>

2. Move to MSAL-native auth configuration​

SDK 2.1 moves from SDK-specific Teams:* auth settings to MSAL-native Microsoft Entra config under AzureAd (plus BotFramework service endpoints), aligned with standard ASP.NET Core configuration.

appsettings.json
{
"AzureAd": {
"TenantId": "your-tenant-id",
"ClientId": "your-client-id",
"ClientCredentials": [
{
"SourceType": "ClientSecret",
"ClientSecret": "your-client-secret"
}
]
}
}

For sovereign cloud or non-public endpoints, add the corresponding service settings:

appsettings.json
{
"AzureAd": {
"Instance": "https://login.microsoftonline.us/"
},
"BotFramework": {
"OpenIdMetadataUrl": "https://login.botframework.azure.us/v1/.well-known/openid-configuration",
"BotTokenIssuer": "https://api.botframework.us"
}
}

3. Replace startup/bootstrap code​

Update Program.cs to the SDK 2.1 hosting model:

Program.cs
using Microsoft.Teams.Apps;

WebApplicationBuilder builder = WebApplication.CreateSlimBuilder(args);
builder.Services.AddTeamsBotApplication();

WebApplication app = builder.Build();
TeamsBotApplication teams = app.UseTeamsBotApplication();

app.Run();

4. Update helper calls to SDK 2.1 APIs​

Keep simple text helpers (Send/Reply) and update async call patterns for SDK 2.1.
When sending typed activities, use MessageActivityInput.

Context helpers

teams.OnMessage(async (context, cancellationToken) =>
{
await context.SendAsync("Acknowledged", cancellationToken);
await context.ReplyAsync("Got it!", cancellationToken);
await context.QuoteAsync("1772050244572", "Referencing an earlier message", cancellationToken);

await context.SendAsync(new MessageActivityInput("Hello from bot"), cancellationToken);
await context.ReplyAsync(new MessageActivityInput("Reply with activity object"), cancellationToken);
await context.QuoteAsync(
"1772050244572",
new MessageActivityInput("Quoted reply with activity object"),
cancellationToken);
});

App helpers:

await teams.SendAsync(
conversationId,
"Welcome",
cancellationToken: cancellationToken);
await teams.SendAsync(
conversationId,
new MessageActivityInput("Welcome with activity object"),
serviceUrl: new Uri("https://smba.trafficmanager.net/teams/"),
cancellationToken: cancellationToken);

await teams.ReplyAsync(
conversationId,
"Flat chat update",
cancellationToken: cancellationToken);
await teams.ReplyAsync(
conversationId,
"1772050244572",
"Thread update",
cancellationToken: cancellationToken);

In SDK 2.2 and later, ReplyAsync(chatOrChannelId, messageId, ...) posts to the reply chain route, so it takes the chat or channel id from channelData and the reply chain id from channelData.replyChain.id. See Proactive Threading.

5. OAuth migration​

In SDK 2.0, OAuth was typically handled through app-level sign-in events after invoking context.SignIn(...).
In SDK 2.1, OAuth is modeled as named flows (AddOAuthFlow + GetOAuthFlow) with explicit success and failure callbacks per flow.

Use these end-to-end OAuth patterns with three key handlers: /signin, sign-in success, and sign-in failure.

builder.Services.AddTeamsBotApplication(options =>
{
options.AddOAuthFlow("graph", oauth =>
{
oauth.OAuthCardText = "Sign in to Microsoft Graph";
oauth.SignInButtonText = "Sign in to Graph";
});
});

OAuthFlow graphAuth = teams.GetOAuthFlow("graph");

graphAuth.OnSignInComplete(async (context, tokenResponse, cancellationToken) =>
{
await context.SendAsync($"Signed in ({tokenResponse.ConnectionName}).", cancellationToken);
});

teams.OnMessage("/signin", async (context, cancellationToken) =>
{
string? token = await graphAuth.SignInAsync(context, cancellationToken);
if (token is not null)
{
await context.SendAsync("You are already signed in.", cancellationToken);
}
});

graphAuth.OnSignInFailure(async (context, failure, cancellationToken) =>
{
await context.SendAsync($"Sign-in failed: {failure?.Code} - {failure?.Message}", cancellationToken);
});

6. Migrate to built-in state management​

SDK 2.1 state is cleaner: call options.UseState() and use context.State.ConversationState / context.State.UserState in handlers.

It is also easy to scale. UseState() uses the standard ASP.NET Core IDistributedCache abstraction under the hood with an in-memory default for local development, and you can move to shared state by registering a distributed cache provider (for example Redis) without changing your handler state logic.

builder.Services.AddTeamsBotApplication(options =>
{
options.UseState();
});

teams.OnMessage(async (context, cancellationToken) =>
{
context.State.ConversationState.Set("lastText", context.Activity.Text ?? string.Empty);
string? lastText = context.State.ConversationState.Get<string>("lastText");
await context.SendAsync($"Saved state: {lastText}", cancellationToken);
});

7. AI migration​

With 2.1, Teams SDK no longer includes dedicated AI libraries and has tightened its focus on providing a developer-friendly interface to Teams. Keep Microsoft.Teams.Apps as your Teams transport/runtime layer and plug in a dedicated AI stack (for example Microsoft Agent Framework, OpenAI SDK, MCP, or A2A) from your handlers.

For migration guidance and rationale, see the AI libraries to agent frameworks blog.

// SDK 2.1: Teams runtime handles transport; bring your own AI stack.
// This example uses the OpenAI SDK directly — swap for any framework.
using OpenAI.Chat;

var builder = WebApplication.CreateSlimBuilder(args);
builder.Services.AddTeamsBotApplication();

// Register OpenAI client via DI
builder.Services.AddSingleton(_ =>
new ChatClient("gpt-4o", builder.Configuration["OpenAI:ApiKey"]));

var app = builder.Build();
TeamsBotApplication teams = app.UseTeamsBotApplication();

teams.OnMessage(async (context, cancellationToken) =>
{
ChatClient chatClient = context.Services.GetRequiredService<ChatClient>();

ChatCompletion completion = await chatClient.CompleteChatAsync(
[new UserChatMessage(context.Activity.Text ?? string.Empty)],
cancellationToken: cancellationToken);

await context.SendAsync(completion.Content[0].Text, cancellationToken);
});

app.Run();

8. Cards migration​

You can still use Microsoft.Teams.Cards in SDK 2.1. Build cards with the cards package, then serialize to JsonElement before attaching to MessageActivityInput.

using System.Text.Json;
using Microsoft.Teams.Cards;

teams.OnMessage(async (context, cancellationToken) =>
{
var card = new AdaptiveCard
{
Version = "1.5",
Body = new List<CardElement>
{
new TextBlock("Hello from SDK 2.1") { Wrap = true }
}
};

JsonElement cardElement = JsonSerializer.SerializeToElement(card);

await context.SendAsync(
new MessageActivityInput()
.WithText("Card message")
.WithAdaptiveCardAttachment(cardElement),
cancellationToken);
});

9. Streaming migration​

In SDK 2.0, streaming used context.Stream.Emit(...) to push chunks.
In SDK 2.1, TeamsStreamingWriter manages chunk updates and requires an explicit finalize step to complete the response.

teams.OnMessage(async (context, cancellationToken) =>
{
TeamsStreamingWriter writer = TeamsStreamingWriter.CreateFromContext(context);
await writer.AppendResponseAsync("hello", cancellationToken);
await writer.AppendResponseAsync(", ", cancellationToken);
await writer.AppendResponseAsync("world!", cancellationToken);
await writer.FinalizeResponseAsync(cancellationToken: cancellationToken);
});

10. Message extensions, task modules, files, and meetings​

This area has the biggest shape change beyond startup/auth. The handler names stay familiar (OnQuery, OnTaskFetch, OnFileConsent, OnMeetingStart), but the payload types and namespaces move to new feature-specific modules in SDK 2.1.

Key updates to expect:

  • Microsoft.Teams.Apps.Activities.* invoke/event payloads move to feature namespaces like Microsoft.Teams.Apps.MessageExtensions, TaskModules, Files, and Meetings.
  • Invoke handlers now use typed InvokeActivity<T> values and return typed response objects (MessageExtensionResponse, TaskModuleResponse, AdaptiveCardResponse) instead of older activity-wrapper types.
  • Meeting events use typed event values like MeetingStartValue in EventActivity<T>.
using Microsoft.Teams.Apps.Files;
using Microsoft.Teams.Apps.Meetings;
using Microsoft.Teams.Apps.MessageExtensions;
using Microsoft.Teams.Apps.TaskModules;

teams.OnQuery(async (context, cancellationToken) =>
{
MessageExtensionQuery? query = context.Activity.Value;
return MessageExtensionResponse.CreateBuilder()
.WithType(MessageExtensionResponseTypes.Message)
.WithText($"query: {query?.CommandId}")
.Build();
});

teams.OnTaskFetch(async (context, cancellationToken) =>
{
return TaskModuleResponse.CreateBuilder()
.WithType(TaskModuleResponseTypes.Message)
.WithMessage("Task fetch handled.")
.Build();
});

teams.OnFileConsent(async (context, cancellationToken) =>
{
var consent = context.Activity.Value;
await context.SendAsync($"File received: {consent?.FileInfo?.Name}", cancellationToken);
});

teams.OnMeetingStart(async (context, cancellationToken) =>
{
var activity = context.Activity.Value;
await context.SendAsync($"'{activity.Title}' has started.", cancellationToken);
});

11. Plugin/event-bus patterns → turn middleware​

SDK 2.1 removes plugin/event-bus style extensibility. Use ITurnMiddleware for cross-cutting behavior.

using Microsoft.Teams.Apps;
using Microsoft.Teams.Core;
using Microsoft.Teams.Core.Schema;

internal sealed class LoggingMiddleware : ITurnMiddleware
{
public async Task OnTurnAsync(
BotApplication botApplication,
CoreActivity activity,
NextTurn nextTurn,
CancellationToken cancellationToken = default)
{
Console.WriteLine($"Processing activity: {activity}");
await nextTurn(cancellationToken);
}
}

teams.UseMiddleware(new LoggingMiddleware());

12. Update local dev auth behavior​

Use this setting when testing locally with the Playground or another client that sends unauthenticated requests.

Properties/launchSettings.json
{
"profiles": {
"YourBot": {
"commandName": "Project",
"environmentVariables": {
"AzureAd__DangerouslyAllowUnauthenticatedRequests": "true"
}
}
}
}