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.

  • 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:

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/dts/dts-emulator:latest

  2. Run the emulator:

    docker run -d --name dts-emulator -p 8080:8080 -p 8082:8082 mcr.microsoft.com/dts/dts-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.

Expected output

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.

Deploy using Azure Developer CLI

  1. From samples/scenarios/WorkItemFilteringSplitActivities, run:

    azd up

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

Understanding the 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. The SDK generates work item filters from the task registry.

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

For example:

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

Because filters are derived from registration, workers don't receive unmatched work item types.

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

  • Last updated on