Durable Functions v1.5.0 Release

Overview

The v1.5.0 release is a minor update for Durable Functions. It contains new features, various improvements, and bug fixes. The biggest focus was on improving on some key pain points since the GA release, as well as enabling support for the latest Azure Functions v2 runtime.

Thanks to everyone who contributed, either via code, asking good questions, or by filing issues! Special thanks goes to @gled4er, @TsuyoshiUshio, and @yuka1984 for their community contributions (including code and documentation)! The specific contributions are called out below.

New Features

• Support for complex object parameters in JavaScript orchestrations: Previously only primitive types (strings, numbers, etc.) were supported.
• New CreateHttpManagementPayload API to get status/terminate/raise-event URLs (#155): Previously only HTTP-triggered functions could discover management endpoint URLs. With this API, any function trigger can now discover this information via DurableOrchestrationClient. See the Instance management documentation for more details. Thanks @gled4er for this community contribution!
• New APIs to enumerate all orchestrations (#323): Previously we required users to track orchestration instance IDs themselves externally. We now expose an API which will enumerate all orchestration instances in the task hub via a .NET API as well as a REST API. Thanks @TsuyoshiUshio for this community contribution!

Improvements

• Adds support for the latest Azure Functions v2 runtime (#342).
• Application Insights tracking logs now omit replay executions by default. Note that this is a behavior change. See the Diagnostics topic for more details. Thanks @gled4er for this community contribution!
• Azure Event Grid integration improvements, including publishing retry configuration and app settings-based endpoint configuration. Thanks @yuka1984 for these community contributions!
• Various telemetry improvements. This will make it a lot easier for us to help you diagnose orchestration runtime issues in Azure.
• The official nuget package is now digitally signed.

Also note that due to an internal policy change on nuget.org, the dependent DurableTask.AzureStorage and DurableTask.Core nuget packages have been temporarily renamed to DurableTask.AzureStorage.Private and DurableTask.Core.Private.

Installation Instructions

The latest nuget package can be downloaded here: Microsoft.Azure.WebJobs.Extensions.DurableTask

Please see our installation documentation for instructions for all supported platforms (be sure to always select the latest version of the extension).

Note that the Azure Functions portal, the Azure Functions CLI, and the Visual Studio tools for Azure Functions and Azure WebJobs may run into issues when using the latest version of the Durable Functions extension at the time of writing. Updates for these tools are in the works.

Durable Functions v1.4.0 (GA) Release

Overview

This is the very first GA release for Durable Functions. It contains new features, various fixes, and a few small compile-time breaking changes (last-minute public surface area cleanup). The biggest focus was on improving performance and scale.

This is an officially supported release. Subsequent 1.x releases will be non-breaking upgrades.

Thanks to everyone who contributed, either via code, asking good questions, or by filing issues! Special thanks goes to @gled4er, @TsuyoshiUshio, @mikhailshilkov, @CarlosSardo, and @MS-Santi for their community contributions (including code, samples, and documentation)!

New Features

• JavaScript orchestrator functions (preview): You can now write orchestrator functions in JavaScript. More details in our new durable-js repo: https://github.com/Azure/azure-functions-durable-js. JavaScript samples can be found here.
• Extended sessions: Allows orchestrator functions to stay in memory longer, removing the need to frequently replay them. This is a feature which can boost performance in various scenarios. More details in our Orchestrator function replay documentation documentation.
• Concurrency control: Configure the maximum number of orchestrator or activity functions that can run concurrently on a single host instance. More details in the Concurrency throttles documentation.
• Configurable partition counts: Configure the number of partitions in your task hub. Previously this was fixed at 4. Now this can be between 1 and 16. More details in the Orchestrator scale-out documentation.

Fixed

• Custom status values were not displayed in the HTTP status query API (#271)
• Waiting for multiple event types inside a loop only responded to first event type received (#275)
• Task hub listeners could fail to start repeatedly and endlessly (#295)
• Scale controller didn't auto-scale out based on queue latency (#200)
• Scaling in consumption plan didn't work when using different storage account (#179)
• Added protection against "split brain" in Azure Storage provider (#38)

Misc

• Change custom Event Grid eventType property from an int to a string (#294) [Breaking change!]
• Made GetInputAsJson and GetRawInput internal [Breaking change!]
• Replaced nullable arguments and optional parameters with proper overloads [Breaking change!]
• Removed "version" information from traces (#282)
• Updated all samples (C# precompiled, C# scripting, F#, and WebJobs SDK)
• Updated .NET API documentation

Installation

Please see our installation documentation for instructions for all supported platforms.

Durable Functions "RC" Release

Overview

This is the RC (Release Candidate) release of the Durable Functions extension to Azure Functions, and contains a significant number of updates. As with most pre-releases, it contains several important fixes, new features, and breaking changes. Thanks to everyone who contributed, either via code, asking good questions, or by filing issues!

Special thanks goes to @gled4er, @TsuyoshiUshio, @yuka1984, @kingkino, @rukasakurai, and @hamamotsu for their community contributions!

New Features

• Custom orchestration status values (#193): A new SetCustomStatus API has been introduced which allows an orchestrator function to expose "progress" state to external callers. The state can be a simple string or a complex JSON object.
• Automatic Azure Event Grid publishing (#220): This feature allows publishing orchestration lifecycle events (created, completed, failed, etc.) to a custom Azure Event Grid topic.
• Large message support (#26): Function parameters, function return values, and external events can now be of any size (previously there was a 60 KB size limitation).
• Inner exceptions (#250): Orchestrator functions can now see the inner exception details when an exception is thrown from an activity or sub-orchestrator function.

Fixed

• Fix for HTTP 500 errors from HTTP APIs on cold start (#205)
• Improved error message for invalid async orchestrator function logic (#208)
• Support for waiting on multiple concurrent external events in parallel with the same name (#207)
• Precompiled samples won't compile for netstandard2.0 (#233)
• Orchestration loops forever when terminated (#146)
• Unintuitive error message when UseDevelopmentStorage=true and Storage Emulator isn't running (#238)
• Orchestration Replay calls activities twice (#231)
• ContinueAsNew doesn't continue (#182)
• Function App doesn't scale when custom HubName is specified (#111)
• StartNewAsync fails with timeout exceptions (#177)
• Tracking events in Application Insights cannot be ordered reliably (#71)
• Status query HTTP API should return a failure status code when the orchestrator fails (#154) [Breaking Change]

Misc

• Replace "Counter" sample with "Monitor" sample (#118)
• Expose Task Hub name in DurableOrchestrationClient (#224)
• Create separate "Instances" table for storing orchestration status (#183) [Breaking Change]
• Expose parent orchestration instance id in a sub-orchestrator (DurableOrchestrationContext.ParentInstanceId) (#257)

Installation

Anyone can start using the v1.3.1-rc release by referencing the latest Microsoft.Azure.WebJobs.Extensions.DurableTask NuGet package in their projects.

Visual Studio 2017 (Functions 1.0 or Functions 2.0 preview)

Update your .csproj file with the following package reference:

<PackageReference Include="Microsoft.Azure.WebJobs.Extensions.DurableTask" Version="1.3.1-rc" />

Azure Functions CLI (Functions 2.0 preview)

Use the following command to install the updated extension into your project:

func extensions install -p Microsoft.Azure.WebJobs.Extensions.DurableTask -v 1.3.1-rc

Azure Portal

The Azure Portal Durable Functions templates for projects targeting Functions 2.0 (preview) will automatically install this version of the extension at a later date.

Breaking Changes

There are runtime breaking changes in this release, so it is highly recommended to use this new package version with new function apps.

If you have an existing function app that you would like to migrate to this version, please see the versioning and migration strategies documentations for best practices.

Quick Documentation

Documentation has not been published yet for these new features, but expect the docs to trickle in over the next few weeks. In the meantime, here are some quick notes for how to get started with some of the new features.

Custom orchestration status values

This is a feature which allows users to set a custom status value from their orchestrator function, and have it exposed via the HTTP GetStatus API or the DurableOrchestrationClient.GetStatusAsync API.

Here is a simple example of how it works, starting with the orchestrator function code:

public static async Task SetStatusTest([OrchestrationTrigger] DurableOrchestrationContext ctx)
{
    // ...do work...

    // update the status of the orchestration with some arbitrary data
    var customStatus = new { nextActions = new [] {"A", "B", "C"}, foo = 2, };
    ctx.SetCustomStatus(customStatus);

    // ...do more work...
}

While the orchestration is running, external clients can fetch this custom status. For example:

GET /admin/extensions/DurableTaskExtension/instances/instance123

...yields the following JSON status payload...

{
  "runtimeStatus": "Running",
  "input": null,
  "customStatus": { "nextActions": ["A", "B", "C"], "foo": 2 },
  "output": null,
  "createdTime": "2017-10-06T18:30:24Z",
  "lastUpdatedTime": "2017-10-06T19:40:30Z"
}

The custom status payload is limited to 16 KB of UTF-16 JSON text. If larger custom status payloads are required, the recommendation is to store them outside the orchestration state in a store like Azure Storage or Cosmos DB.

Azure Event Grid Publishing

Azure Event Grid orchestration lifecycle publishing can be enabled by specifying the eventGridTopEndpoint and eventGridKeyName fields in the durableTask section of host.json:

{
  "durableTask": {
    "eventGridTopicEndpoint": "YOUR_EVENT_GRID_TOPIC_ENDPOINT_SAS_URL",
    "eventGridKeySettingName": "YOUR_EVENT_GRID_TOPIC_KEY_APP_SETTING"
  }
}

Note that the eventGridKeySettingName field should be the name of an Application Setting or environment variable which contains the actual secret key value. You should never put your Event Grid key directly in host.json.

The eventType for these events is orchestratorEvent and the subject is durable/orchestrator/{orchestrationRuntimeStatus}, where {orchestrationRuntimeStatus} can be Running, Completed, Failed, or Terminated.

Beta 3.1 Release

This is a minor update to the third beta release which contains a small number of important fixes and improvements over the original beta 3 release.

Updates

• Functions V2 compatibility update (#210): This version of the Durable Functions extension is compatible with the latest v2.0 update of the Azure Functions runtime.
• Adding sequence numbers to App Insights Events (#71): A sequence number field was added to Application Insights telemetry to help work around a timestamp precision issue that made trace events appear out of order.
• Enable opting-out of the StartNewAsync polling (#177): Some users were seeing timeouts when starting orchestrator functions. This release includes a temporary workaround.
• Fixed message size calculation (#189): There is currently a 60 KB message size limit for function parameters and return values, however, we were throwing an exception for only 30 KB.

StartNewAsync Timeout Workaround

For anyone impacted by the StartNewAsync timeout issue, you can add the following JSON configuration to your host.json file to work around the issue.

{
  "durableTask": {
    "disableStartInstancePolling": true
  }
}

The behavior you will observe is that DurableOrchestrationClient.StartNewAsync will return quickly, but the started instance may not be visible for several seconds. An improved fix is scheduled for the next release and the above configuration will no longer have any effect.

Installation

Anyone can start using the v1.2.2-beta3 release by referencing the latest Microsoft.Azure.WebJobs.Extensions.DurableTask NuGet package in their projects.

Visual Studio 2017 (Functions 1.0 or Functions 2.0)

Update your .csproj file with the following package reference:

<PackageReference Include="Microsoft.Azure.WebJobs.Extensions.DurableTask" Version="1.2.2-beta3" />

Azure Functions CLI (Functions 2.0)

Use the following command to install the updated extension into your project:

func extensions install -p Microsoft.Azure.WebJobs.Extensions.DurableTask -v 1.2.2-beta3

Azure Portal

The Azure Portal Durable Functions templates for projects targeting Functions 2.0 will automatically install this version of the extension into the function app starting April 2.

Beta 3 Release

This is the third beta release and contains several important fixes, new features, and breaking changes. Thanks to everyone who contributed, either via code, asking good questions, or by filing issues!

Special thanks goes to @gled4er and @brandonh-msft for their community contributions!

New Features

Many new features were included in this release:

• Declarative binding expressions (#123): It is now possible to use binding expressions in activity functions.
• Query for orchestration history (#16): You can now get the orchestration history from the statusEndpointGetUrl by including the showHistory=true query string parameter.
• Support for synchronous HTTP execution (#102): It is now possible to run an orchestration and get the output via a single blocking HTTP request.
• Unit testing support (#64): New abstract base classes have been added which enable unit testing orchestration code and triggers via mocks. The the precompiled sample project for examples of this.
• Configurable partition counts (#73): It's now possible to configure the number of partitions in your task hub in host.json (the default is 4).

Proper documentation is still being written for these new features, so stay tuned for that.

Fixed

• Attempting to poll the result of CreateCheckStatusResponse can return 404 (#143, #134)
• Calling RaiseEventAsync or TerminateAsync after starting a new instance results in an error (#101)
• Function app doesn't scale when custom HubName is specified (#111)
• Orchestration termination reason is not shown (#130)
• Passing null parameter into activity causes exception (#137)
• WaitForExternalEvent cannot be awaited more than once using the same event name (#141)
• Durable function queues keep growing and process becomes slower (#104)

Misc.

• Added a Monitor sample which periodically checks the weather and sends a notification on certain conditions.
• Removed the Counter sample from sample projects because the actor model is being de-emphasized (too many fundamental issues make it impractical for real use-cases).

Installation

Anyone can start using the v1.2.0-beta3 release by referencing the latest Microsoft.Azure.WebJobs.Extensions.DurableTask NuGet package in their projects.

Visual Studio 2017 (Functions 1.0 or Functions 2.0)

Update your .csproj file with the following package reference:

<PackageReference Include="Microsoft.Azure.WebJobs.Extensions.DurableTask" Version="1.2.0-beta3" />

Azure Functions CLI (Functions 2.0)

Use the following command to install the updated extension into your project:

func extensions install -p Microsoft.Azure.WebJobs.Extensions.DurableTask -v 1.2.0-beta3

Azure Portal

The Azure Portal templates do not currently support installing or updating to v1.2.0-beta3. :( Please consider using the Azure Functions CLI experience instead, and deploying your local changes to Azure.

Breaking Changes

There are runtime breaking changes in this release, so it is highly recommended to use this new package version with new function apps.

If you have an existing function app that you would like to migrate to this version, please see the versioning and migration strategies documentations for best practices.

Beta 2 Release (1.1.0-beta2)

This is the second beta release and contains several important fixes, new features, and breaking changes. Thanks to everyone who contributed, either via code, asking good questions, or by filing issues!

Improvements

• Fixes issues when using Azure Storage input or output bindings (#74, #78)
• Changed HTTP status codes when querying non-running orchestrations (#75)
• Added message size validation for return values (#79)
• Fixed serialization issues related to sub-orchestrations (#86)
• Enabled creating sub-orchestrations with specific instance IDs (#91, #97)
• Fixed an ugly performance/reliability issue with eternal orchestrations (#94)
• Added Retry-After response headers to the create and HTTP status query APIs for improved integration with Logic Apps (#99)
• Runtime status values are now enums rather than strings (#100)

Installation

Anyone can start using the v1.1.0-beta2 release by referencing the latest Microsoft.Azure.WebJobs.Extensions.DurableTask NuGet package in their projects.

Visual Studio 2017 (Functions 1.0)

Update your .csproj file with the following package reference:

<PackageReference Include="Microsoft.Azure.WebJobs.Extensions.DurableTask" Version="1.1.0-beta2" />

Azure Functions CLI (Functions 2.0)

Use the following command to install the updated extension into your project:

func extensions install -p Microsoft.Azure.WebJobs.Extensions.DurableTask -v 1.1.0-beta2

Azure Portal

The Azure Portal templates do not currently support installing or updating to v1.1.0-beta2. :( Please consider using the Azure Functions CLI experience instead, and deploying your local changes to Azure.

Breaking Changes

There are both compile time and runtime breaking changes in this release, so it is highly recommended to use this new package version with new function apps.

If you have an existing function app that you would like to migrate to this version, please see the versioning and migration strategies documentations for best practices.

Activity binding, System Keys, & improved Visual Studio support

This release includes a variety of changes and fixes, including some minor breaking changes. Most importantly, the Visual Studio setup experience has been significantly improved due in part to several changes included in the final release of Visual Studio 2017 (15.3).

The VS sample project has also been updated to highlight these major changes:

• Durable Functions can be added to any Azure Functions project via a simple NuGet package reference.
• Activity functions can now bind to any JSON-serializeable data type, including primitive types.

Security has also been improved by taking advantage of the new System Keys feature of Azure Functions.

More technical details can be found in the following PR:
Updates for 0.2.2-alpha: Activity binding, System Keys, & improved Visual Studio support