Skip to content

Durable Functions "RC" Release

Pre-release
Pre-release
Compare
Choose a tag to compare
@cgillum cgillum released this 16 Apr 17:31
v1.3.0-rc
38bdffb
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Verified
Learn about vigilant mode.

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.

Assets 2
Loading