Develop with the Azure Functions durable task scheduler (preview)

  • Article

The Azure Functions durable task scheduler is a highly performant, fully managed backend provider for durable functions with an out-of-the-box monitoring dashboard. In this article, you learn how to:

  • Create a scheduler and task hub.
  • Configure identity-based authentication for your application to access durable task scheduler.
  • Monitor the status of your app and task hub on the durable task scheduler dashboard.

Learn more about durable task scheduler features, supported regions, and plans.

Prerequisites

Set up the CLI

  1. Log in to the Azure CLI and make sure you have the latest installed.

    az login
az upgrade

  2. Install the durable task scheduler CLI extension.

    az extension add --name durabletask

  3. If you already installed the durable task scheduler CLI extension, upgrade to the latest version.

    az extension add --upgrade --name durabletask

Run durable task emulator

  1. Pull the docker image containing the emulator.

    docker pull mcr.microsoft.com/dts/dts-emulator:v0.0.5

  2. Run the emulator.

    docker run -itP mcr.microsoft.com/dts/dts-emulator:v0.0.5

    This command exposes a single task hub named default. If you need more than one task hub, you can set the environment variable DTS_TASK_HUB_NAMES on the container to a comma-delimited list of task hub names like in the following command:

    docker run -itP -e DTS_TASK_HUB_NAMES=taskhub1,taskhub2,taskhub3 mcr.microsoft.com/dts/dts-emulator:v0.0.5

Create a scheduler and task hub

Note

Durable task scheduler currently supports apps hosted in the App Service and Functions Premium plans only.

  1. Create a resource group.

    az group create --name YOUR_RESOURCE_GROUP --location LOCATION

  2. Using the durabletask CLI extension, create a scheduler.

    az durabletask scheduler create --name "YOUR_SCHEDULER" --resource-group "YOUR_RESOURCE_GROUP" --location "LOCATION" --ip-allowlist "[0.0.0.0/0]" --sku-name "dedicated" --sku-capacity "1"

    The creation process may take up to 15 minutes to complete.

    Output

    {
    "id": "/subscriptions/YOUR_SUBSCRIPTION_ID/resourceGroups/YOUR_RESOURCE_GROUP/providers/Microsoft.DurableTask/schedulers/YOUR_SCHEDULER",
    "location": "chinanorth3",
    "name": "YOUR_SCHEDULER",
    "properties": {
        "endpoint": "https://YOUR_SCHEDULER.chinanorth3.durabletask.io",
        "ipAllowlist": [
            "0.0.0.0/0"
        ],
        "provisioningState": "Succeeded",
        "sku": {
            "capacity": 1,
            "name": "Dedicated",
            "redundancyState": "None"
        }
    },
    "resourceGroup": "YOUR_RESOURCE_GROUP",
    "systemData": {
        "createdAt": "2025-01-06T21:22:59Z",
        "createdBy": "YOUR_EMAIL@microsoft.com",
        "createdByType": "User",
        "lastModifiedAt": "2025-01-06T21:22:59Z",
        "lastModifiedBy": "YOUR_EMAIL@microsoft.com",
        "lastModifiedByType": "User"
    },
    "tags": {}
}

  3. Create a task hub.

    az durabletask taskhub create --resource-group YOUR_RESOURCE_GROUP --scheduler-name YOUR_SCHEDULER --name YOUR_TASKHUB

    Output

    {
  "id": "/subscriptions/YOUR_SUBSCRIPTION_ID/resourceGroups/YOUR_RESOURCE_GROUP/providers/Microsoft.DurableTask/schedulers/YOUR_SCHEDULERS/taskHubs/YOUR_TASKHUB",
  "name": "YOUR_TASKHUB",
  "properties": {
    "provisioningState": "Succeeded"
  },
  "resourceGroup": "YOUR_RESOURCE_GROUP",
  "systemData": {
    "createdAt": "2024-09-18T22:13:56.5467094Z",
    "createdBy": "OBJECT_ID",
    "createdByType": "User",
    "lastModifiedAt": "2024-09-18T22:13:56.5467094Z",
    "lastModifiedBy": "OBJECT_ID",
    "lastModifiedByType": "User"
  },
  "type": "microsoft.durabletask/scheduler/taskhubs"
}

You can create a scheduler and task hub on Azure portal via two ways:

  • Function app integrated creation: (recommended) automatically creates the managed identity resource and RBAC assignment, plus configures required environment variables for your app to access durable task scheduler.
  • Top-level creation: Requires you to manually assign RBAC permission to configure scheduler access for your app.

Note

Durable task scheduler currently supports apps hosted in the App Service and Functions Premium plans, so this experience is available only when either of these plan types is picked.

You can create a scheduler and a task hub as part of the Function app creation on Azure portal.

  1. Navigate to the Function app creation blade and select Functions Premium or App Service as a hosting option.

    Screenshot of hosting options for Function apps and selecting App Service.

  2. In the Create Function App (App Service) blade, fill in the information in the Basics tab.

    Screenshot of the Basic tab for creating an App Service plan Function app.

    Field Description
    Subscription Select your Azure subscription.
    Resource Group Select an existing resource group or click Create new to create a new one.
    Function App name Create a unique name for your function app.
    Do you want to deploy code or container image? Keep the Code option selected.
    Runtime stack Select the runtime you're using for this quickstart.
    Version Select your runtime stack version.
    Region Select one of the supported regions.
    Operating System Select your operating system.

  3. Select the Durable Functions tab.

  4. Choose Durable Task Scheduler as the backend provider for your durable functions.

  5. Create a scheduler resource. This action automatically creates a task hub.

    Screenshot of creating an App Service plan Function app.

    Field Description
    Storage backend Select Durable Task Scheduler.
    Region It's recommended that the scheduler and function app regions should be the same.
    Durable task scheduler Use the scheduler name offered, or click Create new to create a custom name.
    Plan Only Dedicated is available at the moment.
    Capacity units Currently, you can only choose one Capacity Unit as an option.

  6. Click Review + create to review the resource creation.

    A user-assigned managed identity with the required role-based access control (RBAC) permission is created automatically so that the Function app can access durable task scheduler. You can find in the summary view information related to the managed identity resource, such as:

    • The RBAC assigned to it (Durable Task Data Contributor)

    • The assignment scope (the scheduler or task hub name)

      Screenshot of fields and properties chosen and in review on the Review + create tab.

  7. Click Create once validation passes.

View all durable task scheduler resources in a subscription

  1. Get a list of all scheduler names within a subscription by running the following command.

    az durabletask scheduler list --subscription <SUBSCRIPTION_ID>

  2. You can narrow down results to a specific resource group by adding the --resource-group flag.

    az durabletask scheduler list --subscription <SUBSCRIPTION_ID> --resource-group <RESOURCE_GROUP_NAME>

In the Azure portal, search for Durable Task Scheduler and select it from the results.

Screenshot of searching for the durable task scheduler service in the portal.

You can see the list of scheduler resources created in all subscriptions you have access to.

View all task hubs in a durable task scheduler

Retrieve a list of task hubs in a specific scheduler by running:

az durabletask taskhub list --resource-group <RESOURCE_GROUP_NAME> --scheduler-name <SCHEDULER_NAME>

You can see all the task hubs created in a scheduler on the Overview of the resource on Azure portal.

Screenshot of overview tab of durable task scheduler in the portal.

Delete the scheduler and task hub

  1. Delete the scheduler:

    az durabletask scheduler --resource-group YOUR_RESOURCE_GROUP --scheduler-name YOUR_SCHEDULER

  2. Delete a task hub:

    az durabletask taskhub delete --resource-group YOUR_RESOURCE_GROUP --scheduler-name YOUR_SCHEDULER --name YOUR_TASKHUB

  1. Open the scheduler resource on Azure portal and click Delete:

    Screenshot of scheduler resource in the portal highlighting delete button.

  2. Find the scheduler with the task hub you want to delete, then click into that task hub. Click Delete:

    Screenshot of task hub resource in the portal highlighting delete button.

Configure identity-based authentication for app to access durable task scheduler

Durable task scheduler only supports either user-assigned or system-assigned managed identity authentication. User-assigned identities are recommended, as they aren't tied to the lifecycle of the app and can be reused after the app is deprovisioned.

The following are the durable task scheduler related roles you can grant to an identity:

  • Durable Task Data Contributor: Role for all data access operations. This role is a superset of all other roles.
  • Durable Task Worker: Role used by worker applications to interact with the durable task scheduler. Assign this role if your app is used only for processing orchestrations, activities, and entities.
  • Durable Task Data Reader: Role to read all durable task scheduler data. Assign this role if you only need a list of orchestrations and entities payloads.

Note

Most durable functions apps would require the Durable Task Data Contributor role.

The following sections demonstrate how to grant permissions to an identity resource and configure your durable functions app to use the identity for access to schedulers and task hubs.

Assign RBAC (role-based access control) to managed identity resource

  1. Create a user-assigned managed identity

    az identity create -g RESOURCE_GROUP_NAME -n IDENTITY_NAME

  2. Set the assignee to identity resource created

    assignee=$(az identity show --name IDENTITY_NAME --resource-group RESOURCE_GROUP_NAME --query 'clientId' --output tsv)

  3. Set the scope. Granting access on the scheduler scope gives access to all task hubs in that scheduler.

    Task Hub

    scope="/subscriptions/SUBSCRIPTION_ID/resourceGroups/RESOURCE_GROUP_NAME/providers/Microsoft.DurableTask/schedulers/SCHEDULER_NAME/taskHubs/TASKHUB_NAME"

    Scheduler

    scope="/subscriptions/SUBSCRIPTION_ID/resourceGroups/RESOURCE_GROUP_NAME/providers/Microsoft.DurableTask/schedulers/SCHEDULER_NAME"

  4. Grant access. Run the following command to create the role assignment and grant access.

    az role assignment create \
  --assignee "$assignee" \
  --role "Durable Task Data Contributor" \
  --scope "$scope"

    Expected output

    The following output example shows a developer identity assigned with the Durable Task Data Contributor role on the scheduler level:

    {
  "condition": null,
  "conditionVersion": null,
  "createdBy": "YOUR_DEVELOPER_CREDENTIAL_ID",
  "createdOn": "2024-12-20T01:36:45.022356+00:00",
  "delegatedManagedIdentityResourceId": null,
  "description": null,
  "id": "/subscriptions/YOUR_SUBSCRIPTION_ID/resourceGroups/YOUR_RESOURCE_GROUP/providers/Microsoft.DurableTask/schedulers/YOUR_DTS_NAME/providers/Microsoft.Authorization/roleAssignments/ROLE_ASSIGNMENT_ID",
  "name": "ROLE_ASSIGNMENT_ID",
  "principalId": "YOUR_DEVELOPER_CREDENTIAL_ID",
  "principalName": "YOUR_EMAIL",
  "principalType": "User",
  "resourceGroup": "YOUR_RESOURCE_GROUP",
  "roleDefinitionId": "/subscriptions/YOUR_SUBSCRIPTION/providers/Microsoft.Authorization/roleDefinitions/ROLE_DEFINITION_ID",
  "roleDefinitionName": "Durable Task Data Contributor",
  "scope": "/subscriptions/YOUR_SUBSCRIPTION/resourceGroups/YOUR_RESOURCE_GROUP/providers/Microsoft.DurableTask/schedulers/YOUR_DTS_NAME",
  "type": "Microsoft.Authorization/roleAssignments",
  "updatedBy": "YOUR_DEVELOPER_CREDENTIAL_ID",
  "updatedOn": "2024-12-20T01:36:45.022356+00:00"
}

Note

The following instruction shows a role assignment scoped to a specific task hub. If you need access to all task hubs in a scheduler, perform the assignment on the scheduler level.

  1. Create a user-assigned managed identity.

  2. Navigate to the durable task scheduler resource on the portal.

  3. Click on a task hub name.

  4. In the left menu, select Access control (IAM).

  5. Click Add to add a role assignment.

    Screenshot of the adding the role assignment on the Access Control pane in the portal.

  6. Search for and select Durable Task Data Contributor. Click Next.

    Screenshot of selecting the Durable Task Data Contributor role assignment in the portal.

  7. On the Members tab, for Assign access to, select Managed identity.

  8. For Members, click + Select members.

  9. In the Select managed identities pane, expand the Managed identity drop-down and select User-assigned managed identity.

    Screenshot of selecting the user-assigned managed identity type you're going to use in the portal.

  10. Pick the user-managed identity previously created and click the Select button.

  11. Click Review + assign to finish assigning the role.

Assign managed identity to your app

Now that the identity has the required RBAC to access durable task scheduler, you need to assign it to your function app.

  1. Get resource ID of manage identity.

    resource_id=$(az resource show --resource-group RESOURCE_GROUP --name MANAGED_IDENTITY_NAME --resource-type Microsoft.ManagedIdentity/userAssignedIdentities --query id --output tsv)

  2. Assign the identity to app.

    az functionapp identity assign --resource-group RESOURCE_GROUP_NAME --name FUNCTION_APP_NAME --identities "$resource_id"

  1. From your app in the portal, select Settings > Identity.

  2. Click the User assigned tab.

  3. Click + Add, then pick the identity created in the last section. Click the Add button.

    Screenshot of adding the user-assigned managed identity to your app in the portal.

Add environment variables to app

Add these two environment variables to app setting:

  • TASKHUB_NAME: name of task hub
  • DURABLE_TASK_SCHEDULER_CONNECTION_STRING: the format of the string is "Endpoint={scheduler point};Authentication=ManagedIdentity;ClientID={client id}", where Endpoint is the scheduler endpoint and client id is the identity's client ID.

  1. Get the required information for the durable task scheduler connection string.

    To get the scheduler endpoint.

    az durabletask scheduler show --resource-group RESOURCE_GROUP_NAME --name DTS_NAME --query 'properties.endpoint' --output tsv

    To get the client ID of managed identity.

    az identity show --name MANAGED_IDENTITY_NAME --resource-group RESOURCE_GROUP_NAME --query 'clientId' --output tsv

  2. Use the following command to add environment variable for the scheduler connection string to app.

    az functionapp config appsettings set --resource-group RESOURCE_GROUP_NAME --name FUNCTION_APP_NAME --settings KEY_NAME=KEY_VALUE

  3. Repeat previous step to add environment variable for task hub name.

  1. Get the required information for the durable task scheduler connection string.

    To get your scheduler endpoint, navigate to the Overview tab of your scheduler resource and find "Endpoint" in the top Essentials section.

    To get your managed identity client ID, navigate to the Overview tab of your resource and find "Client ID" in the top Essentials section.

  2. Navigate to your app on the portal.

  3. In the left menu, click Settings > Environment variables.

  4. Add environment variable for durable task scheduler connection string.

  5. Add environment variable for task hub name.

  6. Click Apply then Confirm to add the variables.

Note

If you use system-assigned identity, your connection string would not need the client ID of the identity resource: "Endpoint={scheduler endpoint};Authentication=ManagedIdentity".

Accessing durable task scheduler dashboard

Assign the required role to your developer identity (email) to gain access to the durable task scheduler dashboard.

  1. Set the assignee to your developer identity.

    assignee=$(az ad user show --id "someone@microsoft.com" --query "id" --output tsv)

  2. Set the scope. Granting access on the scheduler scope gives access to all task hubs in that scheduler.

    Task Hub

    scope="/subscriptions/SUBSCRIPTION_ID/resourceGroups/RESOURCE_GROUP/providers/Microsoft.DurableTask/schedulers/SCHEDULER_NAME/taskHubs/TASK_HUB_NAME"

    Scheduler

    scope="/subscriptions/SUBSCRIPTION_ID/resourceGroups/RESOURCE_GROUP/providers/Microsoft.DurableTask/schedulers/SCHEDULER_NAME"

  3. Grant access. Run the following command to create the role assignment and grant access.

    az role assignment create \
  --assignee "$assignee" \
  --role "Durable Task Data Contributor" \
  --scope "$scope"

    Expected output

    The following output example shows a developer identity assigned with the Durable Task Data Contributor role on the scheduler level:

    {
  "condition": null,
  "conditionVersion": null,
  "createdBy": "YOUR_DEVELOPER_CREDENTIAL_ID",
  "createdOn": "2024-12-20T01:36:45.022356+00:00",
  "delegatedManagedIdentityResourceId": null,
  "description": null,
  "id": "/subscriptions/YOUR_SUBSCRIPTION_ID/resourceGroups/YOUR_RESOURCE_GROUP/providers/Microsoft.DurableTask/schedulers/YOUR_DTS_NAME/providers/Microsoft.Authorization/roleAssignments/ROLE_ASSIGNMENT_ID",
  "name": "ROLE_ASSIGNMENT_ID",
  "principalId": "YOUR_DEVELOPER_CREDENTIAL_ID",
  "principalName": "YOUR_EMAIL",
  "principalType": "User",
  "resourceGroup": "YOUR_RESOURCE_GROUP",
  "roleDefinitionId": "/subscriptions/YOUR_SUBSCRIPTION/providers/Microsoft.Authorization/roleDefinitions/ROLE_DEFINITION_ID",
  "roleDefinitionName": "Durable Task Data Contributor",
  "scope": "/subscriptions/YOUR_SUBSCRIPTION/resourceGroups/YOUR_RESOURCE_GROUP/providers/Microsoft.DurableTask/schedulers/YOUR_DTS_NAME",
  "type": "Microsoft.Authorization/roleAssignments",
  "updatedBy": "YOUR_DEVELOPER_CREDENTIAL_ID",
  "updatedOn": "2024-12-20T01:36:45.022356+00:00"
}

  4. After granting access, go to https://dashboard.durabletask.io/ and fill out the required information about your scheduler and task hub to see the dashboard.

Note

The following instruction shows a role assignment scoped to a specific task hub. If you need access to all task hubs in a scheduler, perform the assignment on the scheduler level.

  1. Navigate to the durable task scheduler resource on the portal.

  2. Click on a task hub name.

  3. In the left menu, select Access control (IAM).

  4. Click Add to add a role assignment.

    Screenshot of the adding the role assignment on the Access Control pane in the portal.

  5. Search for and select Durable Task Data Contributor. Click Next.

    Screenshot of selecting the Durable Task Data Contributor role assignment in the portal.

  6. On the Members tab, for Assign access to, select User, group, or service principal.

  7. For Members, click + Select members.

  8. In the Select members pane, search for your name or email:

    Screenshot of selecting the user-assigned managed identity type in the portal.

  9. Pick your email and click the Select button.

  10. Click Review + assign to finish assigning the role.

  11. Once the role is assigned, click Overview on the left menu of the task hub resource and navigate to the dashboard URL located at the top Essentials section.

Auto scaling in Functions Premium plan

For durable task scheduler apps on the Functions Premium plan, enable the Runtime Scale Monitoring setting to get auto scaling of the app.

  1. In the portal overview of your function app, navigate to Settings > Configuration.

  2. Under the Function runtime settings tab, turn on Runtime Scale Monitoring.

    Screenshot of searching for durable task scheduler in the portal.

Run the following command:

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

Next steps

Try out the durable functions quickstart sample.