Class DurableOrchestrationClient
Client for starting, querying, terminating, and raising events to orchestration instances.
Inherited Members
Namespace: Microsoft.Azure.WebJobs
Assembly: Microsoft.Azure.WebJobs.Extensions.DurableTask.dll
Syntax
public class DurableOrchestrationClient : DurableOrchestrationClientBase
Properties
| Improve this Doc View SourceTaskHubName
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
Methods
| Improve this Doc View SourceCreateCheckStatusResponse(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
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.
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
| Improve this Doc View SourceGetStatusAsync(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
| Improve this Doc View SourceGetStatusAsync(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
| Improve this Doc View SourceGetStatusAsync(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
| Improve this Doc View SourcePurgeInstanceHistoryAsync(DateTime, Nullable<DateTime>, IEnumerable<OrchestrationStatus>)
Purge the orchestration history for instances that match the conditions.
Declaration
public override Task 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 | Returns a task which completes when the purge has completed. |
Overrides
| Improve this Doc View SourcePurgeInstanceHistoryAsync(String)
Purge the history for a concrete instance.
Declaration
public override Task 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 | Returns a task which completes when the purge has completed. |
Overrides
| Improve this Doc View SourceRaiseEventAsync(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
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.
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 |
Returns
Type | Description |
---|---|
System.Threading.Tasks.Task | A task that completes when the event notification message has been enqueued. |
Overrides
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.
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
| Improve this Doc View SourceStartNewAsync(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
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. |
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
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, 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
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.