Quickstart: Use work item filtering with the .NET Durable Task SDK

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.

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

1. Pull the emulator image:

   docker pull mcr.microsoft.com/durable-task/emulator:latest
   

2. Run the emulator:

   docker run -d --name dts-emulator -p 8080:8080 -p 8082:8082 mcr.microsoft.com/durable-task/emulator:latest
   

3. Build the sample:

   dotnet build
   

4. Run each worker in a separate terminal:

   Terminal 1 - Orchestrator worker

   dotnet run --project src/OrchestratorWorker
   

   Terminal 2 - Validator worker

   dotnet run --project src/ValidatorWorker
   

   Terminal 3 - Shipper worker

   dotnet run --project src/ShipperWorker
   

5. In a fourth terminal, run the client:

   dotnet run --project src/Client
   

6. Open the emulator dashboard at http://localhost:8082 to monitor orchestration activity.

./run-local.sh

Expected output from work item filtering

You should see:

• The client scheduling orchestration batches and waiting for completion.
• The Orchestrator worker dispatching ValidateOrder and ShipOrder activity calls.
• The Validator worker handling only ValidateOrder activity work items.
• The Shipper worker handling only ShipOrder activity 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):

1. Stop the Shipper worker (Ctrl+C in Terminal 3).
2. Run the client again to schedule new orchestrations.
3. Observe that:
   • The Orchestrator worker picks up and starts orchestrations.
   • The Validator worker completes ValidateOrder for each order.
   • ShipOrder work items remain pending — they aren't delivered to the Validator or Orchestrator worker.
   • The orchestrations stay in "Running" status, waiting for ShipOrder to complete.
4. Restart the Shipper worker — the pending ShipOrder work 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

1. Authenticate with Azure (if you haven't already):

   azd auth login
   

2. From samples/scenarios/WorkItemFilteringSplitActivities, run:

   azd up
   

3. When 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

1. In the azd up output, copy the resource group name.

2. In the Azure portal, open that resource group.

3. For each deployed container app (client, orchestrator-worker, validator-worker, shipper-worker), open Monitoring > Log stream.

4. Verify each app logs only its expected work items:

   • orchestrator-worker: orchestration work.
   • validator-worker: ValidateOrder activity.
   • shipper-worker: ShipOrder activity.

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);

For example:

• OrchestratorWorker registers OrderProcessingOrchestration.
• ValidatorWorker registers ValidateOrder.
• ShipperWorker registers ShipOrder.

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

1. Stop the local emulator container:

   docker rm -f dts-emulator
   

2. If you deployed to Azure, identify the resource group name:

   • Copy it from the azd up output.
   • Or in the Azure portal, use the global search box at the top and search for rg- or your environment name prefix.

3. Open the resource group from the search results.

4. 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.