Table of Contents

Class DurableOrchestrationClientBase

Namespace
Microsoft.Azure.WebJobs
Assembly
Microsoft.Azure.WebJobs.Extensions.DurableTask.dll

Abstract base class for DurableOrchestrationClient.

public abstract class DurableOrchestrationClientBase
Inheritance
DurableOrchestrationClientBase
Derived
Inherited Members

Constructors

DurableOrchestrationClientBase() 

protected DurableOrchestrationClientBase()

Properties

TaskHubName

Gets the name of the task hub configured on this client instance.

public abstract string TaskHubName { get; }

Property Value

string

The name of the task hub.

Methods

CreateCheckStatusResponse(HttpRequestMessage, string)

Creates an HTTP response that is useful for checking the status of the specified instance.

public abstract HttpResponseMessage CreateCheckStatusResponse(HttpRequestMessage request, string instanceId)

Parameters

request HttpRequestMessage

The HTTP request that triggered the current orchestration instance.

instanceId string

The ID of the orchestration instance to check.

Returns

HttpResponseMessage

An HTTP 202 response with a Location header and a payload containing instance control URLs.

Remarks

The payload of the returned HttpResponseMessage contains HTTP API URLs that can be used to query the status of the orchestration, raise events to the orchestration, or terminate the orchestration.

CreateHttpManagementPayload(string)

Creates a HttpManagementPayload object that contains status, terminate and send external event HTTP endpoints.

public abstract HttpManagementPayload CreateHttpManagementPayload(string instanceId)

Parameters

instanceId string

The ID of the orchestration instance to check.

Returns

HttpManagementPayload

Instance of the HttpManagementPayload class.

GetStatusAsync(DateTime, DateTime?, IEnumerable<OrchestrationRuntimeStatus>, int, string, CancellationToken)

Gets the status of all orchestration instances with paging that match the specified conditions.

public abstract Task<OrchestrationStatusQueryResult> GetStatusAsync(DateTime createdTimeFrom, DateTime? createdTimeTo, IEnumerable<OrchestrationRuntimeStatus> runtimeStatus, int pageSize, string continuationToken, CancellationToken cancellationToken = default)

Parameters

createdTimeFrom DateTime

Return orchestration instances which were created after this DateTime.

createdTimeTo DateTime?

Return orchestration instances which were created before this DateTime.

runtimeStatus IEnumerable<OrchestrationRuntimeStatus>

Return orchestration instances which matches the runtimeStatus.

pageSize int

Number of records per one request.

continuationToken string

ContinuationToken of the pager.

cancellationToken CancellationToken

Cancellation token that can be used to cancel the status query operation.

Returns

Task<OrchestrationStatusQueryResult>

Returns each page of orchestration status for all instances and continuation token of next page.

GetStatusAsync(DateTime, DateTime?, IEnumerable<OrchestrationRuntimeStatus>, CancellationToken)

Gets the status of all orchestration instances that match the specified conditions.

public abstract Task<IList<DurableOrchestrationStatus>> GetStatusAsync(DateTime createdTimeFrom, DateTime? createdTimeTo, IEnumerable<OrchestrationRuntimeStatus> runtimeStatus, CancellationToken cancellationToken = default)

Parameters

createdTimeFrom DateTime

Return orchestration instances which were created after this DateTime.

createdTimeTo DateTime?

Return orchestration instances which were created before this DateTime.

runtimeStatus IEnumerable<OrchestrationRuntimeStatus>

Return orchestration instances which matches the runtimeStatus.

cancellationToken CancellationToken

Cancellation token that can be used to cancel the status query operation.

Returns

Task<IList<DurableOrchestrationStatus>>

Returns orchestration status for all instances.

GetStatusAsync(string)

Gets the status of the specified orchestration instance.

public virtual Task<DurableOrchestrationStatus> GetStatusAsync(string instanceId)

Parameters

instanceId string

The ID of the orchestration instance to query.

Returns

Task<DurableOrchestrationStatus>

Returns a task which completes when the status has been fetched.

GetStatusAsync(string, bool)

Gets the status of the specified orchestration instance.

public virtual Task<DurableOrchestrationStatus> GetStatusAsync(string instanceId, bool showHistory)

Parameters

instanceId string

The ID of the orchestration instance to query.

showHistory bool

Boolean marker for including execution history in the response.

Returns

Task<DurableOrchestrationStatus>

Returns a task which completes when the status has been fetched.

GetStatusAsync(string, bool, bool, bool)

Gets the status of the specified orchestration instance.

public abstract Task<DurableOrchestrationStatus> GetStatusAsync(string instanceId, bool showHistory, bool showHistoryOutput, bool showInput = true)

Parameters

instanceId string

The ID of the orchestration instance to query.

showHistory bool

Boolean marker for including execution history in the response.

showHistoryOutput bool

Boolean marker for including input and output in the execution history response.

showInput bool

If set, fetch and return the input for the orchestration instance.

Returns

Task<DurableOrchestrationStatus>

Returns a task which completes when the status has been fetched.

GetStatusAsync(CancellationToken)

Gets all the status of the orchestration instances.

public abstract Task<IList<DurableOrchestrationStatus>> GetStatusAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancellation token that can be used to cancel the status query operation.

Returns

Task<IList<DurableOrchestrationStatus>>

Returns orchestration status for all instances.

PurgeInstanceHistoryAsync(DateTime, DateTime?, IEnumerable<OrchestrationStatus>)

Purge the orchestration history for instances that match the conditions.

public abstract Task<PurgeHistoryResult> PurgeInstanceHistoryAsync(DateTime createdTimeFrom, DateTime? createdTimeTo, IEnumerable<OrchestrationStatus> runtimeStatus)

Parameters

createdTimeFrom DateTime

Start creation time for querying instances for purging.

createdTimeTo DateTime?

End creation time for querying instances for purging.

runtimeStatus IEnumerable<OrchestrationStatus>

List of runtime status for querying instances for purging. Only Completed, Terminated, or Failed will be processed.

Returns

Task<PurgeHistoryResult>

Returns an instance of PurgeHistoryResult.

PurgeInstanceHistoryAsync(string)

Purge the history for a concrete instance.

public abstract Task<PurgeHistoryResult> PurgeInstanceHistoryAsync(string instanceId)

Parameters

instanceId string

The ID of the orchestration instance to purge.

Returns

Task<PurgeHistoryResult>

Returns an instance of PurgeHistoryResult.

RaiseEventAsync(string, string)

Sends an event notification message to a waiting orchestration instance.

public virtual Task RaiseEventAsync(string instanceId, string eventName)

Parameters

instanceId string

The ID of the orchestration instance that will handle the event.

eventName string

The name of the event.

Returns

Task

A task that completes when the event notification message has been enqueued.

Remarks

In order to handle the event, the target orchestration instance must be waiting for an event named eventName using the WaitForExternalEvent<T>(string) API.

If the specified instance is not found or not running, this operation will have no effect.

RaiseEventAsync(string, string, object)

Sends an event notification message to a waiting orchestration instance.

public abstract Task RaiseEventAsync(string instanceId, string eventName, object eventData)

Parameters

instanceId string

The ID of the orchestration instance that will handle the event.

eventName string

The name of the event.

eventData object

The JSON-serializeable data associated with the event.

Returns

Task

A task that completes when the event notification message has been enqueued.

Remarks

In order to handle the event, the target orchestration instance must be waiting for an event named eventName using the WaitForExternalEvent<T>(string) API.

If the specified instance is not found or not running, this operation will have no effect.

RaiseEventAsync(string, string, string, object, string)

Sends an event notification message to a waiting orchestration instance.

public abstract Task RaiseEventAsync(string taskHubName, string instanceId, string eventName, object eventData, string connectionName = null)

Parameters

taskHubName string

The TaskHubName of the orchestration that will handle the event.

instanceId string

The ID of the orchestration instance that will handle the event.

eventName string

The name of the event.

eventData object

The JSON-serializeable data associated with the event.

connectionName string

The name of the connection string associated with taskHubName.

Returns

Task

A task that completes when the event notification message has been enqueued.

Remarks

In order to handle the event, the target orchestration instance must be waiting for an event named eventName using the WaitForExternalEvent<T>(string) API.

If the specified instance is not found or not running, this operation will have no effect.

RewindAsync(string, string)

Rewinds the specified failed orchestration instance with a reason.

public abstract Task RewindAsync(string instanceId, string reason)

Parameters

instanceId string

The ID of the orchestration instance to rewind.

reason string

The reason for rewinding the orchestration instance.

Returns

Task

A task that completes when the rewind message is enqueued.

StartNewAsync(string, object)

Starts a new execution of the specified orchestrator function.

public virtual Task<string> StartNewAsync(string orchestratorFunctionName, object input)

Parameters

orchestratorFunctionName string

The name of the orchestrator function to start.

input object

JSON-serializeable input value for the orchestrator function.

Returns

Task<string>

A task that completes when the orchestration is started.

Exceptions

ArgumentException

The specified function does not exist, is disabled, or is not an orchestrator function.

StartNewAsync(string, string, object)

Starts a new instance of the specified orchestrator function.

public abstract Task<string> StartNewAsync(string orchestratorFunctionName, string instanceId, object input)

Parameters

orchestratorFunctionName string

The name of the orchestrator function to start.

instanceId string

The ID to use for the new orchestration instance.

input object

JSON-serializeable input value for the orchestrator function.

Returns

Task<string>

A task that completes when the orchestration is started.

Remarks

If an orchestration instance with the specified ID already exists, the existing instance will be silently replaced by this new instance.

Exceptions

ArgumentException

The specified function does not exist, is disabled, or is not an orchestrator function.

TerminateAsync(string, string)

Terminates a running orchestration instance.

public abstract Task TerminateAsync(string instanceId, string reason)

Parameters

instanceId string

The ID of the orchestration instance to terminate.

reason string

The reason for terminating the orchestration instance.

Returns

Task

A task that completes when the terminate message is enqueued.

Remarks

Terminating an orchestration instance has no effect on any in-flight activity function executions or sub-orchestrations that were started by the current orchestration instance.

WaitForCompletionOrCreateCheckStatusResponseAsync(HttpRequestMessage, string)

Creates an HTTP response which either contains a payload of management URLs for a non-completed instance or contains the payload containing the output of the completed orchestration.

public virtual Task<HttpResponseMessage> WaitForCompletionOrCreateCheckStatusResponseAsync(HttpRequestMessage request, string instanceId)

Parameters

request HttpRequestMessage

The HTTP request that triggered the current function.

instanceId string

The unique ID of the instance to check.

Returns

Task<HttpResponseMessage>

An HTTP response which may include a 202 and location header or a 200 with the durable function output in the response body.

Remarks

If the orchestration instance completes within the default 10 second timeout, then the HTTP response payload will contain the output of the orchestration instance formatted as JSON. However, if the orchestration does not complete within this timeout, then the HTTP response will be identical to that of the CreateCheckStatusResponse(HttpRequestMessage, string) API.

WaitForCompletionOrCreateCheckStatusResponseAsync(HttpRequestMessage, string, TimeSpan)

Creates an HTTP response which either contains a payload of management URLs for a non-completed instance or contains the payload containing the output of the completed orchestration.

public virtual Task<HttpResponseMessage> WaitForCompletionOrCreateCheckStatusResponseAsync(HttpRequestMessage request, string instanceId, TimeSpan timeout)

Parameters

request HttpRequestMessage

The HTTP request that triggered the current function.

instanceId string

The unique ID of the instance to check.

timeout TimeSpan

Total allowed timeout for output from the durable function. The default value is 10 seconds.

Returns

Task<HttpResponseMessage>

An HTTP response which may include a 202 and location header or a 200 with the durable function output in the response body.

Remarks

If the orchestration instance completes within the specified timeout, then the HTTP response payload will contain the output of the orchestration instance formatted as JSON. However, if the orchestration does not complete within the specified timeout, then the HTTP response will be identical to that of the CreateCheckStatusResponse(HttpRequestMessage, string) API.

WaitForCompletionOrCreateCheckStatusResponseAsync(HttpRequestMessage, string, TimeSpan, TimeSpan)

Creates an HTTP response which either contains a payload of management URLs for a non-completed instance or contains the payload containing the output of the completed orchestration.

public abstract Task<HttpResponseMessage> WaitForCompletionOrCreateCheckStatusResponseAsync(HttpRequestMessage request, string instanceId, TimeSpan timeout, TimeSpan retryInterval)

Parameters

request HttpRequestMessage

The HTTP request that triggered the current function.

instanceId string

The unique ID of the instance to check.

timeout TimeSpan

Total allowed timeout for output from the durable function. The default value is 10 seconds.

retryInterval TimeSpan

The timeout between checks for output from the durable function. The default value is 1 second.

Returns

Task<HttpResponseMessage>

An HTTP response which may include a 202 and location header or a 200 with the durable function output in the response body.

Remarks

If the orchestration instance completes within the specified timeout, then the HTTP response payload will contain the output of the orchestration instance formatted as JSON. However, if the orchestration does not complete within the specified timeout, then the HTTP response will be identical to that of the CreateCheckStatusResponse(HttpRequestMessage, string) API.