Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
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.
Without work item filtering, Durable Task Scheduler delivers all work items to every connected worker — regardless of what each worker actually implements. This causes errors or silent hangs in multi-service deployments and rolling upgrades. With work item filtering, each worker declares the orchestrations and activities it hosts, and the scheduler routes work items only to matching workers.
- Set up and run the Durable Task Scheduler emulator for local development.
- Run the Orchestrator, Validator, and Shipper workers and the client.
- Verify that work items are routed only to matching workers.
- Deploy the sample to Azure Container Apps using Azure Developer CLI.
Prerequisites
Before you begin:
- Install .NET 10 SDK or later.
- Install Docker for running the emulator.
- Install Azure Developer CLI.
- Clone the Durable Task Scheduler GitHub repository.
Prepare the project
From the Azure-Samples/Durable-Task-Scheduler root directory, navigate to the sample directory:
cd samples/scenarios/WorkItemFilteringSplitActivities
Run locally with the emulator
Pull the emulator image:
docker pull mcr.microsoft.com/durable-task/emulator:latestRun the emulator:
docker run -d --name dts-emulator -p 8080:8080 -p 8082:8082 mcr.microsoft.com/durable-task/emulator:latestBuild the sample:
dotnet buildRun each worker in a separate terminal:
Terminal 1 - Orchestrator worker
dotnet run --project src/OrchestratorWorkerTerminal 2 - Validator worker
dotnet run --project src/ValidatorWorkerTerminal 3 - Shipper worker
dotnet run --project src/ShipperWorkerIn a fourth terminal, run the client:
dotnet run --project src/ClientOpen the emulator dashboard at
http://localhost:8082to monitor orchestration activity.
Tip
As an alternative to opening four terminals manually, you can run the included convenience script:
./run-local.sh
It starts the emulator, builds the solution, and launches all workers and the client.
Expected output from work item filtering
You should see:
- The client scheduling orchestration batches and waiting for completion.
- The Orchestrator worker dispatching
ValidateOrderandShipOrderactivity calls. - The Validator worker handling only
ValidateOrderactivity work items. - The Shipper worker handling only
ShipOrderactivity work items.
This behavior confirms that work item filtering routes items only to workers that registered matching task types.
Try it: Strict routing experiment
To see that routing is strict (no fallback to other workers):
- Stop the Shipper worker (Ctrl+C in Terminal 3).
- Run the client again to schedule new orchestrations.
- Observe that:
- The Orchestrator worker picks up and starts orchestrations.
- The Validator worker completes
ValidateOrderfor each order. ShipOrderwork items remain pending — they aren't delivered to the Validator or Orchestrator worker.- The orchestrations stay in "Running" status, waiting for
ShipOrderto complete.
- Restart the Shipper worker — the pending
ShipOrderwork items are delivered immediately and the orchestrations complete.
This demonstrates that work items are routed only to workers with matching filters. There is no fallback.
Deploy using Azure Developer CLI
Authenticate with Azure (if you haven't already):
azd auth loginFrom
samples/scenarios/WorkItemFilteringSplitActivities, run:azd upWhen prompted in the terminal, provide the following parameters:
Parameter Description Environment Name Prefix for the resource group created to hold all Azure resources. Azure Location The Azure location for your resources. Azure Subscription The Azure subscription for your resources.
The azd up command provisions Azure resources and deploys four containerized services from this sample: client, orchestrator worker, validator worker, and shipper worker.
Confirm successful deployment
In the
azd upoutput, copy the resource group name.In the Azure portal, open that resource group.
For each deployed container app (
client,orchestrator-worker,validator-worker,shipper-worker), open Monitoring > Log stream.Verify each app logs only its expected work items:
orchestrator-worker: orchestration work.validator-worker:ValidateOrderactivity.shipper-worker:ShipOrderactivity.
Note
Each Container App is configured with a KEDA scale rule (azure-durabletask-scheduler) that automatically scales workers from 0 to 10 replicas based on the pending work item backlog. When the client finishes its loop and no work items remain, workers scale back to zero. For more information, see Durable Task Scheduler autoscale on Azure Container Apps.
Understand the work item filtering code
The orchestration calls two activities in sequence. The scheduler routes each activity work item to the worker that registered it.
public override async Task<string> RunAsync(TaskOrchestrationContext context, string orderId)
{
string validationResult = await context.CallActivityAsync<string>("ValidateOrder", orderId);
string shippingResult = await context.CallActivityAsync<string>("ShipOrder", orderId);
return $"Order '{orderId}' => Validation: [{validationResult}], Shipping: [{shippingResult}]";
}
Each worker registers only its local tasks and calls UseWorkItemFilters() to opt in to filtering. The SDK then generates work item filters from the task registry.
builder.Services.AddDurableTaskWorker()
.AddTasks(registry =>
{
registry.AddAllGeneratedTasks();
})
.UseWorkItemFilters()
.UseDurableTaskScheduler(connectionString);
Note
Starting in version 1.23.0 of the .NET Durable Task SDK, work item filters are no longer enabled by default. You must explicitly call UseWorkItemFilters() on each worker to enable filtering. Workers that don't call it receive all work item types as before.
For example:
OrchestratorWorkerregistersOrderProcessingOrchestration.ValidatorWorkerregistersValidateOrder.ShipperWorkerregistersShipOrder.
When a worker connects to Durable Task Scheduler, the SDK sends its filter list. The scheduler creates per-filter queues and routes each work item to the matching queue. Workers never receive work item types they didn't register.
Clean up resources
Stop the local emulator container:
docker rm -f dts-emulatorIf you deployed to Azure, identify the resource group name:
- Copy it from the
azd upoutput. - Or in the Azure portal, use the global search box at the top and search for
rg-or your environment name prefix.
- Copy it from the
Open the resource group from the search results.
Select Delete resource group, enter the resource group name to confirm, and then select Delete.
Next steps
- Learn more about Durable Task Scheduler autoscale on Azure Container Apps.
- Review troubleshooting guidance.