Rediger

Singleton orchestrators in Durable Task

For background jobs, you often need to ensure that only one instance of a particular orchestrator runs at a time, preventing duplicate orchestrations from running concurrently. You can implement this singleton pattern in Durable Functions or the Durable Task SDKs by assigning a specific instance ID to an orchestrator when creating it, and then checking if an instance with that ID is already running before starting a new one.

This article shows how to implement singleton orchestrators with code examples for each supported language.

Prerequisites

Note

There is a potential race condition in the singleton pattern. If two clients execute the check-and-start logic concurrently, both calls might report success, but only one orchestration instance actually starts. Depending on your requirements, this may have undesirable side effects. If strict single-instance guarantees are required, consider adding additional locking mechanisms.

Important

Currently, the PowerShell Durable Task SDK isn't available.

Singleton orchestrator example

The following example shows an HTTP-trigger function that creates a singleton background job orchestration. The code attempts to ensure that only one active instance exists for a specified instance ID.

[Function("HttpStartSingle")]
public static async Task<HttpResponseData> RunSingle(
    [HttpTrigger(AuthorizationLevel.Function, "post", Route = "orchestrators/{functionName}/{instanceId}")] HttpRequestData req,
    [DurableClient] DurableTaskClient starter,
    string functionName,
    string instanceId,
    FunctionContext executionContext)
{
    ILogger logger = executionContext.GetLogger("HttpStartSingle");

    // Check if an instance with the specified ID already exists or an existing one stopped running(completed/failed/terminated).
    OrchestrationMetadata? existingInstance = await starter.GetInstanceAsync(instanceId, getInputsAndOutputs: false);
    if (existingInstance == null 
    || existingInstance.RuntimeStatus == OrchestrationRuntimeStatus.Completed 
    || existingInstance.RuntimeStatus == OrchestrationRuntimeStatus.Failed 
    || existingInstance.RuntimeStatus == OrchestrationRuntimeStatus.Terminated)
    {
        // An instance with the specified ID doesn't exist or an existing one stopped running, create one.
        string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
        await starter.ScheduleNewOrchestrationInstanceAsync(functionName, requestBody, new StartOrchestrationOptions { InstanceId = instanceId });
        logger.LogInformation($"Started orchestration with ID = '{instanceId}'.");
        return await starter.CreateCheckStatusResponseAsync(req, instanceId);
    }
    else
    {
        // An instance with the specified ID exists or an existing one still running, don't create one.
        var response = req.CreateResponse(HttpStatusCode.Conflict);
        await response.WriteStringAsync($"An instance with ID '{instanceId}' already exists.");
        return response;
    }
}

Note

The previous C# code is for the isolated worker model, which is the recommended model for .NET apps. For more information about the differences between the in-process and isolated worker models, see the Durable Functions versions article.

The following example shows how to create a singleton orchestration using the Durable Task SDKs. The code attempts to ensure that only one active instance exists for a specified instance ID.

using Microsoft.DurableTask.Client;

// Check if an instance with the specified ID already exists
string instanceId = "singleton-job";
OrchestrationMetadata? existingInstance = await client.GetInstanceAsync(instanceId, getInputsAndOutputs: false);

if (existingInstance == null ||
    existingInstance.RuntimeStatus == OrchestrationRuntimeStatus.Completed ||
    existingInstance.RuntimeStatus == OrchestrationRuntimeStatus.Failed ||
    existingInstance.RuntimeStatus == OrchestrationRuntimeStatus.Terminated)
{
    // An instance with the specified ID doesn't exist or an existing one stopped running, create one.
    await client.ScheduleNewOrchestrationInstanceAsync("MyOrchestration", input, new StartOrchestrationOptions(instanceId));
    Console.WriteLine($"Started orchestration with ID = '{instanceId}'.");
}
else
{
    // An instance with the specified ID exists or an existing one still running.
    Console.WriteLine($"An instance with ID '{instanceId}' already exists.");
}

How the singleton pattern works

Because instance IDs are unique within a task hub, scheduling an orchestration with a known, fixed ID and checking its status first prevents duplicate concurrent runs. By default, instance IDs are randomly generated GUIDs. In the previous examples, however, a specific instance ID is passed in. The code then fetches the orchestration instance metadata to check if an instance with that ID is already running. If no such instance is running, a new instance is created with that ID.

The orchestrator function itself can use any pattern — a standard function that starts and completes, or an Eternal Orchestration that runs continuously. The singleton pattern only controls how many instances run concurrently.

Next steps

Learn about the native HTTP features of orchestrations

Get started with Durable Task SDKs

  • Last updated on