Bindings for Durable Functions (Azure Functions)

Both versions of the Python programming model for Azure Functions are supported by Durable Functions. Because Python v2 is the recommended version, examples in this article exclusively feature this version.

Prerequisites

• Durable Functions SDK, which is the Python Package Index (PyPI) package azure-functions-durable, version 1.2.2 or a later version
• Extension bundle version 4.x (or a later version), which is set in the host.json project file

You can provide feedback and suggestions in the Durable Functions SDK for Python repository.

When you develop functions in .NET, you use the OrchestrationTriggerAttribute .NET attribute to configure the orchestration trigger.

For Java, you use the @DurableOrchestrationTrigger annotation to configure the orchestration trigger.

When you use version 4 of the Node.js programming model to develop functions, you import the app object from the @azure/functions npm module. Then you call the app.orchestration method of the Durable Functions API directly in your function code. This method registers your orchestrator function with the Durable Functions framework.

When you write orchestrator functions, you define the orchestration trigger by using the following JSON object in the bindings array of the function.json file:

{
    "name": "<name-of-input-parameter-in-function-signature>",
    "orchestration": "<optional-name-of-orchestration>",
    "type": "orchestrationTrigger",
    "direction": "in"
}

The orchestration value is the name of the orchestration that clients must use when they want to start new instances of the orchestrator function. This property is optional. If you don't specify it, the name of the function is used.

When you use the Python v2 programming model, you can define an orchestration trigger by using the orchestration_trigger decorator directly in your Python function code.

In the v2 model, you access the Durable Functions triggers and bindings from an instance of DFApp. You can use this subclass of FunctionApp to export decorators that are specific to Durable Functions.

The attribute that you use to define the trigger depends on whether you run your C# functions in the same process as the Functions host process or in an isolated worker process.

[FunctionName("HelloWorld")]
public static string RunOrchestrator([OrchestrationTrigger] IDurableOrchestrationContext context)
{
    string name = context.GetInput<string>();
    return $"Hello {name}!";
}

[Function("HelloWorld")]
public static string RunOrchestrator([OrchestrationTrigger] TaskOrchestrationContext context, string name)
{
    return $"Hello {name}!";
}

const { app } = require('@azure/functions');
const df = require('durable-functions');

df.app.orchestration('helloOrchestrator', function* (context) {
    const name = context.df.getInput();
    return `Hello ${name}`;
});

import azure.functions as func
import azure.durable_functions as df

myApp = df.DFApp(http_auth_level=func.AuthLevel.ANONYMOUS)

@myApp.orchestration_trigger(context_name="context")
def my_orchestrator(context):
    result = yield context.call_activity("Hello", "Tokyo")
    return result

param($Context)

$InputData = $Context.Input
$InputData

@FunctionName("HelloWorldOrchestration")
public String helloWorldOrchestration(
        @DurableOrchestrationTrigger(name = "ctx") TaskOrchestrationContext ctx) {
    return String.format("Hello %s!", ctx.getInput(String.class));
}

Most orchestrator functions call activity functions. The following code provides a Hello World example that demonstrates how to call an activity function:

const { app } = require('@azure/functions');
const df = require('durable-functions');

const activityName = 'hello';

df.app.orchestration('helloOrchestrator', function* (context) {
    const name = context.df.getInput();
    const result = yield context.df.callActivity(activityName, name);
    return result;
});

@FunctionName("HelloWorld")
public String helloWorldOrchestration(
        @DurableOrchestrationTrigger(name = "ctx") TaskOrchestrationContext ctx) {
    String input = ctx.getInput(String.class);
    String result = ctx.callActivity("SayHello", input, String.class).await();
    return result;
}

You use the ActivityTriggerAttribute .NET attribute to configure the activity trigger.

You use the @DurableActivityTrigger annotation to configure the activity trigger.

To register your activity function, you import the app object from the @azure/functions npm module. Then you call the app.activity method of the Durable Functions API directly in your function code.

To define the activity trigger, you use the following JSON object in the bindings array of function.json:

{
    "name": "<name-of-input-parameter-in-function-signature>",
    "activity": "<optional-name-of-activity>",
    "type": "activityTrigger",
    "direction": "in"
}

The activity value is the name of the activity. This value is the name that orchestrator functions use to invoke this activity function. This property is optional. If you don't specify it, the name of the function is used.

You can define an activity trigger by using the activity_trigger decorator directly in your Python function code.

const { app } = require('@azure/functions');
const df = require('durable-functions');
const activityName = 'hello';
df.app.activity(activityName, {
    handler: (input) => {
        return `Hello, ${input}`;
    },
});

import azure.functions as func
import azure.durable_functions as df

myApp = df.DFApp(http_auth_level=func.AuthLevel.ANONYMOUS)

@myApp.activity_trigger(input_name="myInput")
def my_activity(myInput: str):
    return "Hello " + myInput

param($name)

"Hello $name!"

@FunctionName("SayHello")
public String sayHello(@DurableActivityTrigger(name = "name") String name) {
    return String.format("Hello %s!", name);
}

For example, an activity function can receive input from an orchestrator function. The activity function can then send that input as a message to Azure Event Hubs.

const { app } = require('@azure/functions');
const df = require('durable-functions');

df.app.orchestration('helloOrchestrator', function* (context) {
    const input = context.df.getInput();
    yield context.df.callActivity('sendToEventHub', input);
    return `Message sent: ${input}`;
});

const { EventHubProducerClient } = require("@azure/event-hubs");
const connectionString = process.env.EVENT_HUB_CONNECTION_STRING;
const eventHubName = process.env.EVENT_HUB_NAME;

df.app.activity("sendToEventHub", {
    handler: async (message, context) => {
        const producer = new EventHubProducerClient(connectionString, eventHubName);
        try {
            const batch = await producer.createBatch();
            batch.tryAdd({ body: message });
            await producer.sendBatch(batch);
            context.log(`Message sent to Event Hubs: ${message}`);
        } catch (err) {
            context.log.error("Failed to send message to Event Hubs:", err);
            throw err;
        } finally {
            await producer.close();
        }
    },
});

app.storageQueue('helloQueueStart', {
    queueName: 'start-orchestration',
    extraInputs: [df.input.durableClient()],
    handler: async (message, context) => {
        const client = df.getClient(context);
        const orchestratorName = message.orchestratorName || 'helloOrchestrator';
        const input = message.input || null;
        const instanceId = await client.startNew(orchestratorName, { input });
        context.log(`Started orchestration with ID = '${instanceId}'`);
    },
});

You can bind to an orchestration client by using the DurableClientAttribute attribute (OrchestrationClientAttribute in Durable Functions 1.x).

You can bind to an orchestration client by using the @DurableClientInput annotation.

To register your client function, you import the app object from the @azure/functions npm module. Then you call a Durable Functions API method that's specific to your trigger type. For instance, for an HTTP trigger, you call the app.http method. For a queue trigger, you call the app.storageQueue method.

To define the durable client trigger, you use the following JSON object in the bindings array of function.json:

{
    "name": "<name-of-input-parameter-in-function-signature>",
    "taskHub": "<optional-name-of-task-hub>",
    "connectionName": "<optional-name-of-connection-string-app-setting>",
    "type": "orchestrationClient",
    "direction": "in"
}

• The taskHub property is used when multiple function apps share the same storage account but need to be isolated from each other. If you don't specify this property, the default value from host.json is used. This value must match the value that the target orchestrator functions use.
• The connectionName value is the name of an app setting that contains a storage account connection string. The storage account represented by this connection string must be the same one that the target orchestrator functions use. If you don't specify this property, the default storage account connection string for the function app is used.

You can define a durable client trigger by using the durable_client_input decorator directly in your Python function code.

You typically bind to an implementation of IDurableClient (DurableOrchestrationClient in Durable Functions 1.x), which gives you full access to all orchestration client APIs that Durable Functions supports.

You typically bind to the DurableClientContext class.

You must use the language-specific SDK to get access to a client object.

const { app } = require('@azure/functions');
const df = require('durable-functions');

app.storageQueue('helloQueueStart', {
    queueName: 'start-orchestration',
    extraInputs: [df.input.durableClient()],
    handler: async (message, context) => {
        const client = df.getClient(context);
        const orchestratorName = message.orchestratorName || 'helloOrchestrator';
        const input = message.input || null;
        const instanceId = await client.startNew(orchestratorName, { input });
        context.log(`Started orchestration with ID = '${instanceId}' from queue message.`);
    },
});

import azure.functions as func
import azure.durable_functions as df

myApp = df.DFApp(http_auth_level=func.AuthLevel.ANONYMOUS)

@myApp.queue_trigger(
    arg_name="msg",
    queue_name="start-orchestration",
    connection="AzureWebJobsStorage"
)
@myApp.durable_client_input(client_name="client")
async def client_function(msg: func.QueueMessage, client: df.DurableOrchestrationClient):
    input_data = msg.get_body().decode("utf-8")
    await client.start_new("my_orchestrator", None, input_data)
    return None

function.json

{
  "bindings": [
    {
      "name": "InputData",
      "type": "queueTrigger",
      "queueName": "durable-function-trigger",
      "direction": "in"
    },
    {
      "name": "starter",
      "type": "durableClient",
      "direction": "in"
    }
  ]
}

run.ps1

param([string]$InputData, $TriggerMetadata)

$InstanceId = Start-DurableOrchestration -FunctionName 'HelloWorld' -Input $InputData

@FunctionName("QueueStart")
public void queueStart(
        @QueueTrigger(name = "input", queueName = "durable-function-trigger", connection = "Storage") String input,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext) {
    // Orchestration input comes from the queue message content.
    durableContext.getClient().scheduleNewOrchestrationInstance("HelloWorld", input);
}

You use the EntityTriggerAttribute .NET attribute to configure the entity trigger.

To register the entity trigger, you import the app object from the @azure/functions npm module. Then you call the app.entity method of the Durable Functions API directly in your function code.

const df = require('durable-functions');
df.app.entity('counter', (context) => {
    const currentValue = context.df.getState(() => 0);
    switch (context.df.operationName) {
        case 'add':
            context.df.setState(currentValue + context.df.getInput());
            break;
        case 'reset':
            context.df.setState(0);
            break;
        case 'get':
            context.df.return(currentValue);
            break;
    }
});

You can define an entity trigger by using the entity_trigger decorator directly in your Python function code.

You can bind to the entity client by using the DurableClientAttribute .NET attribute in .NET class library functions.

Instead of registering an entity client, you use signalEntity or callEntity to call an entity trigger method from any registered function.

• From a queue-triggered function, you can use client.signalEntity:

  const { app } = require('@azure/functions');
  const df = require('durable-functions');
  app.storageQueue('helloQueueStart', {
      queueName: 'start-orchestration',
      extraInputs: [df.input.durableClient()],
      handler: async (message, context) => {
          const client = df.getClient(context);
          const entityId = new df.EntityId('counter', 'myCounter');
          await client.signalEntity(entityId, 'add', 5);
      },
  });
  

• From an orchestrator function, you can use context.df.callEntity:

  const { app } = require('@azure/functions');
  const df = require('durable-functions');
  df.app.orchestration('entityCaller', function* (context) {
      const entityId = new df.EntityId('counter', 'myCounter');
      yield context.df.callEntity(entityId, 'add', 5);
      yield context.df.callEntity(entityId, 'add', 5);
      const result = yield context.df.callEntity(entityId, 'get');
      return result;
  });
  

You can define an entity client by using the durable_client_input decorator directly in your Python function code.