Azure Durable Task SDK 1.23.0のwork item filtering変更点｜UseWorkItemFilters()明示指定が必要に

2026年5月上旬のAzureドキュメント更新で、.NET Durable Task SDKのwork item filteringはv1.23.0以降、既定で有効にならず、明示的なオプトインが必要になりました。対応の要点はシンプルです。Durable Task Schedulerでワークアイテムの振り分けを使っているワーカーに、UseWorkItemFilters() を追加してください。

この変更を見落とすと、複数のワーカーに処理を分担している構成で、各ワーカーが想定外のオーケストレーションやアクティビティを受け取る可能性があります。特に、Orchestrator用、Validator用、Shipper用のように役割を分けているアプリでは、SDK更新後の挙動確認が必要です。

Azure Durable Task SDK v1.23.0で何が変わったのか

今回のAzureドキュメント更新は、Durable Task Schedulerのクイックスタートに対して、.NET Durable Task SDK v1.23.0 以降のwork item filteringの扱いを反映するものです。GitHubのPRでは、v1.23.0以降、work item filtersが既定で有効ではなくなり、サンプルコードに UseWorkItemFilters() を追加する変更が行われています。(GitHub)

変更前後のポイントは次のとおりです。

観点	変更前に期待されやすかった理解	v1.23.0以降で確認すべき理解
work item filtering	タスク登録によりフィルターが使われると考えがち	`UseWorkItemFilters()` を呼ばないと有効にならない
ワーカーの受け取り対象	登録したタスクに合うワークアイテムのみを受け取る想定	オプトインしないワーカーは、すべての種類のワークアイテムを受け取る可能性がある
必要な対応	サンプルどおりにタスクを登録する	各ワーカーの構成で `UseWorkItemFilters()` を明示的に追加する
影響が出やすい構成	単一ワーカー構成では気づきにくい	複数ワーカー、分割サービス、ローリングアップグレードで影響が出やすい

Microsoft Learnの該当クイックスタートでも、各ワーカーはローカルのタスクを登録したうえで UseWorkItemFilters() を呼び出し、SDKがタスクレジストリからwork item filtersを生成すると説明されています。(Microsoft Learn)

work item filteringとは何か

work item filteringは、Durable Task Schedulerがワークアイテムを適切なワーカーへ配送するための仕組みです。

たとえば、注文処理のアプリを次の3つのワーカーに分けているとします。

ワーカー	登録する処理	受け取りたいワークアイテム
OrchestratorWorker	`OrderProcessingOrchestration`	オーケストレーション処理
ValidatorWorker	`ValidateOrder`	注文検証アクティビティ
ShipperWorker	`ShipOrder`	出荷アクティビティ

work item filteringが有効であれば、ValidateOrder はValidatorWorkerへ、ShipOrder はShipperWorkerへ配送されます。一方、フィルターが有効でない場合、Durable Task Schedulerは接続された各ワーカーへワークアイテムを広く配送するため、ワーカーが実装していない処理を受け取る可能性があります。Microsoft Learnでは、work item filteringがない場合、すべての接続ワーカーにワークアイテムが配送され、複数サービス構成やローリングアップグレードでエラーや停止状態につながる可能性があると説明されています。(Microsoft Learn)

対応が必要な人

今回のAzure documentation updateで特に確認すべきなのは、次のような開発者・運用担当者です。

対象	対応優先度	確認すべき内容
.NET Durable Task SDKをv1.23.0以降へ更新する予定がある	高	`UseWorkItemFilters()` の追加漏れがないか
Durable Task Schedulerで複数ワーカー構成を使っている	高	各ワーカーが担当タスクだけを受け取っているか
Azure Container Appsへワーカーを分けてデプロイしている	高	デプロイ後のログで配送先が想定どおりか
ローリングアップグレードを行う	中〜高	新旧バージョン混在時の受け取り挙動
単一ワーカーで全処理をまとめている	低〜中	将来の分割に備えて設定方針を確認

特に注意したいのは、「ビルドが通る」ことと「ワークアイテムが正しく配送される」ことは別という点です。UseWorkItemFilters() の追加漏れは、コンパイルエラーとして見つかるとは限りません。実行時に、意図しないワーカーが処理を受け取る形で表面化する可能性があります。

追加すべき設定

v1.23.0以降でwork item filteringを使う場合、ワーカー構成に UseWorkItemFilters() を追加します。

builder.Services.AddDurableTaskWorker()
    .AddTasks(registry =>
    {
        registry.AddAllGeneratedTasks();
    })
    .UseWorkItemFilters()
    .UseDurableTaskScheduler(connectionString);

ポイントは、AddTasks() でタスクを登録するだけで終わらせないことです。Microsoft Learnの更新後サンプルでは、各ワーカーがローカルタスクを登録し、UseWorkItemFilters() を呼び出してフィルタリングにオプトインする形になっています。(Microsoft Learn)

各ワーカーで個別に確認する

複数ワーカー構成では、1か所だけ修正しても不十分です。OrchestratorWorker、ValidatorWorker、ShipperWorkerなど、Durable Task Schedulerへ接続する各ワーカーで設定を確認してください。

確認の観点は次のとおりです。

確認項目	見る場所	判断基準
`UseWorkItemFilters()` が呼ばれているか	各ワーカーのDI設定、Program.csなど	Durable Task Workerの設定チェーンに含まれている
登録タスクがワーカーの役割と一致しているか	`AddTasks()` の登録内容	ValidatorWorkerに出荷処理など不要なタスクが入っていない
実行ログが想定どおりか	ローカル実行ログ、Azure Container AppsのLog stream	各ワーカーが担当する処理だけを実行している
停止時の挙動が想定どおりか	特定ワーカーを停止して再実行	担当外ワーカーへフォールバックしない

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

SDK更新時は、単にパッケージバージョンを上げるだけでなく、ワーカーの役割分担まで確認する必要があります。次の順番で進めると、設定漏れを見つけやすくなります。

| 手順 | 作業 | 目的 |
| -: | ————————————— | —————————– |
| 1 | 利用中の.NET Durable Task SDKバージョンを確認する | v1.23.0以降の影響を受けるか判断する |
| 2 | Durable Task Schedulerへ接続するワーカーを一覧化する | 修正対象を漏らさない |
| 3 | 各ワーカーの AddDurableTaskWorker() 設定を確認する | UseWorkItemFilters() の有無を見る |
| 4 | 各ワーカーの登録タスクを確認する | フィルター対象が適切か判断する |
| 5 | ローカルまたはステージングで複数ワーカーを起動する | 実配送の挙動を確認する |
| 6 | 特定ワーカーを停止して再実行する | 担当外ワーカーへ流れないことを確認する |
| 7 | 本番反映前にログ監視条件を決める | 移行後の異常検知を早める |

この変更は、コード上では1行追加に見えます。しかし実務では、ワーカー分割の設計が正しく反映されているかを確認する機会として扱うべきです。

影響が出やすいシナリオ

複数サービスにアクティビティを分割している

注文処理、決済、在庫確認、配送などを別々のワーカーに分けている場合、work item filteringは重要です。

たとえば、在庫確認専用ワーカーが決済アクティビティを受け取ってしまうと、処理できずにエラーになるか、期待した進行にならない可能性があります。ワーカーごとの責務を明確にしている構成ほど、UseWorkItemFilters() の追加漏れは影響が大きくなります。

ローリングアップグレード中に新旧ワーカーが混在する

ローリングアップグレードでは、一時的に異なるバージョンのワーカーが同時に動作します。このとき、一部のワーカーだけがwork item filteringにオプトインしていないと、配送ルールの見え方が複雑になります。

本番環境でローリングアップグレードを行う場合は、事前にステージング環境で次を確認してください。

新旧ワーカー混在時に、担当外のワークアイテムを受け取らないか
途中停止したワーカーの担当ワークアイテムが、別ワーカーに誤配送されないか
未処理ワークアイテムが保留される場合、それが設計どおりか
ログに実装されていないタスク名のエラーが出ていないか

Microsoft Learnのクイックスタートでは、Shipper workerを停止すると ShipOrder のワークアイテムは他のワーカーへ配送されず、Shipper workerを再起動すると保留中のワークアイテムが配送される例が示されています。これは、フィルタリングが有効な状態ではフォールバック配送が行われないことを確認する実験として有用です。(Microsoft Learn)

Azure Container Appsでスケールアウトしている

Azure Container Apps上で複数のワーカーを動かしている場合、ログ確認が重要です。Microsoft Learnの手順では、デプロイ後に各Container AppのLog streamを開き、orchestrator-worker、validator-worker、shipper-worker がそれぞれ期待されるワークアイテムだけを処理しているか確認する流れが示されています。(Microsoft Learn)

スケールアウト構成では、問題が一部のレプリカだけで発生することがあります。移行直後は、成功ログだけでなく、担当外タスク名、ハンドラー未登録、処理待ちの増加も確認してください。

よくある失敗と回避策

失敗しやすいポイント	起きること	回避策
`AddTasks()` だけで設定完了と思い込む	フィルターが有効にならない	`UseWorkItemFilters()` の有無を必ず確認する
一部のワーカーだけ修正する	ワーカー間で挙動がそろわない	Durable Task Scheduler接続ワーカーを一覧化して全件確認する
ローカル単一ワーカーでしかテストしない	複数ワーカー特有の誤配送に気づけない	役割別ワーカーを同時に起動して確認する
成功パスだけ確認する	ワーカー停止時の保留や配送ルールを見落とす	特定ワーカー停止テストを行う
ログ監視を用意しない	本番移行後の異常検知が遅れる	担当外タスク名や未登録ハンドラーのログを監視する

特に、クイックスタートのサンプルを過去にコピーして社内テンプレート化している場合は注意が必要です。古いテンプレートには UseWorkItemFilters() が含まれていない可能性があります。SDKをv1.23.0以降に更新する前に、テンプレート、共通ライブラリ、サンプルリポジトリをまとめて確認してください。

設定後に確認すべきログの見方

UseWorkItemFilters() を追加した後は、各ワーカーが「起動した」だけでは不十分です。次の観点でログを確認します。

正常と判断しやすいログ

正常な状態では、各ワーカーのログに担当する処理だけが現れます。

ワーカー	正常なログの例
OrchestratorWorker	オーケストレーション開始、アクティビティ呼び出し
ValidatorWorker	`ValidateOrder` の処理
ShipperWorker	`ShipOrder` の処理

注意すべきログ

次のようなログが出る場合は、work item filteringの設定漏れやタスク登録の誤りを疑います。

ログの傾向	疑うべき原因
ValidatorWorkerに `ShipOrder` 関連のログが出る	フィルター未設定、またはタスク登録の誤り
ワーカーが未実装のタスクを受け取っている	`UseWorkItemFilters()` の追加漏れ
特定アクティビティだけ処理待ちが増える	担当ワーカー停止、フィルター設定、スケール設定の確認が必要
ローリングアップグレード中だけエラーが増える	新旧ワーカー間で設定がそろっていない可能性

ログ確認では、「エラーがないか」だけでなく、どのワーカーがどの処理を担当したかを見てください。work item filteringの目的は、処理を成功させることだけでなく、ワーカーの責務どおりに配送することです。

既存プロジェクトでの判断基準

今回の変更に対して、すべてのプロジェクトで同じ緊急度になるわけではありません。次の基準で対応優先度を決めるとよいでしょう。

プロジェクトの状態	推奨対応
v1.23.0以降へ更新済みで、複数ワーカー構成	すぐに `UseWorkItemFilters()` とログを確認する
v1.23.0以降へ更新予定	更新前の作業項目に設定確認を追加する
v1.23.0未満で、今後更新予定なし	直ちに影響は限定的だが、将来更新時の注意点として記録する
単一ワーカー構成	影響は小さい可能性があるが、将来の分割に備えて設計を確認する
サンプルやテンプレートを配布している	コード例を更新し、利用者へ変更点を共有する

判断の軸は、SDKバージョンだけではありません。複数ワーカーに処理を分けているか、ローリングアップグレードを行うか、Azure Container Appsなどでスケール運用しているかを含めて確認してください。

チーム内で共有すべき内容

開発チームや運用チームに共有する場合は、次のように短くまとめると伝わりやすくなります。

.NET Durable Task SDK v1.23.0以降では、work item filteringが既定で有効にならない。
Durable Task Schedulerでワーカーごとの処理振り分けを使う場合は、
各ワーカーの AddDurableTaskWorker() 設定に UseWorkItemFilters() を追加する。
SDK更新時は、複数ワーカー構成とローリングアップグレード時の配送ログを確認する。

ドキュメント更新の本質は、「サンプルコードが変わった」ことではなく、フィルタリングを使う意思をコードで明示する必要があるという点です。この考え方をチーム内のレビュー観点に入れておくと、今後のSDK更新でも同じ種類の見落としを防ぎやすくなります。

まず取るべき行動

今回のAzure documentation updateを受けて、最初に行うべきことは3つです。

.NET Durable Task SDKの利用バージョンを確認する
Durable Task Schedulerへ接続する各ワーカーに UseWorkItemFilters() があるか確認する
ステージング環境で、各ワーカーが担当ワークアイテムだけを受け取るかログで確認する

v1.23.0以降へ更新するプロジェクトでは、UseWorkItemFilters() の追加を移行チェックリストに入れてください。特に複数ワーカー構成では、設定漏れが実行時の配送ミスとして現れやすいため、コードレビューとログ確認の両方でチェックすることが重要です。

この記事を書いた人

佐藤健司

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

Azure Durable Task SDK 1.23.0のwork item filtering変更点｜UseWorkItemFilters()明示指定が必要に

Azure Durable Task SDK v1.23.0で何が変わったのか

work item filteringとは何か

対応が必要な人