@cgillum cgillum released this Nov 30, 2018 · 19 commits to master since this release

Assets 2

Overview

The v1.7.0 release is a minor update for Durable Functions. While it is "minor" according to the semver definition, it is a significant release in terms of the actual payload. There are many new features, improvements, important bug fixes, and is fully compatible with both Functions 1.0 and Functions 2.0. It also includes support for command-line management of orchestrations via the Azure Functions Core Tools.

Thanks to everyone who contributed, either via code, asking good questions, or by filing issues! Special thanks goes to @gled4er, @TsuyoshiUshio, @cmkerner20 (one of our Summer interns), @k-miyake (first-time contributor), @mlankamp (first-time contributor) and @brandonh-msft for their community contributions, including code and documentation!

New Features / Enhancements

New features are primarily oriented around orchestration instance and data management.

  • Orchestration history purging (#498): A new API has been added which allows purging the history of completed, failed, or terminated orchestration instances. This is useful for saving space, or for compliance with data retention policies (docs). Contributed by @gled4er.
  • Orchestration status query paging (#473): The instance query HTTP API has been enhanced to support paging. This is useful when a task hub contains hundreds or thousands of orchestrations and you want to list them all (docs). Contributed by @k-miyake and @TsuyoshiUshio.
  • HTTP API for starting new orchestration (#61): Previously, starting orchestration instances required writing a trigger function. It is now possible to start a new orchestration instance via a built-in HTTP API (docs coming soon).
  • NewGuid() API for generating orchestrator-safe GUIDs (#514): Orchestrator functions are not allowed to create random GUID values since random data is forbidden. With this new DurableOrchestrationContext.NewGuid() API, it's now possible to create randomly generated GUID/UUID values in a way that is safe for replays (docs). Contributed by @gled4er.
  • Ability to hide inputs from instance query results (#490): By default, orchestration inputs are shown when querying orchestration instances using the HTTP API. A new showInput parameter has been added which allows the caller to remove the inputs from the response (docs).
  • Improved mocking capabilities for activity functions (#494): By popular demand, we've added a new DurableActivityContextBase class that can be used for mocking activity functions (docs). Contributed by @gled4er.
  • Adding support for configuring task hub name from application settings (#503): This is important when automating the deployment of multiple versions of an application. Contributed by @gled4er.
  • New overloads for RaiseEventAsync and WaitForExternalEvent APIs (#517): Non-generic overloads for these methods now exist for when events do not utilize data payloads. Contributed by @brandonh-msft.

Bug Fixes

There are some very significant bug fixes in this release, making it a highly-recommended upgrade.

  • Excessive storage cost running durable functions (#508, #462). Thanks to @shibayan for finding this bug!
  • High latency between scheduling and starting orchestrator (#449)
  • Internal message loss due to partition movement, resulting in hung orchestration (#481, #460, #412)
  • Large exception payloads will hang orchestration instances (#502, #518)
  • NullReferenceException in query string parsing code (#470)
  • Incompatible Microsoft.Extensions.* dependencies for Functions 1.0 projects (#446). Contributed by @mlankamp.
  • "Invalid table name" error if task hub name contains special characters (#505). Contributed by @gled4er.
  • Failed JavaScript orchestrations incorrectly report "Non-Deterministic workflow detected" (#516)

Misc.

  • Durable Functions documentation has been reorganized under a new, dedicated sub-topic (see below)!
  • Source-link support, including embedded PDBs for easier debugging into extension code (#528). Contributed by @gled4er.
  • Status query results now show blob storage URLs for large messages
  • DurableOrchestrationStatus objects are now serializeable (#485). Contributed by @gled4er.

Introducing Durable Functions commands in Azure Functions Core Tools

Worth calling out separately, this release also includes support for a new Durable Functions-specific commands in the next release (>= 2.3.131) of the Azure Functions Core Tools for Azure Functions 2.0. These commands are intended to enable users to manage their orchestrations without the need for calling REST APIs.

The GitHub Pull Request for these updates can be found here: Azure/azure-functions-core-tools#838).

Supported commands include:

  • func durable start-new ... to start a new instance of an orchestrator function
  • func durable get-runtime-status ... to query the status of a running orchestration
  • func durable get-instances ... to query for orchestrations based on their status, creation time, and/or completion time
  • func durable terminate ... to terminate orchestration instances
  • func durable raise-event ... to send event notifications to running orchestrations
  • func durable rewind ... to resurrect failed orchestration instances (rewind functionality is currently in preview)
  • func durable purge-history ... to purge history data from Azure Storage based on a particular time range
  • func durable delete-task-hub ... to permanently delete all Azure Storage data associated with your durable function app (queues, tables, and blobs).

These commands work by making calls directly to Azure Storage, so they do not require the durable function app to be actually running. They also work with both real Azure Storage accounts and the Azure Storage Emulator on Windows devices. More details can be found in the Instance Management documentation topic. Originally contributed by @cmkerner20.

New Documentation Layout

Previously the Durable Functions documentation was mixed in with the regular Azure Functions documentation in a way that made it fairly difficult to navigate. As part of this release, we have also revamped the organization of the docs into their own sub-section. The new home for the Durable docs can be found here: https://docs.microsoft.com/azure/azure-functions/durable. It has the following sections:

  • Overview: Go here to learn about Azure Functions, Durable Functions, and to learn how they compare to other similar products.
  • Quickstarts: Go here to get started coding with Durable Functions. Language specific guides currently exist for C# and JavaScript.
  • Tutorials: Learn how to accomplish basic tasks using Durable Functions.
  • Samples: Find sample end-to-end applications that use Durable Functions.
  • Concepts: Documentation for all of the foundational features of Durable Functions.
  • How-to-guides: Guides for application patterns, monitoring, troubleshooting, performance, etc.
  • Reference: HTTP API reference (eventually we'll move the language-specific API references here as well).

Be sure to check out the new documentation layout. If there's anything you think is missing or needs fixing up, feel free to leave us feedback or open a docs PR using the links on the page!

Note that some of the old links might return 404 currently. We're working on fixing those so that they redirect to the new locations.

Installation Instructions

The latest nuget package can be downloaded here: Microsoft.Azure.WebJobs.Extensions.DurableTask. The package is digitally signed by Microsoft to ensure its integrity and authenticity.