Class DurableOrchestrationClient

Client for starting, querying, terminating, and raising events to orchestration instances.

Inheritance

System.Object

DurableOrchestrationClientBase

DurableOrchestrationClient

Inherited Members

DurableOrchestrationClientBase.WaitForCompletionOrCreateCheckStatusResponseAsync(HttpRequestMessage, String)

DurableOrchestrationClientBase.WaitForCompletionOrCreateCheckStatusResponseAsync(HttpRequestMessage, String, TimeSpan)

DurableOrchestrationClientBase.StartNewAsync(String, Object)

DurableOrchestrationClientBase.RaiseEventAsync(String, String)

DurableOrchestrationClientBase.GetStatusAsync(String)

DurableOrchestrationClientBase.GetStatusAsync(String, Boolean)

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.ToString()

Namespace: Microsoft.Azure.WebJobs

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

Syntax

public class DurableOrchestrationClient : DurableOrchestrationClientBase

Properties

| Improve this Doc View Source

TaskHubName

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

Declaration

public override string TaskHubName { get; }

Property Value

Type	Description
System.String	The name of the task hub.

Overrides

DurableOrchestrationClientBase.TaskHubName

Methods

| Improve this Doc View Source

CreateCheckStatusResponse(HttpRequestMessage, String)

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

Declaration

public override HttpResponseMessage CreateCheckStatusResponse(HttpRequestMessage request, string instanceId)

Parameters

Type	Name	Description
System.Net.Http.HttpRequestMessage	request	The HTTP request that triggered the current orchestration instance.
System.String	instanceId	The ID of the orchestration instance to check.

Returns

Type	Description
System.Net.Http.HttpResponseMessage	An HTTP 202 response with a Location header and a payload containing instance control URLs.

Overrides

DurableOrchestrationClientBase.CreateCheckStatusResponse(HttpRequestMessage, String)

Remarks

The payload of the returned System.Net.Http.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.

| Improve this Doc View Source

CreateHttpManagementPayload(String)

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

Declaration

public override HttpManagementPayload CreateHttpManagementPayload(string instanceId)

Parameters

Type	Name	Description
System.String	instanceId	The ID of the orchestration instance to check.

Returns

Type	Description
HttpManagementPayload	Instance of the HttpManagementPayload class.

Overrides

DurableOrchestrationClientBase.CreateHttpManagementPayload(String)

| Improve this Doc View Source

GetStatusAsync(DateTime, Nullable<DateTime>, IEnumerable<OrchestrationRuntimeStatus>, Int32, String, CancellationToken)

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

Declaration

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

Parameters

Type	Name	Description
System.DateTime	createdTimeFrom	Return orchestration instances which were created after this DateTime.
System.Nullable<System.DateTime>	createdTimeTo	Return orchestration instances which were created before this DateTime.
System.Collections.Generic.IEnumerable<OrchestrationRuntimeStatus>	runtimeStatus	Return orchestration instances which matches the runtimeStatus.
System.Int32	pageSize	Number of records per one request.
System.String	continuationToken	ContinuationToken of the pager.
System.Threading.CancellationToken	cancellationToken	Cancellation token that can be used to cancel the status query operation.

Returns

Type	Description
System.Threading.Tasks.Task<OrchestrationStatusQueryResult>	Returns each page of orchestration status for all instances and continuation token of next page.

Overrides

DurableOrchestrationClientBase.GetStatusAsync(DateTime, Nullable<DateTime>, IEnumerable<OrchestrationRuntimeStatus>, Int32, String, CancellationToken)

| Improve this Doc View Source

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

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

Declaration

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

Parameters

Type	Name	Description
System.DateTime	createdTimeFrom	Return orchestration instances which were created after this DateTime.
System.Nullable<System.DateTime>	createdTimeTo	Return orchestration instances which were created before this DateTime.
System.Collections.Generic.IEnumerable<OrchestrationRuntimeStatus>	runtimeStatus	Return orchestration instances which matches the runtimeStatus.
System.Threading.CancellationToken	cancellationToken	Cancellation token that can be used to cancel the status query operation.

Returns

Type	Description
System.Threading.Tasks.Task<System.Collections.Generic.IList<DurableOrchestrationStatus>>	Returns orchestration status for all instances.

Overrides

DurableOrchestrationClientBase.GetStatusAsync(DateTime, Nullable<DateTime>, IEnumerable<OrchestrationRuntimeStatus>, CancellationToken)

| Improve this Doc View Source

GetStatusAsync(String, Boolean, Boolean, Boolean)

Gets the status of the specified orchestration instance.

Declaration

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

Parameters

Type	Name	Description
System.String	instanceId	The ID of the orchestration instance to query.
System.Boolean	showHistory	Boolean marker for including execution history in the response.
System.Boolean	showHistoryOutput	Boolean marker for including input and output in the execution history response.
System.Boolean	showInput	If set, fetch and return the input for the orchestration instance.

Returns

Type	Description
System.Threading.Tasks.Task<DurableOrchestrationStatus>	Returns a task which completes when the status has been fetched.

Overrides

DurableOrchestrationClientBase.GetStatusAsync(String, Boolean, Boolean, Boolean)

| Improve this Doc View Source

GetStatusAsync(CancellationToken)

Gets all the status of the orchestration instances.

Declaration

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

Parameters

Type	Name	Description
System.Threading.CancellationToken	cancellationToken	Cancellation token that can be used to cancel the status query operation.

Returns

Type	Description
System.Threading.Tasks.Task<System.Collections.Generic.IList<DurableOrchestrationStatus>>	Returns orchestration status for all instances.

Overrides

DurableOrchestrationClientBase.GetStatusAsync(CancellationToken)

| Improve this Doc View Source

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

Purge the orchestration history for instances that match the conditions.

Declaration

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

Parameters

Type	Name	Description
System.DateTime	createdTimeFrom	Start creation time for querying instances for purging.
System.Nullable<System.DateTime>	createdTimeTo	End creation time for querying instances for purging.
System.Collections.Generic.IEnumerable<DurableTask.Core.OrchestrationStatus>	runtimeStatus	List of runtime status for querying instances for purging. Only Completed, Terminated, or Failed will be processed.

Returns

Type	Description
System.Threading.Tasks.Task<PurgeHistoryResult>	Returns an instance of PurgeHistoryResult.

Overrides

DurableOrchestrationClientBase.PurgeInstanceHistoryAsync(DateTime, Nullable<DateTime>, IEnumerable<OrchestrationStatus>)

| Improve this Doc View Source

PurgeInstanceHistoryAsync(String)

Purge the history for a concrete instance.

Declaration

public override Task<PurgeHistoryResult> PurgeInstanceHistoryAsync(string instanceId)

Parameters

Type	Name	Description
System.String	instanceId	The ID of the orchestration instance to purge.

Returns

Type	Description
System.Threading.Tasks.Task<PurgeHistoryResult>	Returns an instance of PurgeHistoryResult.

Overrides

DurableOrchestrationClientBase.PurgeInstanceHistoryAsync(String)

| Improve this Doc View Source

RaiseEventAsync(String, String, Object)

Sends an event notification message to a waiting orchestration instance.

Declaration

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

Parameters

Type	Name	Description
System.String	instanceId	The ID of the orchestration instance that will handle the event.
System.String	eventName	The name of the event.
System.Object	eventData	The JSON-serializeable data associated with the event.

Returns

Type	Description
System.Threading.Tasks.Task	A task that completes when the event notification message has been enqueued.

Overrides

DurableOrchestrationClientBase.RaiseEventAsync(String, String, Object)

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.

| Improve this Doc View Source

RaiseEventAsync(String, String, String, Object, String)

Sends an event notification message to a waiting orchestration instance.

Declaration

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

Parameters

Type	Name	Description
System.String	taskHubName	The TaskHubName of the orchestration that will handle the event.
System.String	instanceId	The ID of the orchestration instance that will handle the event.
System.String	eventName	The name of the event.
System.Object	eventData	The JSON-serializeable data associated with the event.
System.String	connectionName	The name of the connection string associated with `taskHubName`.

Returns

Type	Description
System.Threading.Tasks.Task	A task that completes when the event notification message has been enqueued.

Overrides

DurableOrchestrationClientBase.RaiseEventAsync(String, String, String, Object, String)

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.

| Improve this Doc View Source

RewindAsync(String, String)

Rewinds the specified failed orchestration instance with a reason.

Declaration

public override Task RewindAsync(string instanceId, string reason)

Parameters

Type	Name	Description
System.String	instanceId	The ID of the orchestration instance to rewind.
System.String	reason	The reason for rewinding the orchestration instance.

Returns

Type	Description
System.Threading.Tasks.Task	A task that completes when the rewind message is enqueued.

Overrides

DurableOrchestrationClientBase.RewindAsync(String, String)

| Improve this Doc View Source

StartNewAsync(String, String, Object)

Starts a new instance of the specified orchestrator function.

Declaration

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

Parameters

Type	Name	Description
System.String	orchestratorFunctionName	The name of the orchestrator function to start.
System.String	instanceId	The ID to use for the new orchestration instance.
System.Object	input	JSON-serializeable input value for the orchestrator function.

Returns

Type	Description
System.Threading.Tasks.Task<System.String>	A task that completes when the orchestration is started.

Overrides

DurableOrchestrationClientBase.StartNewAsync(String, String, Object)

Remarks

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

Exceptions

Type	Condition
System.ArgumentException	The specified function does not exist, is disabled, or is not an orchestrator function.

| Improve this Doc View Source

TerminateAsync(String, String)

Terminates a running orchestration instance.

Declaration

public override Task TerminateAsync(string instanceId, string reason)

Parameters

Type	Name	Description
System.String	instanceId	The ID of the orchestration instance to terminate.
System.String	reason	The reason for terminating the orchestration instance.

Returns

Type	Description
System.Threading.Tasks.Task	A task that completes when the terminate message is enqueued.

Overrides

DurableOrchestrationClientBase.TerminateAsync(String, String)

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.

| Improve this Doc View Source

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.

Declaration

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

Parameters

Type	Name	Description
System.Net.Http.HttpRequestMessage	request	The HTTP request that triggered the current function.
System.String	instanceId	The unique ID of the instance to check.
System.TimeSpan	timeout	Total allowed timeout for output from the durable function. The default value is 10 seconds.
System.TimeSpan	retryInterval	The timeout between checks for output from the durable function. The default value is 1 second.

Returns

Type	Description
System.Threading.Tasks.Task<System.Net.Http.HttpResponseMessage>	An HTTP response which may include a 202 and location header or a 200 with the durable function output in the response body.

Overrides

DurableOrchestrationClientBase.WaitForCompletionOrCreateCheckStatusResponseAsync(HttpRequestMessage, String, TimeSpan, TimeSpan)

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.