Microsoft Teams Core/activity extensions更新の変更点と移行・展開時の注意点

Microsoft Teamsの「Core/activity extensions」更新は、Teamsクライアントの画面やテナント設定を変えるアップデートではなく、Teams SDK coreでActivity関連の拡張メソッドを整理し、引用、引用元表示、メンション、ターゲットメッセージなどの扱いを新しいAPIパターンへ寄せる変更です。影響を受けるのは主に、C#/.NETでMicrosoft TeamsアプリやBotを開発している開発者、SDK移行を進めているチーム、サンプルコードをもとに実装している保守担当者です。

結論から言うと、既存のTeams利用者や一般管理者がすぐに操作を変更する必要はありません。一方で、Teams SDK coreを使ったコードで WithQuote、Activityの With*() メソッド、引用・Citation・Targeted Message関連の直接操作を使っている場合は、ビルドエラーや挙動差を避けるために移行確認が必要です。Microsoft公式GitHubのPR #515は、Activity entity拡張メソッドの整理、移行ガイドとBreaking change資料の更新、古い AllFeatures サンプルの削除を含む変更としてマージされています。(GitHub)

Microsoft TeamsのCore/activity extensions更新で何が変わるのか

今回の「Microsoft Teams documentation update: Core/activity extensions」は、Teams SDK core内でActivityに付随するEntity操作をより分かりやすく整理するための更新です。

Activityとは、Teams BotやTeamsアプリが送受信するメッセージ、メンション、入力中表示、引用、カード操作などを表す基本的なデータ構造です。Microsoft LearnのActivity Type Referenceでも、message、typing、mention、Message Extension関連のルートなどがActivityとして扱われています。(Microsoft Learn)

今回の変更では、Activityに含まれるEntityを「Activity全体に雑多にぶら下げる」形から、Entityごとの拡張メソッドに分けて扱う方向に整理されています。たとえば、引用は QuotedReplyEntityExtensions、Citationは CitationEntityExtensions、メンションは MentionEntityExtensions のように、責務が分かりやすいクラスへ移されています。

変更領域	主な内容	実務上の意味
Activity Entity拡張メソッド	引用、Citation、メンション、Targeted MessageなどをEntity単位の拡張メソッドへ整理	どのEntityを操作しているかがコード上で分かりやすくなる
Builderパターン	`TeamsActivityBuilder` を使う書き方が推奨される	Activity生成時の記述をチェーン形式で統一しやすい
MessageActivity拡張	`MessageActivityExtensions` に `WithText()`、`AddQuote()`、`AddCitation()` などを追加	既存のメッセージ操作を移行しやすい
移行ガイド	Breaking changeと移行例を更新	古いAPIから新しいAPIへ置き換える判断材料になる
サンプル整理	古い `AllFeatures` サンプルを削除し、QuotingやTeamsBotサンプルを更新	サンプル依存の実装は参照先の見直しが必要

PRの説明では、ActivityQuotedReplyExtensions.cs と ActivityTargetedMessageInfoExtensions.cs が削除され、引用、Citation、メンションなどのEntity別拡張クラスへロジックが移されたとされています。(GitHub)

影響を受ける対象者

今回の更新で最も影響を受けるのは、Microsoft Teamsの利用者全体ではなく、Teams SDK coreを使ってTeamsアプリを実装している開発者です。

影響が大きいケース

次のようなコードや運用をしている場合は、変更内容を確認する優先度が高くなります。

対象	確認すべき理由
C#/.NETでTeams Botを開発しているチーム	ActivityやMessageActivityのAPI変更がビルド・送信処理に影響する可能性がある
引用返信を実装しているBot	`WithQuote` から `AddQuote` への移行が必要になる可能性がある
AI応答にCitationやFeedbackを付けているアプリ	`AddCitation()`、`AddAIGenerated()`、`AddFeedback()` の新しい使い方を確認すべき
Targeted Messageを扱うアプリ	`TargetedMessageInfoEntityExtensions` へ整理されたため、既存コードの参照先を確認する必要がある
公式サンプルをコピーして実装しているプロジェクト	`AllFeatures` サンプルが削除され、QuotingやTeamsBotサンプルも書き換えられている
SDK移行中のプロジェクト	MigrationGuideとReduceBreakingChangesPlanの更新を前提に移行計画を見直すべき

反対に、Teamsのチャット、会議、チャネル、ファイル共有を通常利用している一般ユーザーには、直接の操作変更は基本的にありません。Teams管理センターでテナント全体のポリシーを急いで変更する類のアップデートでもありません。

開発者が押さえるべき主な変更点

Activity Entityの取得メソッドがEntity別に整理された

MigrationGuideでは、Activity Entityの取得ヘルパーがEntityスコープの拡張メソッドとして公開されることが示されています。例として、GetMentions()、GetQuotedMessages()、GetCitation()、GetStreamInfo()、GetTargetedMessageInfo()、GetProductInfo()、GetMessageEntity() などが挙げられています。(GitHub)

実務では、「Activityの中に何が入っているか」を手作業でEntityリストから探すより、目的別の Get* メソッドを使った方が安全です。

たとえば、メンションを処理するコードなら、Entity配列を直接走査するより次のような考え方に寄せます。

var mentions = activity.GetMentions();

引用返信を扱う場合は次のように取得します。

var quotedMessages = activity.GetQuotedMessages();

Citationを扱う場合は次のように取得します。

var citation = activity.GetCitation();

この整理により、コードレビュー時にも「これはCitationを見ている処理」「これはQuoted Replyを見ている処理」と判断しやすくなります。

`WithQuote` より `AddQuote` を使う流れになる

Quotingサンプルでは、古い WithQuote() の例が削除され、AddQuote() を使うBuilderベースの書き方へ更新されています。PRの差分では、TeamsActivity.CreateBuilder() に WithType(TeamsActivityType.Message) を指定したうえで、.AddQuote(...) をつなぐ形へ変わっています。(GitHub)

移行前のイメージは次のようなコードです。

TeamsActivity reply = TeamsActivity.CreateBuilder()
    .WithType(TeamsActivityType.Message)
    .WithQuote(sent.Id, "Verified — all smoke tests passing.")
    .Build();

移行後は、次のように AddQuote() を使う形が中心になります。

TeamsActivity msg = TeamsActivity.CreateBuilder()
    .WithType(TeamsActivityType.Message)
    .AddQuote(sent.Id, "Done! Left my comments on the PR.")
    .Build();

注意点は、AddQuote() はメッセージActivityに対して使う前提であることです。TeamsActivityBuilder 側の実装では、Activity typeがMessageでない場合に例外を投げるようになっています。(GitHub)

つまり、引用返信を作るときは次の順序を守るのが安全です。

手順	確認内容
1	`TeamsActivity.CreateBuilder()` でBuilderを作成する
2	`.WithType(TeamsActivityType.Message)` を指定する
3	`.AddQuote(messageId, text)` で引用を追加する
4	`.Build()` でActivityを生成する
5	`SendActivityAsync()` などで送信する

AddQuote() だけを見て移行すると、Activity typeの指定漏れで実行時エラーになる可能性があります。移行時は、置換だけでなくBuilderチェーン全体を確認してください。

Citation、AI生成ラベル、FeedbackはBuilderでまとめやすくなった

TeamsBotサンプルでは、Citationを付けた応答を MessageActivity に直接追加する書き方から、TeamsActivity.CreateBuilder() で組み立てる書き方へ更新されています。具体的には、.WithText()、.WithProperty("textFormat", TextFormats.Markdown)、.AddCitation()、.AddAIGenerated()、.AddFeedback() をチェーンする形です。(GitHub)

新しい書き方のイメージは次のとおりです。

TeamsActivity reply = TeamsActivity.CreateBuilder()
    .WithType(TeamsActivityType.Message)
    .WithText("Here is a response with citations [1] [2].")
    .WithProperty("textFormat", TextFormats.Markdown)
    .AddCitation(1, new CitationAppearance()
    {
        Name = "Teams SDK Documentation",
        Abstract = "The Teams Bot SDK provides a streamlined way to build bots for Microsoft Teams.",
        Url = new Uri("https://github.com/microsoft/teams.net"),
        Icon = CitationIcon.Text
    })
    .AddAIGenerated()
    .AddFeedback()
    .Build();

AI応答をTeamsに返すアプリでは、この変更は重要です。生成AIの回答に出典表示、AI生成ラベル、フィードバック導線を付ける実装が、Activity生成時にまとまりやすくなります。

ただし、Citationの位置番号と本文中の [1] [2] のような表記がずれると、ユーザーに誤解を与えます。実装時は、本文テキスト、Citationの position、表示名、URLをセットでテストしてください。

`MessageActivityExtensions` にFluent APIが追加された

MessageActivityExtensions.cs には、WithId()、WithChannelId()、WithFrom()、WithRecipient()、WithConversation()、WithServiceUrl()、WithLocale()、WithTimestamp()、WithData()、WithAppId() など、多くの With* 系メソッドが追加されています。さらに、WithText()、AddText()、AddAttachment()、AddQuote()、AddMention()、AddStreamFinal()、AddAIGenerated()、AddSensitivityLabel()、AddFeedback()、AddCitation() なども提供されています。(GitHub)

移行時のポイントは、すべてをBuilderへ寄せる必要はないことです。MigrationGuideでは、推奨される新しい書き方として TeamsActivityBuilder を示しつつ、MessageActivity 上の拡張メソッドも利用できると説明されています。(GitHub)

判断基準は次のように考えると実務で迷いにくくなります。

実装パターン	向いているケース
`TeamsActivityBuilder`	新しくActivityを組み立てる処理、引用・Citation・Feedbackをまとめて設定する処理
`MessageActivityExtensions`	既存の `MessageActivity` に対して小さく機能を追加する処理
Entity別の `Get*` メソッド	受信Activityからメンション、引用、Citationなどを読み取る処理

新規開発ではBuilder中心、既存コードの小規模改修では MessageActivityExtensions を使う、という分け方が現実的です。

管理者が確認すべきポイント

今回のCore/activity extensions更新は、Teams管理センターのポリシー変更を伴う更新ではありません。ただし、社内でTeamsアプリやBotを運用している場合、管理者にも確認すべき点があります。

社内アプリの開発・運用担当にSDK利用状況を確認する

管理者が最初にすべきことは、テナント設定の変更ではなく、社内で使っているTeamsアプリの棚卸しです。

特に次のアプリは確認対象です。

確認対象	理由
社内Bot	Activity送受信処理を直接使っている可能性が高い
生成AI連携Bot	Citation、Feedback、AI生成ラベルを使う可能性がある
承認・通知Bot	引用返信やメンションを使っている可能性がある
Message Extension	Activity routeやinvoke処理の移行影響を受ける可能性がある
公式サンプルをベースにしたPoC	サンプル削除・書き換えの影響を受けやすい

管理者がコードを読む必要はありません。開発担当に対して、次の3点を確認すれば十分です。

1. Microsoft.Teams.Apps / Teams SDK coreを使っているか
2. 引用返信、Citation、Targeted Message、メンション処理を実装しているか
3. SDK更新時にMigrationGuideの該当箇所を確認したか

Teamsクライアントの利用者向け告知は基本的に不要

今回の変更はSDK内部と開発者向けドキュメントの整理が中心です。一般ユーザーに「Teamsの操作が変わる」と告知する必要は通常ありません。

ただし、社内Botの改修に伴って、Botの返信形式が変わる場合は別です。たとえば、引用付き返信の見た目、AI回答の出典表示、フィードバックボタンの表示が変わる場合は、利用部門に事前共有しておくと問い合わせを減らせます。

アプリ展開前に検証環境で確認する

SDKやサンプル更新後のコードを本番展開する前に、少なくとも次の動作を検証してください。

検証項目	確認内容
通常メッセージ送信	`message` Activityとして正常に送れるか
引用返信	引用対象のメッセージIDが正しく反映されるか
複数引用	複数の `AddQuote()` を使った場合に表示が崩れないか
Citation	本文中の番号とCitationの位置が一致するか
メンション	対象ユーザーに正しくメンション通知されるか
Targeted Message	意図したユーザーだけに表示・処理されるか
例外処理	Message以外のActivityで `AddQuote()` を呼んでいないか

特に引用返信は、表示上は問題なく見えても、Entityの中身が期待どおりでないと後続処理で失敗することがあります。UIの見た目だけでなく、送信されるActivityのJSONやログも確認してください。

移行時に確認したいAPI変更

Activityの `With*()` はBuilderまたはMessageActivity拡張へ移す

MigrationGuideでは、古いActivityの With*() メソッドは、推奨パターンとして TeamsActivityBuilder を使う形に移行することが示されています。加えて、MessageActivity には多くの With*() メソッドが拡張メソッドとして提供されています。(GitHub)

古い書き方の例です。

var activity = new Activity()
    .WithFrom(account)
    .WithConversation(conv);

推奨されるBuilderベースの例です。

var activity = new TeamsActivityBuilder()
    .WithFrom(account)
    .WithConversation(conv)
    .Build();

MessageActivity を直接扱う場合は、次のような書き方もできます。

var activity = new MessageActivity()
    .WithFrom(account)
    .WithConversation(conv)
    .WithChannelId("msteams");

ただし、WithRelatesTo はcore側に ConversationReference 相当がないため未対応とされています。(GitHub)

Activity変換メソッドはFactoryへ置き換える

MigrationGuideでは、Activity変換メソッドの移行例として、古い activity.ToMessage() から新しい MessageActivity.FromActivity(coreActivity) への変更が示されています。(GitHub)

移行前です。

var msg = activity.ToMessage();

移行後です。

var msg = MessageActivity.FromActivity(coreActivity);

この変更は、単純なメソッド名変更に見えますが、型の扱いが変わるため注意が必要です。変換後に Text、From、Conversation、Value などを参照している箇所は、null許容や型の違いもあわせて確認してください。

一部の型変更にも注意する

MigrationGuideでは、旧ライブラリと新ライブラリの型互換性の違いも整理されています。たとえば、Timestamp と LocalTimestamp は DateTime? から string?、ServiceUrl は string? から Uri?、Attachmentの ContentUrl や ThumbnailUrl も Uri? として扱われる変更が示されています。(GitHub)

移行時に見落としやすいのは、コンパイルエラーにならない周辺コードです。たとえば、ログ出力や独自DTOへのマッピングで ServiceUrl を文字列として保存している場合、Uri から文字列への変換を明示する必要があります。

確認すべき例です。

var serviceUrl = activity.ServiceUrl?.ToString();

日時も同様に、文字列として受け取る前提に変わる場合があります。アプリ内で日時計算をしているなら、パース処理やタイムゾーンの扱いを必ず確認してください。

サンプル削除・更新による注意点

今回のPRでは、古い AllFeatures サンプルプロジェクトと関連ファイルが削除されています。また、Quoting と TeamsBot のサンプルコードは、新しいBuilderパターンと拡張メソッドを使う形に更新されています。(GitHub)

これにより、過去に AllFeatures サンプルをコピーして作ったPoCや社内テンプレートは、今後の参照元として使いにくくなります。特に、社内Wikiや手順書に古いサンプルへのリンクを貼っている場合は、早めに差し替えてください。

おすすめの見直し方は次のとおりです。

見直し対象	対応
社内テンプレート	`TeamsActivityBuilder` ベースの最小構成へ更新
引用返信サンプル	`WithQuote()` ではなく `AddQuote()` を使う例に修正
Citationサンプル	`AddCitation()`、`AddAIGenerated()`、`AddFeedback()` の組み合わせを確認
社内ドキュメント	削除された `AllFeatures` へのリンクを削除
CIのサンプルビルド	削除されたプロジェクトを参照していないか確認

公式サンプルは便利ですが、そのまま長期間固定して使うと、SDK更新時に差分が大きくなります。Teamsアプリの社内テンプレートは、引用、Citation、メンション、Targeted Messageなど機能別に小さなサンプルへ分けて管理する方が保守しやすくなります。

実務での移行チェックリスト

Core/activity extensions更新に対応する際は、次の順序で確認すると無駄がありません。

順番	作業	判断基準
1	SDK利用箇所を洗い出す	`Microsoft.Teams.Apps`、`TeamsActivity`、`MessageActivity` を検索する
2	引用関連コードを確認する	`WithQuote`、`AddQuote`、`QuotedReply` を検索する
3	Citation関連コードを確認する	`AddCitation`、`CitationEntity`、`CitationAppearance` を検索する
4	Targeted Messageを確認する	`TargetedMessageInfo`、`isTargeted` を検索する
5	`With*()` の古い使い方を確認する	Builderまたは `MessageActivityExtensions` へ移す
6	サンプル参照を更新する	`AllFeatures` 依存がないか確認する
7	検証環境でE2Eテストする	送信、返信、引用、Citation、メンションを実画面で確認する

移行では、検索置換だけに頼らないことが重要です。たとえば WithQuote を AddQuote に置き換えても、Activity typeをMessageにしていなければ動かない可能性があります。AddQuote() の前に .WithType(TeamsActivityType.Message) があるかまで確認してください。

失敗しやすいポイント

Activity typeの指定漏れ

AddQuote() やTargeted Message関連のBuilderメソッドは、Message Activityとして使う前提です。Activity typeが未指定のまま呼び出すと、実行時例外につながる可能性があります。

悪い例です。

var msg = TeamsActivity.CreateBuilder()
    .AddQuote(messageId, "確認しました")
    .Build();

安全な例です。

var msg = TeamsActivity.CreateBuilder()
    .WithType(TeamsActivityType.Message)
    .AddQuote(messageId, "確認しました")
    .Build();

Entityの直接操作を続けてしまう

旧コードで activity.Entities を直接操作している場合、動作することもありますが、今後の保守性は下がります。引用、Citation、メンション、Sensitivity Labelなどは、できるだけEntity別の拡張メソッドを使ってください。

悪い例です。

activity.Entities.Add(entity);

改善例です。

activity.AddCitation(position, appearance);
activity.AddMention(account);
activity.AddSensitivityLabel("Confidential");

Citation番号と本文がずれる

AI回答やナレッジ検索Botでは、本文中に [1] [2] のような出典番号を出し、ActivityのCitation Entityにも番号を持たせます。本文を後から編集したり、Citationの追加順序を変えたりすると、表示上の番号と実際の出典がずれることがあります。

本番投入前には、次の観点で確認してください。

確認項目	チェック内容
本文	`[1]` `[2]` の表示が自然か
Citation position	本文中の番号と一致しているか
URL	正しい資料にリンクしているか
表示名	ユーザーが出典を理解できる名称か
フォールバック	URLなしのCitationでも表示が崩れないか

古いサンプルを社内標準として残してしまう

AllFeatures サンプルが削除されたため、古い社内資料でこのサンプルを前提にしている場合、今後の新人教育やPoC作成で混乱が起きやすくなります。

社内標準として残すなら、「全部入りサンプル」ではなく、次のような小さな単位に分けるのがおすすめです。

- message-basic
- quoting-reply
- citation-response
- mention-user
- targeted-message
- adaptive-card-message

機能単位で分けると、SDK更新時にも影響範囲を切り分けやすくなります。

管理者・開発者別の対応まとめ

Teams管理者がやること

Teams管理者は、Teams管理センターで即時設定変更するよりも、社内アプリの影響確認を優先してください。

優先度	対応
高	社内BotやTeamsアプリの開発担当にSDK利用状況を確認する
高	本番Botの改修予定がある場合、検証環境で引用・Citation・メンションを確認する
中	社内手順書に古いサンプルリンクがないか確認する
中	利用部門に影響が出るUI変更がある場合のみ事前告知する
低	Teams一般ユーザー向けの操作案内を更新する

開発者がやること

開発者は、コード上のActivity操作を中心に確認してください。

優先度	対応
高	`WithQuote`、`ActivityQuotedReplyExtensions`、`ActivityTargetedMessageInfoExtensions` の参照を検索する
高	`TeamsActivityBuilder` と `MessageActivityExtensions` の新しい使い方へ移行する
高	`AddQuote()` の前にMessage Activity typeが設定されているか確認する
中	Citation、AI生成ラベル、Feedbackの表示テストを行う
中	`ServiceUrl` やTimestampなどの型変更に伴うマッピングを確認する
低	削除された `AllFeatures` サンプル依存を整理する

今回の更新をどう受け止めるべきか

Microsoft TeamsのCore/activity extensions更新は、派手な新機能追加というより、SDK coreのActivity操作を長期的に保守しやすくするための整理です。引用、Citation、Targeted Message、メンションのようなTeamsらしいメッセージ機能を、Entityごとの拡張メソッドとBuilderパターンで扱いやすくする意図が見えます。

管理者は、テナント設定を急いで変更する必要はありません。まずは社内でTeams SDK coreを使っているアプリがあるかを確認してください。開発者は、WithQuote や古いActivity With*() メソッドを検索し、TeamsActivityBuilder、MessageActivityExtensions、Entity別の Get* メソッドへ移行できるかを確認するのが次の一歩です。

特に生成AI連携Botやナレッジ検索Botでは、Citation、AI生成ラベル、Feedbackの実装品質がユーザーの信頼に直結します。今回の更新を機に、単にビルドを通すだけでなく、引用元表示、対象ユーザー、メンション通知、フィードバック導線まで含めて検証しておくと、今後のTeamsアプリ運用が安定します。

この記事を書いた人

佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

Microsoft Teams Core/activity extensions更新の変更点と移行・展開時の注意点

Microsoft TeamsのCore/activity extensions更新で何が変わるのか

影響を受ける対象者

影響が大きいケース

開発者が押さえるべき主な変更点

Activity Entityの取得メソッドがEntity別に整理された

`WithQuote` より `AddQuote` を使う流れになる

Citation、AI生成ラベル、FeedbackはBuilderでまとめやすくなった

`MessageActivityExtensions` にFluent APIが追加された

管理者が確認すべきポイント

社内アプリの開発・運用担当にSDK利用状況を確認する

Teamsクライアントの利用者向け告知は基本的に不要

アプリ展開前に検証環境で確認する

移行時に確認したいAPI変更

Activityの `With*()` はBuilderまたはMessageActivity拡張へ移す

Activity変換メソッドはFactoryへ置き換える

一部の型変更にも注意する

サンプル削除・更新による注意点

実務での移行チェックリスト

失敗しやすいポイント

Activity typeの指定漏れ

Entityの直接操作を続けてしまう

Citation番号と本文がずれる

古いサンプルを社内標準として残してしまう

管理者・開発者別の対応まとめ

Teams管理者がやること

開発者がやること

今回の更新をどう受け止めるべきか

この記事を書いた人

コメント

コメントするコメントをキャンセル

Microsoft Teams Core/activity extensions更新の変更点と移行・展開時の注意点

Microsoft TeamsのCore/activity extensions更新で何が変わるのか

影響を受ける対象者

影響が大きいケース

開発者が押さえるべき主な変更点

Activity Entityの取得メソッドがEntity別に整理された

WithQuote より AddQuote を使う流れになる

Citation、AI生成ラベル、FeedbackはBuilderでまとめやすくなった

MessageActivityExtensions にFluent APIが追加された

管理者が確認すべきポイント

社内アプリの開発・運用担当にSDK利用状況を確認する

Teamsクライアントの利用者向け告知は基本的に不要

アプリ展開前に検証環境で確認する

移行時に確認したいAPI変更

Activityの With*() はBuilderまたはMessageActivity拡張へ移す

Activity変換メソッドはFactoryへ置き換える

一部の型変更にも注意する

サンプル削除・更新による注意点

実務での移行チェックリスト

失敗しやすいポイント

Activity typeの指定漏れ

Entityの直接操作を続けてしまう

Citation番号と本文がずれる

古いサンプルを社内標準として残してしまう

管理者・開発者別の対応まとめ

Teams管理者がやること

開発者がやること

今回の更新をどう受け止めるべきか

この記事を書いた人

関連記事

コメント

コメントする コメントをキャンセル

`WithQuote` より `AddQuote` を使う流れになる

`MessageActivityExtensions` にFluent APIが追加された

Activityの `With*()` はBuilderまたはMessageActivity拡張へ移す

コメントするコメントをキャンセル