migrate-backend-to-dts

Migrate Durable Functions to Durable Task Scheduler

Step-by-step guide for migrating Azure Durable Functions apps from existing backend storage providers to the Durable Task Scheduler (DTS).

Before You Start

⚠️ Critical Prerequisites

1. Drain in-flight orchestrations. DTS does not import state from other backends. All running orchestrations must complete or be terminated before switching.
2. .NET apps must use isolated worker model. DTS does not support the in-process hosting model. If your app uses in-process (Microsoft.Azure.WebJobs.Extensions.DurableTask), migrate to isolated worker first.
3. Identity-based auth only. DTS uses Microsoft Entra ID / managed identity — no shared keys or connection string secrets. Plan for RBAC setup.

Step 1: Identify Your Current Backend

Inspect your host.json to determine which backend you're migrating from:

Current storageProvider.type	Backend	Key Indicator
(missing or empty)	Azure Storage (default)	No explicit type; uses AzureWebJobsStorage connection
"azure"	Azure Storage (explicit)	Same as default
"netherite"	Netherite	Requires Event Hubs connection string
"mssql"	Microsoft SQL	Requires SQL Server connection string

Also check your packages for confirmation:

.NET (.csproj):

Package	Backend
Microsoft.Azure.WebJobs.Extensions.DurableTask (no suffix)	Azure Storage (in-process — must also migrate to isolated)
Microsoft.Azure.Functions.Worker.Extensions.DurableTask (no suffix)	Azure Storage (isolated)
Microsoft.Azure.DurableTask.Netherite.AzureFunctions	Netherite
Microsoft.DurableTask.SqlServer.AzureFunctions	MSSQL

Python (requirements.txt): azure-functions-durable — backend is configured in host.json only.

JavaScript (package.json): durable-functions — backend is configured in host.json only.

Java (build.gradle/pom.xml): azure-functions-java-library — backend is configured in host.json only.

Step 2: Update host.json

Remove your old storageProvider block and replace it with the DTS configuration.

Migrating from Azure Storage (default)

// BEFORE — Azure Storage (default, no storageProvider block)
{
  "version": "2.0",
  "extensions": {
    "durableTask": {
      "hubName": "MyTaskHub"
    }
  }
}

// AFTER — Durable Task Scheduler
{
  "version": "2.0",
  "extensions": {
    "durableTask": {
      "hubName": "%TASKHUB_NAME%",
      "storageProvider": {
        "type": "azureManaged",
        "connectionStringName": "DURABLE_TASK_SCHEDULER_CONNECTION_STRING"
      }
    }
  }
}

Migrating from Azure Storage (explicit)

// BEFORE — Azure Storage (explicit type)
{
  "version": "2.0",
  "extensions": {
    "durableTask": {
      "hubName": "MyTaskHub",
      "storageProvider": {
        "type": "azure",
        "connectionStringName": "AzureWebJobsStorage"
      }
    }
  }
}

// AFTER — Durable Task Scheduler
{
  "version": "2.0",
  "extensions": {
    "durableTask": {
      "hubName": "%TASKHUB_NAME%",
      "storageProvider": {
        "type": "azureManaged",
        "connectionStringName": "DURABLE_TASK_SCHEDULER_CONNECTION_STRING"
      }
    }
  }
}

Migrating from Netherite

// BEFORE — Netherite
{
  "version": "2.0",
  "extensions": {
    "durableTask": {
      "hubName": "MyTaskHub",
      "storageProvider": {
        "type": "netherite",
        "storageConnectionName": "AzureWebJobsStorage",
        "eventHubsConnectionName": "EventHubsConnection",
        "partitionCount": 12
      }
    }
  }
}

// AFTER — Durable Task Scheduler
{
  "version": "2.0",
  "extensions": {
    "durableTask": {
      "hubName": "%TASKHUB_NAME%",
      "storageProvider": {
        "type": "azureManaged",
        "connectionStringName": "DURABLE_TASK_SCHEDULER_CONNECTION_STRING"
      }
    }
  }
}

Netherite cleanup: After migration, remove the EventHubsConnection setting and consider deprovisioning the Event Hubs namespace if no longer needed. DTS handles partitioning internally — partitionCount is not needed.

Migrating from MSSQL

// BEFORE — Microsoft SQL Server
{
  "version": "2.0",
  "extensions": {
    "durableTask": {
      "hubName": "MyTaskHub",
      "storageProvider": {
        "type": "mssql",
        "connectionStringName": "SQLDB_Connection",
        "taskEventLockTimeout": "00:02:00",
        "createDatabaseIfNotExists": true,
        "schemaName": "dt"
      }
    }
  }
}

// AFTER — Durable Task Scheduler
{
  "version": "2.0",
  "extensions": {
    "durableTask": {
      "hubName": "%TASKHUB_NAME%",
      "storageProvider": {
        "type": "azureManaged",
        "connectionStringName": "DURABLE_TASK_SCHEDULER_CONNECTION_STRING"
      }
    }
  }
}

MSSQL cleanup: After migration, remove SQLDB_Connection from app settings. The dt.* schema tables in your SQL database can be dropped once you've confirmed the migration is successful.

Non-.NET Languages (Python, JavaScript, Java)

For Python, JavaScript, and Java apps, migration is configuration-only — no code changes or package changes are required. You only need to update host.json.

There is one key difference from .NET: the extension bundle must be updated to the Preview bundle.

Python — Migrating from Azure Storage (default)

// BEFORE — host.json (Azure Storage default)
{
  "version": "2.0",
  "extensions": {
    "durableTask": {
      "hubName": "MyTaskHub"
    }
  },
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[4.0.0, 5.0.0)"
  }
}

// AFTER — host.json (Durable Task Scheduler)
{
  "version": "2.0",
  "logging": {
    "logLevel": {
      "DurableTask.Core": "Warning"
    }
  },
  "extensions": {
    "durableTask": {
      "hubName": "default",
      "storageProvider": {
        "type": "azureManaged",
        "connectionStringName": "DURABLE_TASK_SCHEDULER_CONNECTION_STRING"
      }
    }
  },
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle.Preview",
    "version": "[4.29.0, 5.0.0)"
  }
}

requirements.txt — no changes needed:

azure-functions
azure-functions-durable

local.settings.json:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "python",
    "DURABLE_TASK_SCHEDULER_CONNECTION_STRING": "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None"
  }
}

JavaScript / TypeScript — Migrating from Azure Storage (default)

// BEFORE — host.json (Azure Storage default)
{
  "version": "2.0",
  "extensions": {
    "durableTask": {
      "hubName": "MyTaskHub"
    }
  },
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[4.0.0, 5.0.0)"
  }
}

// AFTER — host.json (Durable Task Scheduler)
{
  "version": "2.0",
  "logging": {
    "logLevel": {
      "DurableTask.Core": "Warning"
    }
  },
  "extensions": {
    "durableTask": {
      "hubName": "default",
      "storageProvider": {
        "type": "azureManaged",
        "connectionStringName": "DURABLE_TASK_SCHEDULER_CONNECTION_STRING"
      }
    }
  },
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle.Preview",
    "version": "[4.29.0, 5.0.0)"
  }
}

package.json — no changes needed:

{
  "dependencies": {
    "@azure/functions": "^4.0.0",
    "durable-functions": "^3.0.0"
  }
}

local.settings.json:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "DURABLE_TASK_SCHEDULER_CONNECTION_STRING": "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None"
  }
}

Java — Migrating from Azure Storage (default)

// BEFORE — host.json (Azure Storage default)
{
  "version": "2.0",
  "extensions": {
    "durableTask": {
      "hubName": "MyTaskHub"
    }
  },
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[4.0.0, 5.0.0)"
  }
}

// AFTER — host.json (Durable Task Scheduler)
{
  "version": "2.0",
  "logging": {
    "logLevel": {
      "DurableTask.Core": "Warning"
    }
  },
  "extensions": {
    "durableTask": {
      "hubName": "default",
      "storageProvider": {
        "type": "azureManaged",
        "connectionStringName": "DURABLE_TASK_SCHEDULER_CONNECTION_STRING"
      }
    }
  },
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle.Preview",
    "version": "[4.29.0, 5.0.0)"
  }
}

pom.xml — no changes needed. Your existing dependencies stay the same:

<dependency>
    <groupId>com.microsoft.azure.functions</groupId>
    <artifactId>azure-functions-java-library</artifactId>
    <version>3.2.3</version>
</dependency>
<dependency>
    <groupId>com.microsoft</groupId>
    <artifactId>durabletask-azure-functions</artifactId>
    <version>1.7.0</version>
</dependency>

local.settings.json:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "java",
    "DURABLE_TASK_SCHEDULER_CONNECTION_STRING": "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None"
  }
}

Non-.NET — Migrating from Netherite or MSSQL

The target configuration is the same regardless of which existing backend you're migrating from. Replace the old storageProvider block and update the extension bundle as shown above. The only additional step is removing the old backend's connection strings from your app settings:

• From Netherite: Remove EventHubsConnection (or your Event Hubs connection name)
• From MSSQL: Remove SQLDB_Connection (or your SQL connection name)

Step 3: Update Packages (.NET Only)

Non-.NET languages

---

Content truncated.