Durable Orchestrations - Azure Functions (2023)

Durable Functions is an extension ofAzure functions. You can use oneOrchestrator-Rolleto orchestrate the execution of other persistent functions within a function app. Orchestrator functions have the following properties:

• Orchestrator functions define workflows of functions using procedural code. No declarative schemas or designers are needed.
• Orchestrator functions can call other persistent functions synchronously and asynchronously. The output of called functions can be reliably stored in local variables.
• Orchestrator functions are durable and reliable. Execution progress is checked automatically when the function "waits" or "gives". The local state is never lost when the process is recycled or the virtual machine is restarted.
• Orchestrator roles can take a long time. The total useful life of aorchestration instancethey can be seconds, days, months or endless.

This article gives you an overview of Orchestrator features and how they can help you solve various application development challenges. If you're new to the types of functions available in a Durable Functions application, read theTypes of Persistent Functionsfirst article.

orchestration identity

Everyoneexampleof an orchestration has an instance identifier (also known asinstance identifier). By default, each instance ID is an automatically generated GUID. However, instance IDs can also be any user-generated string values. Each orchestration instance ID must be unique withintask center.

Here are some rules about instance IDs:

• Instance IDs must be between 1 and 256 characters long.
• Instance IDs must not start with@.
• Instance IDs must not contain/,\,#, Ö?Characters.
• Instance IDs cannot contain control characters.

The instance ID of an orchestration is a required parameter for mostInstance Management Operations. They are also important for diagnosis, such asBrowse orchestration trace datain Application Insights for analysis or troubleshooting purposes. For this reason, it is recommended to store the generated instance IDs in an external location (e.g. in a database or in the application logs) where they can be easily referenced later.

reliability

Orchestrator functions maintain their execution state by using reliableEvent-Sourcingdesign pattern. Rather than storing the current state of an orchestration directly, the Durable Task Framework uses an append-only store to record the entire series of actions that the function orchestration performs. An add-only store has many advantages over "dumping" the entire runtime state. Benefits include increased performance, scalability, and responsiveness. You also get ultimate consistency for transactional data and full audit trails and logs. Test reports support reliable compensation measures.

Durable Functions uses event sourcing transparently. Behind the scenes thatWait(Re#) itto produce(JavaScript/Python) in an orchestrator function returns control of the orchestrator thread to the Durable Task Framework dispatcher. In the case of Java, there is no special language keyword. Call instead.Wait()in a task, control of a returns to the dispatcherthrowable. The dispatcher then writes to memory any new actions that the orchestrator function has scheduled (such as calling one or more child functions or scheduling a persistent timer). The transparent commit action updates the orchestration instance execution history by adding any new events to the store, similar to an add-only record. Similarly, the commit action creates messages in memory to schedule actual work. At this point, the orchestrator function can be unloaded from memory. By default, Durable Functions uses Azure Storage for runtime state storage, but othersStorage providers are also supported.

When more work is assigned to an orchestration function (for example, when a response message is received or a persistent timer expires), the orchestrator wakes up and runs the entire function again from the beginning to recreate the local state. When your code tries to call a function (or perform some other asynchronous work) during playback, the Durable Task Framework queries the execution history of the current orchestration. If you find thatactivity functionalready executed and returned a result, reflects the result of this function and the orchestrator code continues to run. Replay continues until the function code ends or until you schedule a new asynchronous job.

history of orchestration

The Durable Task Framework's event-sourcing behavior is closely related to the Orchestrator function code that you write. Suppose you have an activity chain orchestration function, e.g. For example, the following orchestration function:

[FunctionName("HelloCities")]Public Static Asynchronous Task<List<string>> Execute( [Orchestrierungsauslöser] IDurableOrchestrationContext-Kontext){ var output = new List<string>(); output.Add(await context.CallActivityAsync<string>("SayHello", "Tokyo")); Outputs.Add(await context.CallActivityAsync<string>("SayHello", "Seattle")); Outputs.Add(await context.CallActivityAsync<string>("SayHello", "London")); // gibt ["Hallo Tokio!", "Hallo Seattle!", "Hallo London!"] zurück.

Whenever an activity function is scheduled, the Durable Task Framework checks the execution status of the function in a durable storage backend (Azure Table storage by default). This condition is calledhistory of orchestration.

history table

In general, the Durable Task Framework does the following at each checkpoint:

1. Save execution history to persistent storage.
2. Queues messages for functions that the orchestrator wants to invoke.
3. Queues messages to the orchestrator itself, e.g. B. Persistent timer messages.

Once the checkpoint is complete, the orchestrator function can be removed from memory until more work needs to be done.

When you're done, the function history shown above will look like the following table in Azure Table Storage (abbreviated for clarity):

A few notes about the column values:

• partition key: Contains the instance ID of the orchestration.
• event type: Represents the type of event. You can find detailed descriptions of all kinds of historical eventshere.
• time stamp: The UTC timestamp of the historical event.
• Name: The name of the called function.
• Entry: The JSON-formatted input for the function.
• Result: The output of the function; that is, its return value.

Each time the function resumes after waiting for a task to complete, the Durable Task Framework runs the orchestrator function from scratch. On each iteration, it queries the execution history to see if the current asynchronous task is complete. If the execution history shows that the task has already been completed, the framework reflects the result of that task and moves on to the next task. This process continues until all execution history has been replayed. Once the current execution history was replayed, the local variables were reset to their previous values.

features and patterns

The following sections describe the features and patterns of orchestrator functions.

sub-orchestrations

Orchestrator functions can call activity functions, but also other orchestrator functions. For example, you can create a larger orchestration from a library of orchestrator functions. Or you can run multiple instances of an orchestrator function in parallel.

For more information and examples seesub-orchestrationsArticle.

long-lasting Hours

Orchestrations can be scheduledlong-lasting Hoursto implement delays or to configure timeout handling for asynchronous actions. Use persistent timers in orchestrator functions instead of native language "sleep" APIs.

For more information and examples seelong-lasting HoursArticle.

external events

Orchestrator functions can wait for external events to update an orchestration instance. This Durable Functions feature is often useful for handling human interactions or other external callbacks.

For more information and examples seeexternal eventsArticle.

error handling

Orchestrator functions can use the error-handling features of the programming language. existing patterns likeattempt/captureThey are supported by the orchestration code.

Orchestrator functions can also add retry policies to the activity or sub-orchestrator functions they call. If a sub-orquesterer function or activity fails with an exception, the specified retry policy can automatically delay execution up to a specified number of times and try again.

For more information and examples seeerror handlingArticle.

Critical sections (Durable Functions 2.x, currently .NET only)

Orchestration instances are single-threaded, so you don't have to worry about race conditions.Withinan orchestration. However, race conditions are possible when orchestrations interact with external systems. Orchestrator functions can be defined to mitigate race conditions when interacting with external systemscritical sectionsusing aLockAsyncMethod in .NET.

The following sample code shows an orchestrator function that defines a critical section. Include the critical sectionLockAsyncMethod. This method requires passing one or more references to apermanent unit, which permanently manages the lock state. Only a single instance of this orchestration can run the code in the critical section at a time.

[FunctionName("Synchronize")] Public Static Asynchronous Task Synchronization([Orchestration Trigger] IDurableOrchestrationContext context){ var lockId = new EntityId("LockEntity", "MyLockIdentifier"); using (await context.LockAsync(lockId)) { // critical section: you can only enter one orchestration at a time }}

IsLockAsyncacquires the permanent lock(s) and returns adisposablewhich ends the critical section when disposed of. ThisdisposableThe result can be used together with auseblock to get a syntactical representation of the critical section. When an orchestrator function enters a critical section, only one instance can run that block of code. Any other instance trying to enter the critical section will be blocked until the previous instance exits the critical section.

The critical sections feature is also useful for coordinating changes to persistent entities. For more information about critical sections, seePermanent Units "Coordination of Units"him.

Invoking HTTP endpoints (Durable Functions 2.x)

Orchestrator functions cannot perform I/O operations as described inOrchestrator function code limitations. The typical workaround for this limitation is to wrap any code that needs to perform I/O operations in an activity function. Orchestrations that interact with external systems often use activity functions to make HTTP calls and return the result to the orchestration.

public static asynchronous task [FunctionName("CheckSiteAvailable")]CheckSiteAvailable ([OrchestrationTrigger] IDurableOrchestrationContext context){ Uri url = context.GetInput<Uri>(); // Send an HTTP GET request to the specified endpoint Response DurableHttpResponse = await context.CallHttpAsync(HttpMethod.Get, url); if ((int)response.StatusCode == 400) { // Here comes the error code handling }}

In addition to supporting basic request/response patterns, the mechanism supports automatic handling of common asynchronous HTTP-202 query patterns and also supports authentication using external servicesManaged Identities.

For more information and detailed examples, seeHTTP functionsArticle.

Pass multiple parameters

It is not possible to pass multiple parameters directly to an activity function. The recommendation is to pass an array of objects or compound objects.

[FunctionName("GetCourseRecommendations")]Public Static Asynchronous Task<Object> RunOrchestrator( [OrchestrationTrigger] IDurableOrchestrationContext context){ string major = "ComputerScience"; int collegeyear = context.GetInput<int>(); object CourseRecommendations = await context.CallActivityAsync<object>( "CourseRecommendations", (major, universityYear)); return CourseRecommendations;}[FunctionName("CourseRecommendations")]public static async Task<object> Mapper([Activity Trigger] IDurableActivityContext input){ // parse the student major and year input (string Major, int UniversityYear) studentInfo = entrance. GetInput<(string, int)>(); // Get and return course recommendations by major and year of study return new { major = studentInfo.Major, universityYear = studentInfo.UniversityYear, addedCourses = new [] { "Introduction to .NET Programming", "Introduction to Linux", " Becoming an Unternehmer" } };}

Next Steps