From 40699db6c5911edb21232d8191c983d018be8289 Mon Sep 17 00:00:00 2001 From: MehakBindra Date: Fri, 22 May 2026 13:36:28 -0700 Subject: [PATCH 1/3] doc update --- core/docs/ReduceBreakingChangesPlan.md | 506 +++++++++++-------------- 1 file changed, 218 insertions(+), 288 deletions(-) diff --git a/core/docs/ReduceBreakingChangesPlan.md b/core/docs/ReduceBreakingChangesPlan.md index b9088635..666991ea 100644 --- a/core/docs/ReduceBreakingChangesPlan.md +++ b/core/docs/ReduceBreakingChangesPlan.md @@ -8,58 +8,9 @@ The `core/src/Microsoft.Teams.Apps` project is the next version of `Libraries/Mi ## Breaking Changes Inventory -### BC-1: Context convenience methods removed (ALL 13 samples affected) - -**Decision: IMPLEMENT** (defer `Send(AdaptiveCard)` — avoid Teams.Cards dependency for now) - -**Old API:** -```csharp -await context.Send("text", cancellationToken); -await context.Send(card, cancellationToken); -await context.Reply("text", cancellationToken); -await context.Reply(card, cancellationToken); -await context.Typing("processing", cancellationToken); -``` - -**New API:** -```csharp -await context.SendActivityAsync("text", cancellationToken); // only string overload -// No Send(AdaptiveCard), no Reply(), no Typing() -``` - -**Samples affected:** Echo, Cards, Dialogs, Graph, Meetings, MessageExtensions, Reactions, TargetedMessages, Threading, Tab, Lights - -**Proposed fix:** Add convenience methods to `Context`: -- `Send(string text, CancellationToken)` -> wraps `SendActivityAsync(text)` -- `Send(TeamsActivity activity, CancellationToken)` -> wraps `SendActivityAsync(activity)` -- ~~`Send(AdaptiveCard card, CancellationToken)`~~ **DEFERRED** — review later to avoid Teams.Cards dependency -- `Reply(string text, CancellationToken)` -> builds threaded reply activity -- `Reply(TeamsActivity activity, CancellationToken)` -> builds threaded reply -- ~~`Reply(AdaptiveCard card, CancellationToken)`~~ **DEFERRED** — same reason -- `Typing(string? text, CancellationToken)` -> wraps `SendTypingActivityAsync()` - -**File:** `core/src/Microsoft.Teams.Apps/Context.cs` - --- -### BC-2: No `context.Log` logger (12 samples affected) - -**Decision: IMPLEMENT** — `context.Log` with `.Info()`, `.Error()`, `.Debug()` delegating to `ILogger` - -**Old API:** -```csharp -context.Log.Info("message"); -context.Log.Error("error"); -context.Log.Debug("debug"); -``` - -**New API:** No logger on context at all. - -**Samples affected:** Echo, Cards, Dialogs, Graph, Meetings, MessageExtensions, Reactions, TargetedMessages, Tab, Lights, BotBuilder, Deprecated.Controllers - -**Proposed fix:** Add `Log` property to `Context` that exposes an object with `.Info()`, `.Error()`, `.Debug()` methods, delegating to `Microsoft.Extensions.Logging.ILogger` sourced from DI. This preserves the old API surface while using the standard logging infrastructure. - -**File:** `core/src/Microsoft.Teams.Apps/Context.cs` +### Pending: Items to Review or Implement --- @@ -90,109 +41,89 @@ teams.OnActivity(async (context, cancellationToken) => { --- -### BC-4: No `context.Ref` (ConversationReference) (2 samples affected) +### BC-14: `app.AddTab()` missing (1 sample affected) -**Decision: DOC-ONLY** +**Decision: REVIEW LATER** **Old API:** ```csharp -var conversationId = context.Ref.Conversation.Id; +app.AddTab("dialog-form", "Web/dialog-form"); ``` -**New API:** No `Ref` property. Must use `context.Activity.Conversation.Id` directly. +**New API:** No `AddTab()` method. -**Samples affected:** Threading, TargetedMessages +**Samples affected:** Dialogs, Tab -**Migration:** `context.Ref.Conversation.Id` -> `context.Activity.Conversation.Id` +**Note:** Need to determine if `AddTab()` is just static file serving or also registers Teams tab config endpoints. This affects whether a simple "use `app.UseStaticFiles()`" migration note is sufficient. --- -### BC-5: No `context.AppId` (1 sample affected) - -**Decision: IMPLEMENT** - -**Old API:** -```csharp -context.Log.Info(context.AppId); -``` +### BC-19: Missing activity types -**New API:** No `AppId` on context. +**Decision: REVIEW LATER** -**Samples affected:** Echo +| Missing Type | Notes | +|---|---| +| `TypingActivity` | No class in new lib; typing handled via `TeamsActivityType.Typing`. | +| `EndOfConversationActivity` | Deprecated in old lib — not a breaking change to omit. | +| `CommandActivity` / `CommandResultActivity` | Deprecated in old lib — not a breaking change to omit. | -**Proposed fix:** Add `AppId` property to `Context` reading from `TeamsBotApplication.AppId`. +--- -**File:** `core/src/Microsoft.Teams.Apps/Context.cs` +### BC-20: Missing handler registration methods ---- +**Decision: REVIEW LATER** — 18 handler methods exist in the old library but not in the new. -### BC-6: App.Builder() pattern removed (2 samples affected) +**Tab handlers (completely removed):** +- `OnTabFetch`, `OnTabSubmit`, `OnConfigFetch`, `OnConfigSubmit` -**Decision: IMPLEMENT** — Add `App.Builder()` as a wrapper around ASP.NET DI +**Command handlers (not a breaking change):** +- `OnCommand`, `OnCommandResult` — fully deprecated in the old library (activity types + handlers). Not a breaking change to drop. -**Old API:** -```csharp -var appBuilder = App.Builder() - .AddLogger(new ConsoleLogger(...)) - .AddOAuth("graph"); -builder.AddTeams(appBuilder); -``` +**Infrastructure events (architectural change):** +- `OnActivity`, `OnError`, `OnStart`, `OnActivityResponse`, `OnActivitySent` -**New API:** -```csharp -builder.Services.AddTeamsBotApplication(options => { - options.AddOAuthFlow("graph"); -}); -``` +**Auth events (restructured to per-flow):** +- `OnSignIn`, `OnSignInFailure`, `OnTokenExchange`, `OnVerifyState` -**Samples affected:** Graph, Meetings +**Other removed handlers:** +- `OnTyping` , `OnHandoff`, `OnFeedback`, `OnExecuteAction` -**Proposed fix:** Add `App.Builder()` that wraps the standard ASP.NET DI options pattern, providing a clear migration path from the old builder API. +**Commented out in new library:** +- `OnSetting`, `OnCardButtonClicked`, `OnTypeaheadSearch`, `OnAnswerSearch`, `OnReadReceipt` — all active (not deprecated) --- -### BC-7: `AddTeams()` extension target changed (ALL samples affected) - -**Decision: IMPLEMENT** — parameterless overload only +### BC-23: MessageActivity commented-out properties -**Old API:** -```csharp -builder.AddTeams(); // on WebApplicationBuilder -builder.AddTeams(appBuilder); // with App.Builder -``` +**Decision: REVIEW LATER (partial)** — These properties exist in the old library but are commented out in the new. -**New API:** -```csharp -builder.Services.AddTeams(); // on IServiceCollection -``` +**Deprecated in old lib (not a breaking change to omit):** +`Speak`, `InputHint`, `Importance`, `Expiration` — marked `[Obsolete("This will be removed by end of summer 2026.")]` in commit 6f33aba. -**Samples affected:** All +**Active in old lib (real breaking change):** +`Summary`, `DeliveryMode`, `Value` — not deprecated. Still need to be addressed. -**Proposed fix:** Add parameterless extension method on `WebApplicationBuilder` that delegates to `builder.Services.AddTeams()`. +--- -**File:** `core/src/Microsoft.Teams.Apps/TeamsBotApplication.HostingExtensions.cs` +### Doc-Only: Architectural Changes (No Code Change Needed) --- -### BC-8: Proactive messaging from app-level (1 sample affected) +### BC-4: No `context.Ref` (ConversationReference) (2 samples affected) -**Decision: IMPLEMENT** +**Decision: DOC-ONLY** **Old API:** ```csharp -await teams.Send(conversationId, "text", cancellationToken: ct); -await teams.Reply(conversationId, messageId, "text", ct); +var conversationId = context.Ref.Conversation.Id; ``` -**New API:** No `Send()`/`Reply()` convenience methods on `TeamsBotApplication`. - -**Samples affected:** Threading +**New API:** No `Ref` property. Must use `context.Activity.Conversation.Id` directly. -**Proposed fix:** Add convenience methods on `TeamsBotApplication`: -- `Send(string conversationId, string text, ...)` -- `Reply(string conversationId, string messageId, string text, ...)` +**Samples affected:** Threading, TargetedMessages -**File:** `core/src/Microsoft.Teams.Apps/TeamsBotApplication.cs` or extension +**Migration:** `context.Ref.Conversation.Id` -> `context.Activity.Conversation.Id` --- @@ -219,297 +150,296 @@ flow.OnSignInFailure(handler); --- -### BC-10: Meeting handler renames (1 sample affected) - -**Decision: IMPLEMENT** — aliases without `[Obsolete]` +### BC-13: Activity type hierarchy changed (MEDIUM - affects type usage) -**Old API:** -```csharp -teams.OnMeetingJoin(handler); -teams.OnMeetingLeave(handler); -``` +**Decision: DOC-ONLY** -**New API:** -```csharp -teams.OnMeetingParticipantJoin(handler); -teams.OnMeetingParticipantLeave(handler); -``` +**Old:** Activities come from `Microsoft.Teams.Api.Activities` (e.g., `MessageActivity`, `InvokeActivity`) +**New:** Activities come from `Microsoft.Teams.Apps.Schema` (e.g., `MessageActivity : TeamsActivity`) -**Samples affected:** Meetings +**Migration:** Namespace imports change but member access stays the same. Provide namespace mapping table in migration docs. -**Proposed fix:** Add `OnMeetingJoin()` and `OnMeetingLeave()` as aliases that call the new methods. No `[Obsolete]` attribute for now — will revisit later. +--- -**File:** `core/src/Microsoft.Teams.Apps/Handlers/MeetingExtensions.cs` +### Not Migrated: Intentional Decisions --- -### BC-11: `OnSetting()` handler missing (1 sample affected) +### BC-18: Activity conversion methods removed (`ToMessage()`, `ToInvoke()`, etc.) -**Decision: REVIEW LATER** +**Decision: NOT MIGRATED** — The old library had `ToMessage()`, `ToInvoke()`, `ToEvent()`, etc. The new library uses `FromActivity()` static factory methods instead: -**Old API:** ```csharp -teams.OnSetting((context, cancellationToken) => { ... }); +// Old: activity.ToMessage() +// New: MessageActivity.FromActivity(coreActivity) ``` -**New API:** No `OnSetting()` extension method. +--- -**Samples affected:** MessageExtensions +### BC-21: Type incompatibilities -**Note:** Need to clarify what activity type/invoke name `OnSetting()` matches before implementing. +**Decision: NOT MIGRATED** — Intentional architectural changes. -**File:** `core/src/Microsoft.Teams.Apps/Handlers/MessageExtension/MessageExtensionExtensions.cs` +| Property | Old Type | New Type | +|---|---|---| +| `Timestamp`, `LocalTimestamp` | `DateTime?` | `string?` | +| `ServiceUrl` | `string?` | `Uri?` | +| `ContentUrl`, `ThumbnailUrl` (Attachment) | `string?` | `Uri?` | +| Enums (`TextFormat`, `InputHint`, etc.) | Enum types | String constants | +| `Account` | Custom `Account` class | `ConversationAccount` | --- -### BC-12: Invoke handler return types changed (4 samples affected) +### BC-24: SuggestedActions fluent methods removed -**Decision: IMPLEMENT** — factory methods only (no implicit conversions) +**Decision: NOT MIGRATED** — Old `SuggestedActions` had `AddRecipients()`, `AddAction()`, `AddActions()` fluent methods. Use direct property assignment instead. -**Old API:** Handlers return library-specific response types: -```csharp -// AdaptiveCardAction returns ActionResponse -return new ActionResponse.Message("text") { StatusCode = 400 }; +--- -// TaskFetch/Submit returns Microsoft.Teams.Api.TaskModules.Response -return new Microsoft.Teams.Api.TaskModules.Response(...); +### Implemented -// MessageExtension returns Microsoft.Teams.Api.MessageExtensions.Response -return response; +--- + +### BC-1: Context convenience methods removed (ALL 13 samples affected) + +**Decision: IMPLEMENTED** (defer `Send(AdaptiveCard)` — avoid Teams.Cards dependency for now) + +**Old API:** +```csharp +await context.Send("text", cancellationToken); +await context.Send(card, cancellationToken); +await context.Reply("text", cancellationToken); +await context.Reply(card, cancellationToken); +await context.Typing("processing", cancellationToken); ``` -**New API:** Handlers return `InvokeResponse` or `InvokeResponse`: +**New API:** ```csharp -Task AdaptiveCardActionHandler(...) -Task> TaskModuleHandler(...) -Task> MessageExtensionQueryHandler(...) +await context.SendActivityAsync("text", cancellationToken); // only string overload +// No Send(AdaptiveCard), no Reply(), no Typing() ``` -**Samples affected:** Cards, Dialogs, MessageExtensions, Lights +**Samples affected:** Echo, Cards, Dialogs, Graph, Meetings, MessageExtensions, Reactions, TargetedMessages, Threading, Tab, Lights -**Proposed fix:** Add factory methods: -- `InvokeResponse.Ok(body)` — wraps body with 200 status -- `InvokeResponse.Error(status, body)` — wraps body with error status +**Fix applied:** Convenience methods added to `Context`: +- `Send(string text, CancellationToken)` -> delegates to `SendAsync` +- `Send(TeamsActivity activity, CancellationToken)` -> delegates to `SendAsync` +- ~~`Send(AdaptiveCard card, CancellationToken)`~~ **DEFERRED** — review later to avoid Teams.Cards dependency +- `Reply(string text, CancellationToken)` -> delegates to `ReplyAsync` +- `Reply(TeamsActivity activity, CancellationToken)` -> delegates to `ReplyAsync` +- ~~`Reply(AdaptiveCard card, CancellationToken)`~~ **DEFERRED** — same reason +- `Typing(string? text, CancellationToken)` -> delegates to `TypingAsync` -**File:** Invoke response types in core project +**File:** `core/src/Microsoft.Teams.Apps/Context.cs` --- -### BC-13: Activity type hierarchy changed (MEDIUM - affects type usage) +### BC-2: No `context.Log` logger (12 samples affected) -**Decision: DOC-ONLY** +**Decision: IMPLEMENTED** — `context.Log` with `.Info()`, `.Error()`, `.Debug()` delegating to `ILogger` -**Old:** Activities come from `Microsoft.Teams.Api.Activities` (e.g., `MessageActivity`, `InvokeActivity`) -**New:** Activities come from `Microsoft.Teams.Apps.Schema` (e.g., `MessageActivity : TeamsActivity`) +**Old API:** +```csharp +context.Log.Info("message"); +context.Log.Error("error"); +context.Log.Debug("debug"); +``` -**Migration:** Namespace imports change but member access stays the same. Provide namespace mapping table in migration docs. +**Samples affected:** Echo, Cards, Dialogs, Graph, Meetings, MessageExtensions, Reactions, TargetedMessages, Tab, Lights, BotBuilder, Deprecated.Controllers + +**Fix applied:** `Log` property added to `Context` as `ContextLogger`, exposing `.Info()`, `.Error()`, `.Debug()`, `.Warn()` methods delegating to `ILogger`. + +**File:** `core/src/Microsoft.Teams.Apps/Context.cs` --- -### BC-14: `app.AddTab()` missing (1 sample affected) +### BC-5: No `context.AppId` (1 sample affected) -**Decision: REVIEW LATER** +**Decision: IMPLEMENTED** **Old API:** ```csharp -app.AddTab("dialog-form", "Web/dialog-form"); +context.Log.Info(context.AppId); ``` -**New API:** No `AddTab()` method. +**Samples affected:** Echo -**Samples affected:** Dialogs, Tab +**Fix applied:** `AppId` property added to `Context` delegating to `TeamsBotApplication.AppId`. -**Note:** Need to determine if `AddTab()` is just static file serving or also registers Teams tab config endpoints. This affects whether a simple "use `app.UseStaticFiles()`" migration note is sufficient. +**File:** `core/src/Microsoft.Teams.Apps/Context.cs` --- -## Sample Migration Difficulty Assessment +### BC-6: App.Builder() pattern removed (2 samples affected) -| Sample | Difficulty | Key Blockers | -|--------|-----------|-------------| -| Samples.Echo | **Easy** | BC-1 (Send/Typing), BC-2 (Log), BC-3 (OnActivity/Next), BC-5 (AppId), BC-7 (AddTeams) | -| Samples.Cards | **Easy** | BC-1 (Send), BC-2 (Log), BC-7, BC-12 (InvokeResponse) | -| Samples.Reactions | **Easy** | BC-1 (Send), BC-2 (Log), BC-7 | -| Samples.Threading | **Easy** | BC-1 (Send/Reply), BC-4 (Ref), BC-7, BC-8 (proactive) | -| Samples.Dialogs | **Easy-Med** | BC-1 (Send), BC-2 (Log), BC-7, BC-12, BC-14 (AddTab) | -| Samples.MessageExtensions | **Easy-Med** | BC-1, BC-2, BC-7, BC-11 (OnSetting), BC-12 | -| Samples.TargetedMessages | **Easy-Med** | BC-1 (Send/Reply), BC-2, BC-3 (OnActivity), BC-7 | -| Samples.Meetings | **Medium** | BC-1, BC-2, BC-3 (Use/Next), BC-6 (Builder), BC-7, BC-10 (renames) | -| Samples.Graph | **Medium-Hard** | BC-1, BC-2, BC-3 (Use/Next), BC-6 (Builder), BC-7, BC-9 (SignIn events) | -| Samples.BotBuilder | **Hard** | Entire `AddBotBuilder<>()` pattern missing | -| Deprecated.Controllers | **N/A** | Already deprecated, no migration needed | +**Decision: IMPLEMENTED** — `App.Builder()` added as a wrapper around ASP.NET DI ---- +**Old API:** +```csharp +var appBuilder = App.Builder() + .AddLogger(new ConsoleLogger(...)) + .AddOAuth("graph"); +builder.AddTeams(appBuilder); +``` -## Implementation Plan (ordered by impact) +**Samples affected:** Graph, Meetings -### Item 1: Add `Send()`, `Reply()`, `Typing()` convenience methods to Context -- **File:** `core/src/Microsoft.Teams.Apps/Context.cs` -- **Impact:** Resolves BC-1, unblocks ALL samples -- **Details:** Add methods matching old signatures (except AdaptiveCard overloads — deferred). `Reply()` builds a threaded reply using `Activity.Conversation.Id` and `Activity.Id`. +**Fix applied:** `AppBuilder` class added (`core/src/Microsoft.Teams.Apps/AppBuilder.cs`) wrapping `TeamsBotApplicationOptions`. `AddTeams(WebApplicationBuilder, AppBuilder)` overload added to `TeamsBotApplication.HostingExtensions.cs`. -### Item 2: Add `context.Log` with `.Info()`, `.Error()`, `.Debug()` delegating to ILogger -- **File:** `core/src/Microsoft.Teams.Apps/Context.cs` -- **Impact:** Resolves BC-2, unblocks 12 samples -- **Details:** Expose a `Log` property with `.Info()`, `.Error()`, `.Debug()` methods that delegate to `Microsoft.Extensions.Logging.ILogger` from DI. Preserves old API surface. +--- -### Item 3: Add `WebApplicationBuilder.AddTeams()` extension -- **File:** `core/src/Microsoft.Teams.Apps/TeamsBotApplication.HostingExtensions.cs` -- **Impact:** Resolves BC-7, unblocks ALL samples -- **Details:** Parameterless `public static IServiceCollection AddTeams(this WebApplicationBuilder builder) => builder.Services.AddTeams();` +### BC-7: `AddTeams()` extension target changed (ALL samples affected) -### Item 4: Add `AppId` property to Context -- **File:** `core/src/Microsoft.Teams.Apps/Context.cs` -- **Impact:** Resolves BC-5 -- **Details:** `AppId` sourced from `TeamsBotApplication.AppId`. +**Decision: IMPLEMENTED** — parameterless overload on `WebApplicationBuilder` -### Item 5: Add `App.Builder()` wrapper around ASP.NET DI -- **Impact:** Resolves BC-6, unblocks Graph and Meetings samples -- **Details:** `App.Builder()` returns a builder that wraps standard ASP.NET DI options pattern. +**Old API:** +```csharp +builder.AddTeams(); // on WebApplicationBuilder +builder.AddTeams(appBuilder); // with App.Builder +``` -### Item 6: Add `OnMeetingJoin`/`OnMeetingLeave` aliases -- **File:** `core/src/Microsoft.Teams.Apps/Handlers/MeetingExtensions.cs` -- **Impact:** Resolves BC-10 -- **Details:** Aliases to `OnMeetingParticipantJoin`/`OnMeetingParticipantLeave`. No `[Obsolete]` for now. +**New API:** +```csharp +builder.Services.AddTeams(); // on IServiceCollection +``` -### Item 7: Add proactive `Send()`/`Reply()` on TeamsBotApplication -- **File:** `core/src/Microsoft.Teams.Apps/TeamsBotApplication.cs` or extension -- **Impact:** Resolves BC-8, unblocks Threading sample +**Samples affected:** All -### Item 8: Add `InvokeResponse.Ok()`/`InvokeResponse.Error()` factory methods -- **Impact:** Resolves BC-12 -- **File:** Invoke response types in core project +**Fix applied:** Parameterless `AddTeams(this WebApplicationBuilder builder)` extension method added, delegating to `builder.Services.AddTeams()`. -### Item 9: Document migration for architectural changes (no code) -- `context.Ref` (BC-4): `context.Ref.Conversation.Id` -> `context.Activity.Conversation.Id` -- SignIn events (BC-9): `teams.OnSignIn()` -> `flow.OnSignInComplete()` (existing context.OnSignIn covers compat) -- Namespace changes (BC-13): Provide mapping table +**File:** `core/src/Microsoft.Teams.Apps/TeamsBotApplication.HostingExtensions.cs` --- -## API Surface Gaps (from systematic comparison) +### BC-8: Proactive messaging from app-level (1 sample affected) -These were identified by comparing the full public API surface between old and new libraries, beyond what the sample-driven analysis caught. +**Decision: IMPLEMENTED** -### BC-15: MessageActivity fluent methods removed +**Old API:** +```csharp +await teams.Send(conversationId, "text", cancellationToken: ct); +await teams.Reply(conversationId, messageId, "text", ct); +``` -**Decision: IMPLEMENTED** — MessageActivity fluent extension methods added. +**Samples affected:** Threading -Methods added: `WithText()`, `AddText()`, `WithSuggestedActions()`, `WithTextFormat()`, `WithAttachmentLayout()`, `AddAttachment()`, `AddStreamFinal()`. +**Fix applied:** `Send(string conversationId, string text, ...)` and `Reply(string conversationId, string messageId, string text, ...)` convenience methods added on `TeamsBotApplication`, delegating to `SendAsync`/`ReplyAsync`. -Not migrated (low priority, underlying properties commented out): `WithSpeak()`, `WithInputHint()`, `WithSummary()`, `WithImportance()`, `WithDeliveryMode()`, `WithExpiration()`, `Merge()`. +**File:** `core/src/Microsoft.Teams.Apps/TeamsBotApplication.cs` --- -### BC-16: `AddSensitivityLabel()` missing on TeamsActivity +### BC-10: Meeting handler renames (1 sample affected) -**Decision: IMPLEMENTED** — Extension method added in `MessageActivityExtensions`. +**Decision: IMPLEMENTED** — aliases without `[Obsolete]` ---- +**Old API:** +```csharp +teams.OnMeetingJoin(handler); +teams.OnMeetingLeave(handler); +``` -### BC-17: Base Activity fluent `With*()` methods removed +**New API:** +```csharp +teams.OnMeetingParticipantJoin(handler); +teams.OnMeetingParticipantLeave(handler); +``` -**Decision: IMPLEMENTED (mostly)** — Base activity fluent methods added. +**Samples affected:** Meetings -- **With* methods:** `WithId`, `WithChannelId`, `WithFrom`, `WithRecipient`, `WithRecipient(..., bool isTargeted)`, `WithConversation`, `WithServiceUrl`, `WithLocale`, `WithTimestamp`, `WithLocalTimestamp`, `WithData(ChannelData)`, `WithData(string, object?)`, `WithAppId` -- **Add* methods:** `AddEntity`, `UpdateEntity`, `AddAIGenerated`, `AddFeedback(bool)`, `AddTargetedMessageInfo`, `AddCitation`, `AddMention`, `AddSensitivityLabel`, `AddClientInfo` -- **Get* methods:** `GetAccountMention` +**Fix applied:** `OnMeetingJoin()` and `OnMeetingLeave()` aliases added, delegating to `OnMeetingParticipantJoin`/`OnMeetingParticipantLeave`. No `[Obsolete]` for now. -Remaining gap: `WithRelatesTo` is still not migrated because core currently has no `ConversationReference` model. +**File:** `core/src/Microsoft.Teams.Apps/Handlers/MeetingHandler.cs` --- -### BC-18: Activity conversion methods removed (`ToMessage()`, `ToInvoke()`, etc.) +### BC-12: Invoke handler return types changed (4 samples affected) -**Decision: NOT MIGRATED** — The old library had `ToMessage()`, `ToInvoke()`, `ToEvent()`, etc. The new library uses `FromActivity()` static factory methods instead: +**Decision: IMPLEMENTED** — factory methods only (no implicit conversions) +**Old API:** Handlers return library-specific response types: ```csharp -// Old: activity.ToMessage() -// New: MessageActivity.FromActivity(coreActivity) +// AdaptiveCardAction returns ActionResponse +return new ActionResponse.Message("text") { StatusCode = 400 }; + +// TaskFetch/Submit returns Microsoft.Teams.Api.TaskModules.Response +return new Microsoft.Teams.Api.TaskModules.Response(...); + +// MessageExtension returns Microsoft.Teams.Api.MessageExtensions.Response +return response; ``` ---- +**New API:** Handlers return `InvokeResponse` or `InvokeResponse`: +```csharp +Task AdaptiveCardActionHandler(...) +Task> TaskModuleHandler(...) +Task> MessageExtensionQueryHandler(...) +``` -### BC-19: Missing activity types +**Samples affected:** Cards, Dialogs, MessageExtensions, Lights -**Decision: REVIEW LATER** +**Fix applied:** Factory methods added: +- `InvokeResponse.Ok(body)` — wraps body with 200 status +- `InvokeResponse.Error(status, body)` — wraps body with error status -| Missing Type | Notes | -|---|---| -| `TypingActivity` | No class in new lib; typing handled via `TeamsActivityType.Typing` | -| `EndOfConversationActivity` | Commented out / TODO | -| `CommandActivity` / `CommandResultActivity` | Commented out / TODO | -| `ConversationReference` | Entire class missing; no direct replacement | +**File:** `core/src/Microsoft.Teams.Apps/Handlers/InvokeHandler.Response.cs` --- -### BC-20: Missing handler registration methods - -**Decision: REVIEW LATER** — 18 handler methods exist in the old library but not in the new. +### BC-15: MessageActivity fluent methods removed -**Tab handlers (completely removed):** -- `OnTabFetch`, `OnTabSubmit`, `OnConfigFetch`, `OnConfigSubmit` +**Decision: IMPLEMENTED** — MessageActivity fluent extension methods added. -**Command handlers (removed):** -- `OnCommand`, `OnCommandResult` +Methods added: `WithText()`, `AddText()`, `WithSuggestedActions()`, `WithTextFormat()`, `WithAttachmentLayout()`, `AddAttachment()`, `AddStreamFinal()`. -**Infrastructure events (architectural change):** -- `OnActivity`, `OnError`, `OnStart`, `OnActivityResponse`, `OnActivitySent` +Not migrated (low priority): `WithSummary()`, `WithDeliveryMode()`, `Merge()`. +Not migrated (now deprecated in old lib — not a breaking change): `WithSpeak()`, `WithInputHint()`, `WithImportance()`, `WithExpiration()`. -**Auth events (restructured to per-flow):** -- `OnSignIn`, `OnSignInFailure`, `OnTokenExchange`, `OnVerifyState` +--- -**Other removed handlers:** -- `OnTyping`, `OnHandoff`, `OnFeedback`, `OnExecuteAction` +### BC-16: `AddSensitivityLabel()` missing on TeamsActivity -**Commented out in new library:** -- `OnSetting`, `OnCardButtonClicked`, `OnTypeaheadSearch`, `OnAnswerSearch`, `OnReadReceipt` +**Decision: IMPLEMENTED** — Extension method added in `MessageActivityExtensions`. --- -### BC-21: Type incompatibilities +### BC-17: Base Activity fluent `With*()` methods removed -**Decision: NOT MIGRATED** — Intentional architectural changes. +**Decision: IMPLEMENTED (mostly)** — Base activity fluent methods added. -| Property | Old Type | New Type | -|---|---|---| -| `Timestamp`, `LocalTimestamp` | `DateTime?` | `string?` | -| `ServiceUrl` | `string?` | `Uri?` | -| `ContentUrl`, `ThumbnailUrl` (Attachment) | `string?` | `Uri?` | -| Enums (`TextFormat`, `InputHint`, etc.) | Enum types | String constants | -| `Account` | Custom `Account` class | `ConversationAccount` | +- **With* methods:** `WithId`, `WithChannelId`, `WithFrom`, `WithRecipient`, `WithRecipient(..., bool isTargeted)`, `WithConversation`, `WithServiceUrl`, `WithLocale`, `WithTimestamp`, `WithLocalTimestamp`, `WithData(ChannelData)`, `WithData(string, object?)`, `WithAppId` +- **Add* methods:** `AddEntity`, `UpdateEntity`, `AddAIGenerated`, `AddFeedback(bool)`, `AddTargetedMessageInfo`, `AddCitation`, `AddMention`, `AddSensitivityLabel`, `AddClientInfo` +- **Get* methods:** `GetAccountMention` + +Remaining gap: `WithRelatesTo` — no longer a concern since `RelatesTo` is marked `[Obsolete("This will be removed by end of summer 2026.")]` in commit 6f33aba. --- ### BC-22: `Conversation.ToThreadedConversationId()` missing -**Decision: REVIEW LATER** — Static utility method for constructing threaded conversation IDs. Used by Threading sample. The new `TeamsBotApplication.Reply()` handles this internally, but direct usage in sample code would break. +**Decision: IMPLEMENTED** — Available as `ConversationExtensions.ToThreadedConversationId(conversationId, messageId)` in `Microsoft.Teams.Core`. Note: in the old library this was a static method on the `Conversation` class; in the new library it lives on `ConversationExtensions`. Direct callers will need a minor namespace/type adjustment, but the functionality is available and `TeamsBotApplication.Reply()` uses it internally. ---- - -### BC-23: MessageActivity commented-out properties - -**Decision: REVIEW LATER** — These properties exist in the old library but are commented out in the new: -`Speak`, `InputHint`, `Summary`, `Importance`, `DeliveryMode`, `Expiration`, `Value` +**File:** `core/src/Microsoft.Teams.Core/Schema/ConversationExtensions.cs` --- -### BC-24: SuggestedActions fluent methods removed - -**Decision: NOT MIGRATED** — Old `SuggestedActions` had `AddRecipients()`, `AddAction()`, `AddActions()` fluent methods. Use direct property assignment instead. - ---- +## Sample Migration Difficulty Assessment -## Items to Review Later +"Remaining Blockers" lists only pending library-side work. Implemented items (BC-1, 2, 5, 6, 7, 8, 10, 12, 15, 16, 17, 22) are no longer blockers. -- **BC-1 (partial):** `Send(AdaptiveCard)` / `Reply(AdaptiveCard)` — blocked on Teams.Cards dependency decision -- **BC-3:** Middleware / `OnActivity` / `Use()` / `Next()` — need to investigate sample usage patterns -- **BC-11:** `OnSetting()` handler — need to clarify activity type/invoke name -- **BC-14:** `AddTab()` — need to determine if it's static files only or also tab config endpoints -- **BC-19:** Missing activity types (`TypingActivity`, `EndOfConversationActivity`, `CommandActivity`) -- **BC-20:** Missing handler registration methods (Tab, Command, Infrastructure, commented-out) -- **BC-22:** `Conversation.ToThreadedConversationId()` static utility -- **BC-23:** MessageActivity commented-out properties +| Sample | Difficulty | Remaining Blockers | +|--------|-----------|-------------| +| Samples.Cards | **Ready** | None | +| Samples.Reactions | **Ready** | None | +| Samples.Threading | **Ready** | BC-4 (doc-only: `context.Ref` → `context.Activity.Conversation`) | +| Samples.Echo | **Easy** | BC-3 (OnActivity/Next — pending) | +| Samples.TargetedMessages | **Easy** | BC-3 (OnActivity — pending) | +| Samples.Meetings | **Easy** | BC-3 (Use/Next — pending) | +| Samples.Dialogs | **Easy** | BC-14 (AddTab — pending) | +| Samples.MessageExtensions | **Easy** | BC-20 (OnSetting — pending) | +| Samples.Graph | **Easy-Med** | BC-3 (Use/Next — pending), BC-9 (SignIn events — doc-only) | +| Samples.BotBuilder | **Hard** | Entire `AddBotBuilder<>()` pattern missing | +| Deprecated.Controllers | **N/A** | Already deprecated, no migration needed | --- From 975724083b0b95f4d4424c0dfdbca3affafc585a Mon Sep 17 00:00:00 2001 From: Mehak Bindra Date: Fri, 22 May 2026 14:12:13 -0700 Subject: [PATCH 2/3] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- core/docs/ReduceBreakingChangesPlan.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/core/docs/ReduceBreakingChangesPlan.md b/core/docs/ReduceBreakingChangesPlan.md index 666991ea..11b2f95d 100644 --- a/core/docs/ReduceBreakingChangesPlan.md +++ b/core/docs/ReduceBreakingChangesPlan.md @@ -417,7 +417,7 @@ Remaining gap: `WithRelatesTo` — no longer a concern since `RelatesTo` is mark ### BC-22: `Conversation.ToThreadedConversationId()` missing -**Decision: IMPLEMENTED** — Available as `ConversationExtensions.ToThreadedConversationId(conversationId, messageId)` in `Microsoft.Teams.Core`. Note: in the old library this was a static method on the `Conversation` class; in the new library it lives on `ConversationExtensions`. Direct callers will need a minor namespace/type adjustment, but the functionality is available and `TeamsBotApplication.Reply()` uses it internally. +**Decision: IMPLEMENTED** — Available as `Microsoft.Teams.Core.Schema.ConversationExtensions.ToThreadedConversationId(conversationId, messageId)`. Note: in the old library this was a static method on the `Conversation` class; in the new library it lives on `ConversationExtensions` in the `Microsoft.Teams.Core.Schema` namespace. Direct callers will need a minor namespace/type adjustment, but the functionality is available and `TeamsBotApplication.Reply()` uses it internally. **File:** `core/src/Microsoft.Teams.Core/Schema/ConversationExtensions.cs` From 6e73a858a53795019ef111c6d07eee6e716fe33e Mon Sep 17 00:00:00 2001 From: Mehak Bindra Date: Fri, 22 May 2026 14:14:16 -0700 Subject: [PATCH 3/3] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- core/docs/ReduceBreakingChangesPlan.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/core/docs/ReduceBreakingChangesPlan.md b/core/docs/ReduceBreakingChangesPlan.md index 11b2f95d..e9b0f8b9 100644 --- a/core/docs/ReduceBreakingChangesPlan.md +++ b/core/docs/ReduceBreakingChangesPlan.md @@ -41,7 +41,7 @@ teams.OnActivity(async (context, cancellationToken) => { --- -### BC-14: `app.AddTab()` missing (1 sample affected) +### BC-14: `app.AddTab()` missing (2 samples affected) **Decision: REVIEW LATER**