microsoft/teams.net
Publicmirrored fromhttps://github.com/microsoft/teams.netAvailable
core/README.md
126lines · modecode
| 1 | # Microsoft Teams Bot Core SDK |
| 2 | |
| 3 | The core SDK for building Microsoft Teams bots in .NET. It implements the [Activity Protocol](https://github.com/microsoft/Agents/blob/main/specs/activity/protocol-activity.md) and provides a modern, layered framework with first-class support for ASP.NET Core dependency injection, authentication via MSAL, and extensible activity schemas. |
| 4 | |
| 5 | ## Packages |
| 6 | |
| 7 | | Package | Description | |
| 8 | |---------|-------------| |
| 9 | | [Microsoft.Teams.Core](src/Microsoft.Teams.Core/) | Foundational library — activity protocol, conversation client, user token client, middleware pipeline, and authentication | |
| 10 | | [Microsoft.Teams.Apps](src/Microsoft.Teams.Apps/) | High-level Teams framework — typed activity routing, handler registration, OAuth flows, Teams API clients, and streaming | |
| 11 | | [Microsoft.Teams.Apps.BotBuilder](src/Microsoft.Teams.Apps.BotBuilder/) | Compatibility bridge for existing Bot Framework SDK v4 bots to run on the new Core infrastructure | |
| 12 | |
| 13 | ## Quick Start |
| 14 | |
| 15 | ```csharp |
| 16 | using Microsoft.Teams.Apps; |
| 17 | |
| 18 | var builder = WebApplication.CreateBuilder(args); |
| 19 | builder.AddTeams(); |
| 20 | |
| 21 | var app = builder.Build(); |
| 22 | var teams = app.UseTeams(); // maps POST /api/messages |
| 23 | |
| 24 | teams.OnMessage(async (context, ct) => |
| 25 | { |
| 26 | await context.Send($"You said: {context.Activity.Text}"); |
| 27 | }); |
| 28 | |
| 29 | app.Run(); |
| 30 | ``` |
| 31 | |
| 32 | ## Design Principles |
| 33 | |
| 34 | - **Loose schema** — `CoreActivity` contains only strictly required fields; additional fields are captured via `JsonExtensionData` |
| 35 | - **Simple serialization** — Standard `System.Text.Json` with source generation, no custom converters |
| 36 | - **Extensible schema** — `ChannelData` and entities support extension properties; generics allow custom types |
| 37 | - **MSAL-based auth** — Token acquisition built on Microsoft Identity Web, supporting client secrets, managed identities, and agentic (user-delegated) tokens |
| 38 | - **ASP.NET DI** — All dependencies configured via `IServiceCollection`, reusing the built-in `HttpClient` factory |
| 39 | - **ILogger & IConfiguration** — Standard .NET logging and configuration throughout |
| 40 | |
| 41 | ## Configuration |
| 42 | |
| 43 | Create a Teams Application, configure it in Azure Bot Service, and provide credentials via `appsettings.json`: |
| 44 | |
| 45 | ```json |
| 46 | { |
| 47 | "AzureAd": { |
| 48 | "Instance": "https://login.microsoftonline.com/", |
| 49 | "TenantId": "<your-tenant-id>", |
| 50 | "ClientId": "<your-client-id>", |
| 51 | "Scope": "https://api.botframework.com/.default", |
| 52 | "ClientCredentials": [ |
| 53 | { |
| 54 | "SourceType": "ClientSecret", |
| 55 | "ClientSecret": "<your-entra-app-secret>" |
| 56 | } |
| 57 | ] |
| 58 | } |
| 59 | } |
| 60 | ``` |
| 61 | |
| 62 | Or via environment variables: |
| 63 | |
| 64 | ```env |
| 65 | AzureAd__Instance=https://login.microsoftonline.com/ |
| 66 | AzureAd__TenantId=<your-tenant-id> |
| 67 | AzureAd__ClientId=<your-client-id> |
| 68 | AzureAd__Scope=https://api.botframework.com/.default |
| 69 | AzureAd__ClientCredentials__0__SourceType=ClientSecret |
| 70 | AzureAd__ClientCredentials__0__ClientSecret=<your-entra-app-secret> |
| 71 | ``` |
| 72 | |
| 73 | ## Testing in Localhost (Anonymous) |
| 74 | |
| 75 | When no MSAL configuration is provided, all communication happens as anonymous REST calls, suitable for local development. |
| 76 | |
| 77 | ### Install Playground |
| 78 | |
| 79 | Linux: |
| 80 | ```sh |
| 81 | curl -s https://raw.githubusercontent.com/OfficeDev/microsoft-365-agents-toolkit/dev/.github/scripts/install-agentsplayground-linux.sh | bash |
| 82 | ``` |
| 83 | |
| 84 | Windows: |
| 85 | ```sh |
| 86 | winget install m365agentsplayground |
| 87 | ``` |
| 88 | |
| 89 | ### Run a Scenario |
| 90 | |
| 91 | ```sh |
| 92 | dotnet samples/scenarios/middleware.cs -- --urls "http://localhost:3978" |
| 93 | ``` |
| 94 | |
| 95 | ## Samples |
| 96 | |
| 97 | | Sample | Description | |
| 98 | |--------|-------------| |
| 99 | | [TeamsBot](samples/TeamsBot/) | Basic Teams bot with message handling | |
| 100 | | [TeamsChannelBot](samples/TeamsChannelBot/) | Channel-scoped messaging | |
| 101 | | [AllInvokesBot](samples/AllInvokesBot/) | Handles all invoke activity types | |
| 102 | | [MessageExtensionBot](samples/MessageExtensionBot/) | Message extension search and actions | |
| 103 | | [MeetingsBot](samples/MeetingsBot/) | Meeting events and participant APIs | |
| 104 | | [OAuthFlowBot](samples/OAuthFlowBot/) | OAuth sign-in and token management | |
| 105 | | [SsoBot](samples/SsoBot/) | Single sign-on (SSO) token exchange | |
| 106 | | [StreamingBot](samples/StreamingBot/) | Progressive streaming responses | |
| 107 | | [Proactive](samples/Proactive/) | Proactive messaging from external triggers | |
| 108 | | [TabApp](samples/TabApp/) | Tab application with backend API | |
| 109 | | [CompatBot](samples/CompatBot/) | Migrating a Bot Framework v4 bot | |
| 110 | | [CoreBot](samples/CoreBot/) | Using Microsoft.Teams.Core directly | |
| 111 | |
| 112 | ## Project Structure |
| 113 | |
| 114 | ``` |
| 115 | core/ |
| 116 | ├── src/ |
| 117 | │ ├── Microsoft.Teams.Core/ # Foundation: protocol, clients, middleware, auth |
| 118 | │ ├── Microsoft.Teams.Apps/ # Framework: routing, handlers, OAuth, API clients |
| 119 | │ └── Microsoft.Teams.Apps.BotBuilder/ # Compat bridge for Bot Framework SDK v4 |
| 120 | ├── samples/ # Sample bot applications |
| 121 | └── test/ |
| 122 | ├── Microsoft.Teams.Core.UnitTests/ |
| 123 | ├── Microsoft.Teams.Apps.UnitTests/ |
| 124 | ├── Microsoft.Teams.Apps.BotBuilder.UnitTests/ |
| 125 | └── IntegrationTests/ |
| 126 | ``` |
| 127 | |