Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Durable Functions is an extension of Azure Functions and Azure WebJobs that lets you write stateful functions in a serverless environment. The extension manages state, checkpoints, and restarts for you. If you aren't already familiar with Durable Functions, see the overview documentation.
Version summary
| Version | Status | Key changes |
|---|---|---|
| v3.x | Current (recommended) | Updated Azure Storage SDK, improved cost efficiency, no code changes to upgrade from v2.x |
| v2.x | Maintained (security and bug fixes only) | Durable entities, Durable HTTP |
| v1.x | End of support September 2026 | Legacy |
What's new in v3.x
The Microsoft.Azure.WebJobs.Extensions.DurableTask v3 package (referred to as WebJobs.Extensions.DurableTask in subsequent sections) is the current recommended version. Upgrading from v2.x requires no code changes — you only need to update your package dependencies. This update is only considered a breaking change for customers running Durable C# apps that use the in-process model.
Note
The Durable Functions .NET out-of-process package, Microsoft.Azure.Functions.Worker.Extensions.DurableTask, references Microsoft.Azure.WebJobs.Extensions.DurableTask as its underlying assembly. Thus, this update also applies to Microsoft.Azure.Functions.Worker.Extensions.DurableTask, starting from version 1.2.x.
Updated Azure Storage SDK
By default, Durable Functions use Azure Storage as a storage backend to durably save application state. In WebJobs.Extensions.DurableTask v3, the Azure Storage backend was upgraded to use the latest versions of the Azure Storage SDKs: Azure.Data.Tables, Azure.Storage.Blobs, and Azure.Storage.Queues. These SDKs offer enhanced support for Managed Identity, better performance, more efficient data handling, and improved security compared to the legacy Microsoft.Azure.Storage.* packages used in v2.x.
Improved cost efficiency (for the Azure Storage provider)
In the Azure Storage backend, the Partition Manager is responsible for distributing partitions/control queues among workers. The WebJobs.Extensions.DurableTask v3 package uses Partition Manager V3 by default, which is a new design that leverages Azure Tables to manage partition assignments instead of Azure Blob leases. This design can significantly reduce storage costs while making debugging easier. When Partition Manager V3 is used, a new table, named Partitions, is created in your storage account, allowing you to easily check the partition information.
Removed support for the Azure Functions v1 runtime
WebJobs.Extensions.DurableTask v3 no longer supports version 1.x of the Azure Functions runtime, support for which is scheduled to end in September 2026. If you must use Functions runtime v1, please use a Durable Functions extension version lower than v2.11.0. Keep in mind that when the scheduled end of support comes, Durable Functions will drop its support for runtime v1 as well.
.NET runtime target update
WebJobs.Extensions.DurableTask v3 updates the target runtime from .NET Core 3.1 to .NET 6, offering improved performance and enhanced compatibility with modern .NET features and libraries. This update aligns with future releases of the Azure Functions extension bundles.
Migrate from v2.x to v3.x
Migration from v2.x to v3.x requires no code changes — simply update your dependencies to start using the new features.
- In-process model: Update to Microsoft.Azure.WebJobs.Extensions.DurableTask version 3.0.0 or later.
- Isolated worker model: Update to Microsoft.Azure.Functions.Worker.Extensions.DurableTask version 1.2.0 or later.
Update to Azure Functions extension bundle version 4.22.0 or later.
Downgrade compatibility (v3.x to v2.x)
WebJobs.Extensions.DurableTask v3 uses a different text encoding for the Azure Storage SDK (Base64) compared to v2 (UTF-8). If you need to revert from v3.x to v2.x, use the following minimum versions to ensure backward compatibility:
Revert to an extension bundle version earlier than 4.22.0.
Support and maintenance of v2.x
WebJobs.Extensions.DurableTask v2.x continues to receive security updates and bug fixes, ensuring that your existing applications remain secure and stable. However, all new features and enhancements are added exclusively to v3.x. Because of this, you should upgrade to WebJobs.Extensions.DurableTask v3 as soon as you can to take advantage of the latest capabilities and ongoing improvements.
Features introduced in v2.x
The following features are available in Durable Functions 2.x and later, across all supported languages.
Note
The .NET in-process API details in this section don't apply to the isolated worker model. For isolated worker guidance, see the Durable Functions isolated process overview.
Durable entities
Durable Functions supports entity functions for reading and updating small pieces of state, known as durable entities. Like orchestrator functions, entity functions are functions with a special trigger type, entity trigger. Unlike orchestrator functions, entity functions don't have any specific code constraints. Entity functions also manage state explicitly rather than implicitly representing state via control flow.
To learn more, see the durable entities article.
Durable HTTP
Durable Functions includes a Durable HTTP feature that allows you to:
- Call HTTP APIs directly from orchestration functions (with some documented limitations).
- Implement automatic client-side HTTP 202 status polling.
- Use built-in support for Azure Managed Identities.
To learn more, see the HTTP features article.
Migrate from 1.x to 2.x
Important
Version 1.x of the Azure Functions runtime reaches end of support in September 2026. If you're still on v1.x, plan your migration soon.
This section describes how to migrate your existing version 1.x Durable Functions to version 2.x to take advantage of the new features.
Upgrade the Durable Functions extension
Install the latest 2.x version of the Durable Functions bindings extension in your project.
Durable Functions 2.x is available starting in version 2.x of the Azure Functions extension bundle.
Python support in Durable Functions requires Durable Functions 2.x or greater.
To update the extension bundle version in your project, open host.json and update the extensionBundle section to use version 4.x ([4.*, 5.0.0)).
{
"version": "2.0",
"extensionBundle": {
"id": "Microsoft.Azure.Functions.ExtensionBundle",
"version": "[4.*, 5.0.0)"
}
}
Durable Functions 2.x is available starting in version 2.x of the Azure Functions extension bundle.
To update the extension bundle version in your project, open host.json and update the extensionBundle section to use version 4.x ([4.*, 5.0.0)).
{
"version": "2.0",
"extensionBundle": {
"id": "Microsoft.Azure.Functions.ExtensionBundle",
"version": "[4.*, 5.0.0)"
}
}
Note
If Visual Studio Code is not displaying the correct templates after you change the extension bundle version, reload the window by running the Developer: Reload Window command (Ctrl+R on Windows and Linux, Command+R on macOS).
Durable Functions 2.x is available starting in version 2.x of the Azure Functions extension bundle.
To update the extension bundle version in your project, open host.json and update the extensionBundle section to use version 4.x ([4.*, 5.0.0)).
{
"version": "2.0",
"extensionBundle": {
"id": "Microsoft.Azure.Functions.ExtensionBundle",
"version": "[4.*, 5.0.0)"
}
}
Update your .NET project to use the latest version of the Durable Functions bindings extension.
See Register Azure Functions binding extensions for more information.
Update your Durable Functions code
Durable Functions 2.x introduces several breaking changes. Durable Functions 1.x applications aren't compatible with Durable Functions 2.x without code changes. This section lists some of the changes you must make when upgrading your version 1.x functions to 2.x.
Host.json schema
Durable Functions 2.x uses a new host.json schema. The main changes from 1.x include:
"storageProvider"(and the"azureStorage"subsection) for storage-specific configuration."tracing"for tracing and logging configuration."notifications"(and the"eventGrid"subsection) for Event Grid notification configuration.
See the Durable Functions host.json reference documentation for details.
Default task hub name changes
In version 1.x, if a task hub name wasn't specified in host.json, it was defaulted to "DurableFunctionsHub". In version 2.x, the default task hub name is now derived from the name of the function app. Because of this, if you haven't specified a task hub name when upgrading to 2.x, your code will be operating with new task hub, and all in-flight orchestrations will no longer have an application processing them. To work around this, you can either explicitly set your task hub name to the v1.x default of "DurableFunctionsHub", or you can follow our zero-downtime deployment guidance for details on how to handle breaking changes for in-flight orchestrations.
Public interface changes in Durable Functions
In version 1.x, the various context objects supported by Durable Functions have abstract base classes intended for use in unit testing. As part of Durable Functions 2.x, these abstract base classes are replaced with interfaces.
The following table represents the main changes:
| 1.x | 2.x |
|---|---|
DurableOrchestrationClientBase |
IDurableOrchestrationClient or IDurableClient |
DurableOrchestrationContext or DurableOrchestrationContextBase |
IDurableOrchestrationContext |
DurableActivityContext or DurableActivityContextBase |
IDurableActivityContext |
OrchestrationClientAttribute |
DurableClientAttribute |
In the case where an abstract base class contained virtual methods, these virtual methods have been replaced by extension methods defined in DurableContextExtensions.
function.json changes
In Durable Functions 1.x, the orchestration client binding uses a type of orchestrationClient. Version 2.x uses durableClient instead.
Raise event changes
In Durable Functions 1.x, calling the raise event API and specifying an instance that didn't exist resulted in a silent failure. Starting in 2.x, raising an event to a non-existent orchestration results in an exception.