Skip to content

Commit d39cadc

Browse files
JamesJBarnettJamesJBarnett
authored
Merge pull request #312674 from hhunter-ms/work-item-filtering-quickstart
[Durable] Add and validate work item filtering quickstart
2 parents b0212ce + 86f6248 commit d39cadc

2 files changed

Lines changed: 183 additions & 0 deletions

File tree

‎articles/azure-functions/durable/TOC.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,9 @@
4141
href: ./durable-task-scheduler/quickstart-container-apps-durable-task-sdk.md
4242
- name: Host a .NET Durable Task SDK app on Azure Kubernetes Service
4343
href: ./durable-task-scheduler/quickstart-aks-durable-task-scheduler.md
44+
- name: Use work item filtering with the .NET Durable Task SDK
45+
displayName: get started, durable task scheduler
46+
href: ./durable-task-scheduler/quickstart-work-item-filtering-durable-task.md
4447
- name: Core concepts
4548
items:
4649
- name: Fundamentals

‎articles/azure-functions/durable/durable-task-scheduler/quickstart-work-item-filtering-durable-task.md‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
---
2+
title: "Quickstart: Use work item filtering with the .NET Durable Task SDK"
3+
description: Learn how to run a .NET Durable Task SDK sample that uses work item filtering with Durable Task Scheduler and deploy it to Azure Container Apps.
4+
ms.subservice: durable-task-scheduler
5+
ms.topic: quickstart
6+
ms.date: 03/05/2026
7+
ms.custom:
8+
- build-2025
9+
---
10+
11+
# Quickstart: Use work item filtering with the .NET Durable Task SDK
12+
13+
In this quickstart, you learn how to run a .NET Durable Task SDK sample that uses work item filtering to route orchestrations and activities to dedicated workers.
14+
15+
> [!div class="checklist"]
16+
>
17+
> - Set up and run the Durable Task Scheduler emulator for local development.
18+
> - Run the Orchestrator, Validator, and Shipper workers and the client.
19+
> - Verify that work items are routed only to matching workers.
20+
> - Deploy the sample to Azure Container Apps using Azure Developer CLI.
21+
22+
## Prerequisites
23+
24+
Before you begin:
25+
26+
- Install [.NET 10 SDK](https://dotnet.microsoft.com/download) or later.
27+
- Install [Docker](https://www.docker.com/products/docker-desktop/) for running the emulator.
28+
- Install [Azure Developer CLI](/azure/developer/azure-developer-cli/install-azd).
29+
- Clone the [Durable Task Scheduler GitHub repository](https://github.com/Azure-Samples/Durable-Task-Scheduler).
30+
31+
## Prepare the project
32+
33+
From the `Azure-Samples/Durable-Task-Scheduler` root directory, navigate to the sample directory:
34+
35+
```bash
36+
cd samples/scenarios/WorkItemFilteringSplitActivities
37+
```
38+
39+
## Run locally with the emulator
40+
41+
1. Pull the emulator image:
42+
43+
```bash
44+
docker pull mcr.microsoft.com/dts/dts-emulator:latest
45+
```
46+
47+
1. Run the emulator:
48+
49+
```bash
50+
docker run -d --name dts-emulator -p 8080:8080 -p 8082:8082 mcr.microsoft.com/dts/dts-emulator:latest
51+
```
52+
53+
1. Build the sample:
54+
55+
```bash
56+
dotnet build
57+
```
58+
59+
1. Run each worker in a separate terminal:
60+
61+
**Terminal 1 - Orchestrator worker**
62+
63+
```bash
64+
dotnet run --project src/OrchestratorWorker
65+
```
66+
67+
**Terminal 2 - Validator worker**
68+
69+
```bash
70+
dotnet run --project src/ValidatorWorker
71+
```
72+
73+
**Terminal 3 - Shipper worker**
74+
75+
```bash
76+
dotnet run --project src/ShipperWorker
77+
```
78+
79+
1. In a fourth terminal, run the client:
80+
81+
```bash
82+
dotnet run --project src/Client
83+
```
84+
85+
1. Open the emulator dashboard at `http://localhost:8082` to monitor orchestration activity.
86+
87+
### Expected output
88+
89+
You should see:
90+
91+
- The client scheduling orchestration batches and waiting for completion.
92+
- The Orchestrator worker dispatching `ValidateOrder` and `ShipOrder` activity calls.
93+
- The Validator worker handling only `ValidateOrder` activity work items.
94+
- The Shipper worker handling only `ShipOrder` activity work items.
95+
96+
This behavior confirms that work item filtering routes items only to workers that registered matching task types.
97+
98+
## Deploy using Azure Developer CLI
99+
100+
1. From `samples/scenarios/WorkItemFilteringSplitActivities`, run:
101+
102+
```azdeveloper
103+
azd up
104+
```
105+
106+
1. When prompted in the terminal, provide the following parameters:
107+
108+
| Parameter | Description |
109+
| --------- | ----------- |
110+
| Environment Name | Prefix for the resource group created to hold all Azure resources. |
111+
| Azure Location | The Azure location for your resources. |
112+
| Azure Subscription | The Azure subscription for your resources. |
113+
114+
The `azd up` command provisions Azure resources and deploys four containerized services from this sample: client, orchestrator worker, validator worker, and shipper worker.
115+
116+
## Confirm successful deployment
117+
118+
1. In the `azd up` output, copy the resource group name.
119+
1. In the [Azure portal](https://portal.azure.com), open that resource group.
120+
1. For each deployed container app (`client`, `orchestrator-worker`, `validator-worker`, `shipper-worker`), open **Monitoring** > **Log stream**.
121+
1. Verify each app logs only its expected work items:
122+
123+
- `orchestrator-worker`: orchestration work.
124+
- `validator-worker`: `ValidateOrder` activity.
125+
- `shipper-worker`: `ShipOrder` activity.
126+
127+
## Understanding the code
128+
129+
The orchestration calls two activities in sequence. The scheduler routes each activity work item to the worker that registered it.
130+
131+
```csharp
132+
public override async Task<string> RunAsync(TaskOrchestrationContext context, string orderId)
133+
{
134+
string validationResult = await context.CallActivityAsync<string>("ValidateOrder", orderId);
135+
string shippingResult = await context.CallActivityAsync<string>("ShipOrder", orderId);
136+
137+
return $"Order '{orderId}' => Validation: [{validationResult}], Shipping: [{shippingResult}]";
138+
}
139+
```
140+
141+
Each worker registers only its local tasks. The SDK generates work item filters from the task registry.
142+
143+
```csharp
144+
builder.Services.AddDurableTaskWorker()
145+
.AddTasks(registry =>
146+
{
147+
registry.AddAllGeneratedTasks();
148+
})
149+
.UseDurableTaskScheduler(connectionString);
150+
```
151+
152+
For example:
153+
154+
- `OrchestratorWorker` registers `OrderProcessingOrchestration`.
155+
- `ValidatorWorker` registers `ValidateOrder`.
156+
- `ShipperWorker` registers `ShipOrder`.
157+
158+
Because filters are derived from registration, workers don't receive unmatched work item types.
159+
160+
## Clean up resources
161+
162+
1. Stop the local emulator container:
163+
164+
```bash
165+
docker rm -f dts-emulator
166+
```
167+
168+
1. If you deployed to Azure, identify the resource group name:
169+
170+
- Copy it from the `azd up` output.
171+
- Or in the [Azure portal](https://portal.azure.com), use the global search box at the top and search for `rg-` or your environment name prefix.
172+
173+
1. Open the resource group from the search results.
174+
175+
1. Select **Delete resource group**, enter the resource group name to confirm, and then select **Delete**.
176+
177+
## Next steps
178+
179+
- Learn more about [Durable Task Scheduler autoscale on Azure Container Apps](./durable-task-scheduler-auto-scaling.md).
180+
- Review [troubleshooting guidance](./troubleshoot-durable-task-scheduler.md).

0 commit comments

Comments
 (0)