Skip to content

quickstart-durable-task-scheduler.md

Latest commit

 

History

History
247 lines (166 loc) · 8.92 KB

quickstart-durable-task-scheduler.md

File metadata and controls

247 lines (166 loc) · 8.92 KB
author hhunter-ms
ms.author hannahhunter
title Quickstart: Configure a Durable Functions app to use Durable Task Scheduler
titleSuffix Durable Task
description Learn how to configure an existing Durable Functions app to use Durable Task Scheduler as a backend.
ms.topic how-to
ms.service durable-task
ms.subservice durable-task-scheduler
ms.date 10/29/2025
zone_pivot_groups df-languages

Quickstart: Configure a Durable Functions app to use Durable Task Scheduler

Write stateful functions in a serverless environment using Durable Functions, a feature of Azure Functions. Scenarios where Durable Functions is useful include orchestrating microservices and workflows, stateful patterns like fan-out/fan-in, and long-running tasks.

You can use the Durable Task Scheduler as a backend for your Durable Functions, to store orchestration and entity runtime state.

In this quickstart, you:

[!div class="checklist"]

  • Configure an existing Durable Functions app to use the Durable Task Scheduler.
  • Set up the Durable Task emulator for local development.
  • Deploy your app to Azure on the App Service plan using Visual Studio Code.
  • Monitor the status of your app and task hub on the Durable Task Scheduler dashboard.

For C#, this quickstart uses the .NET isolated worker model.

Prerequisites

::: zone-end

::: zone pivot="javascript"

::: zone-end

::: zone pivot="python"

::: zone-end

::: zone pivot="powershell"

::: zone-end

::: zone pivot="java"

::: zone-end

Add the Durable Task Scheduler package

::: zone pivot="csharp"

Install the latest version of the Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged package by using the dotnet add package command:

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged --prerelease

Note

The Durable Task Scheduler extension requires Microsoft.Azure.Functions.Worker.Extensions.DurableTask version 1.2.2 or higher.

::: zone-end

::: zone pivot="javascript,python,java,powershell"

In host.json, update the extensionBundle property to use the preview version that contains the Durable Task Scheduler package:

{
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle.Preview",
    "version": "[4.29.0, 5.0.0)"
  }
}

::: zone-end

Update host.json

Update the host.json as follows to use Durable Task Scheduler as the backend.

{
  "extensions": {
    "durableTask": {
      "hubName": "%TASKHUB_NAME%",
      "storageProvider": {
        "type": "azureManaged",
        "connectionStringName": "DURABLE_TASK_SCHEDULER_CONNECTION_STRING"
      }
    }
  }
}

Configure local.settings.json

Add connection information for local development:

{
  "IsEncrypted": false,
  "Values": {
    "FUNCTIONS_WORKER_RUNTIME": "<DEPENDENT ON YOUR PROGRAMMING LANGUAGE>",
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "DURABLE_TASK_SCHEDULER_CONNECTION_STRING": "Endpoint=http://localhost:8080;Authentication=None",
    "TASKHUB_NAME": "default"
  }
}

Set up the Durable Task emulator

  1. Pull the docker image containing the emulator.

    docker pull mcr.microsoft.com/dts/dts-emulator:latest

  2. Run the emulator.

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

    The following output indicates the emulator started successfully.

    :::image type="content" source="media/quickstart-durable-task-scheduler/emulator-started.png" alt-text="Screenshot showing emulator started successfully on terminal.":::

  3. Make note of the ports exposed on Docker desktop. The scheduler exposes multiple ports for different purposes:

    • 8080: gRPC endpoint that allows an app to connect to the scheduler
    • 8082: Endpoint for Durable Task Scheduler dashboard

    :::image type="content" source="media/quickstart-durable-task-scheduler/docker-ports.png" alt-text="Screenshot of ports on Docker.":::

Note

The Durable Task Scheduler emulator stores orchestration data in memory, which means all data is lost when it shuts down.

Test locally

  1. Go to the root directory of your app and start Azurite.

    azurite start

  2. Run the application.

    func start

    You should see a list of the functions in your app.

  3. Start an orchestration instance by sending an HTTP POST request to the URL endpoint using the HTTP test tool you chose.

  4. Copy the URL value for statusQueryGetUri and paste it in your browser's address bar. You should see the status on the orchestration instance:

      {
    "name": "DurableFunctionsOrchestration",
    "instanceId": "<instanceID>",
    "runtimeStatus": "Completed",
    "input": null,
    "customStatus": null,
    "output": [
      "Hello Tokyo!",
      "Hello Seattle!",
      "Hello London!"
    ],
    "createdTime": "2025-02-21T21:09:59Z",
    "lastUpdatedTime": "2025-02-21T21:10:00Z"
  }

  5. To view more details about the orchestration instance, go to http://localhost:8082/ access the Durable Task Scheduler dashboard.

  6. Click on the default task hub to see its dashboard.

Running into issues testing? See the troubleshooting guide.

Run your app in Azure

Create required resources

Create a Durable Task Scheduler instance and Azure Functions app on Azure following the Function app integrated creation flow. This experience will automatically set up identity-based access and configure the required environment variables for the app to access the scheduler.

[!INCLUDE function-app-integrated-creation]

Resource deployment could take around 15 to 20 minutes. Once that is finished, you can deploy your app to Azure.

Deploy your function app to Azure

[!INCLUDE functions-publish-project-vscode]

Apps on Functions Premium plan

If your app is running on the Functions Premium plan, turn on the Runtime Scale Monitoring setting after deployment to ensure your app autoscales based on load:

az resource update -g <resource_group> -n <function_app_name>/config/web --set properties.functionsRuntimeScaleMonitoringEnabled=1 --resource-type Microsoft.Web/sites

Test your function app

Run the following command to get your function's URL:

az functionapp function list --resource-group <RESOURCE_GROUP_NAME> --name <FUNCTION_APP_NAME>  --query '[].{Function:name, URL:invokeUrlTemplate}' --output json

Check orchestration status

Check the status of the orchestration instance and activity details on the Durable Task Scheduler dashboard. Accessing the dashboard requires you to log in.

[!INCLUDE assign-dev-identity-role-based-access-control-portal]

Clean up resources

If you no longer need the resources that you created to complete the quickstart, to avoid related costs in your Azure subscription, delete the resource group and all related resources.

Next steps