Microsoft.Teams.Apps 2.1.0

Microsoft.Teams.Apps

A high-level framework for building Microsoft Teams bots in .NET. Built on top of Microsoft.Teams.Core, it provides Teams-specific activity types, a typed routing and handler system, OAuth authentication flows, Teams API clients, and streaming message support.

Key Features

• Typed Activity Routing — Register handlers for specific activity types (OnMessage, OnAdaptiveCardAction, OnQuery, etc.) with type-safe contexts
• Teams Activity Schema — Rich type hierarchy (MessageActivity, InvokeActivity<T>, ConversationUpdateActivity, etc.) with polymorphic deserialization
• OAuth Flows — Built-in SSO token exchange, sign-in cards, and token management via OAuthFlow
• Teams API Clients — Typed clients for conversations, members, teams, channels, meetings, and batch operations
• Streaming Messages — Progressive response updates via TeamsStreamingWriter
• Conversation Helpers — Send, reply, quote, and typing helpers for reactive and proactive messaging
• Turn State — Conversation and user state backed by IDistributedCache
• Targeted Messages — Send messages visible only to a selected participant in supported conversations
• Observability — OpenTelemetry spans, metrics, and Agent 365 baggage propagation
• Fluent Configuration — Chainable handler registration and options-based service configuration

Installation

dotnet add package Microsoft.Teams.Apps

Quick Start

using Microsoft.Teams.Apps;

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

var app = builder.Build();
var teams = app.UseTeamsBotApplication(); // maps POST /api/messages

teams.OnMessage(async (context, ct) =>
{
    await context.SendAsync($"You said: {context.Activity.Text}", ct);
});

app.Run();

Handler Registration

Handlers are registered as extension methods on TeamsBotApplication and can be chained:

Messages

// All messages
teams.OnMessage(async (context, ct) => { ... });

// Regex pattern match
teams.OnMessage(@"^help$", async (context, ct) =>
{
    await context.SendAsync("Here's how to use the bot...", ct);
});

Conversation Helpers

teams.OnMessage(async (context, ct) =>
{
    await context.TypingAsync(ct);
    await context.ReplyAsync("This reply quotes the incoming message.", ct);
    await context.QuoteAsync(context.Activity.Id!, "Explicitly quoted reply.", ct);
});

Invoke Activities

// Adaptive card actions
teams.OnAdaptiveCardAction(async (context, ct) =>
{
    var value = context.Activity.Value;
    return AdaptiveCardResponse.CreateMessageResponse("Action received.");
});

// Message extension search
teams.OnQuery(async (context, ct) =>
{
    var query = context.Activity.Value;
    var searchText = query?.Parameters
        .FirstOrDefault(parameter => parameter.Name == "queryText")?
        .Value;

    return MessageExtensionResponse.CreateBuilder()
        .WithType(MessageExtensionResponseTypes.Message)
        .WithText($"Searching for: {searchText}")
        .Build();
});

// Task modules
teams.OnFetchTask(async (context, ct) => { ... });
teams.OnTaskSubmit(async (context, ct) => { ... });

// Link unfurling
teams.OnQueryLink(async (context, ct) => { ... });

Other message extension handlers include OnSubmitAction, OnSelectItem, OnAnonQueryLink, OnQuerySettingUrl, OnSetting, and OnCardButtonClicked.

State and OAuth

Enable distributed turn state and register OAuth flows when adding the application:

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

UseState() uses an in-memory IDistributedCache by default. Register another IDistributedCache implementation, such as Redis, for state that must survive process restarts or be shared across instances.

Main Types