Class DurableOrchestrationContext

Namespace

Microsoft.Azure.WebJobs

Assembly

Microsoft.Azure.WebJobs.Extensions.DurableTask.dll

Parameter data for orchestration bindings that can be used to schedule function-based activities.

public sealed class DurableOrchestrationContext : DurableOrchestrationContextBase

Inheritance

object

DurableOrchestrationContextBase

DurableOrchestrationContext

Inherited Members

DurableOrchestrationContextBase.CallActivityAsync(string, object)

DurableOrchestrationContextBase.CallActivityWithRetryAsync(string, RetryOptions, object)

DurableOrchestrationContextBase.CallSubOrchestratorAsync(string, object)

DurableOrchestrationContextBase.CallSubOrchestratorAsync(string, string, object)

DurableOrchestrationContextBase.CallSubOrchestratorAsync<TResult>(string, object)

DurableOrchestrationContextBase.CallSubOrchestratorWithRetryAsync(string, RetryOptions, object)

DurableOrchestrationContextBase.CallSubOrchestratorWithRetryAsync(string, RetryOptions, string, object)

DurableOrchestrationContextBase.CallSubOrchestratorWithRetryAsync<TResult>(string, RetryOptions, object)

DurableOrchestrationContextBase.CreateTimer(DateTime, CancellationToken)

DurableOrchestrationContextBase.WaitForExternalEvent(string)

DurableOrchestrationContextBase.WaitForExternalEvent(string, TimeSpan)

DurableOrchestrationContextBase.InstanceId

DurableOrchestrationContextBase.ParentInstanceId

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Properties

CurrentUtcDateTime

Gets the current date/time in a way that is safe for use by orchestrator functions.

public override DateTime CurrentUtcDateTime { get; }

Property Value

DateTime

The orchestration's current date/time in UTC.

Remarks

This date/time value is derived from the orchestration history. It always returns the same value at specific points in the orchestrator function code, making it deterministic and safe for replay.

IsReplaying

Gets a value indicating whether the orchestrator function is currently replaying itself.

public override bool IsReplaying { get; }

Property Value

bool

true if the orchestrator function is currently being replayed; otherwise false.

Remarks

This property is useful when there is logic that needs to run only when the orchestrator function is not replaying. For example, certain types of application logging may become too noisy when duplicated as part of orchestrator function replay. The orchestrator code could check to see whether the function is being replayed and then issue the log statements when this value is false.

Methods

CallActivityAsync<TResult>(string, object)

Schedules an activity function named functionName for execution.

public override Task<TResult> CallActivityAsync<TResult>(string functionName, object input)

Parameters

functionName string

The name of the activity function to call.

input object

The JSON-serializeable input to pass to the activity function.

Returns

Task<TResult>

A durable task that completes when the called activity function completes or fails.

Type Parameters

TResult

The return type of the scheduled activity function.

Exceptions

ArgumentException

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

InvalidOperationException

The current thread is different than the thread which started the orchestrator execution.

FunctionFailedException

The activity function failed with an unhandled exception.

CallActivityWithRetryAsync<TResult>(string, RetryOptions, object)

Schedules an activity function named functionName for execution with retry options.

public override Task<TResult> CallActivityWithRetryAsync<TResult>(string functionName, RetryOptions retryOptions, object input)

Parameters

functionName string

The name of the activity function to call.

retryOptions RetryOptions

The retry option for the activity function.

input object

The JSON-serializeable input to pass to the activity function.

Returns

Task<TResult>

A durable task that completes when the called activity function completes or fails.

Type Parameters

TResult

The return type of the scheduled activity function.

Exceptions

ArgumentNullException

The retry option object is null.

ArgumentException

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

InvalidOperationException

The current thread is different than the thread which started the orchestrator execution.

FunctionFailedException

The activity function failed with an unhandled exception.

CallSubOrchestratorAsync<TResult>(string, string, object)

Schedules an orchestration function named functionName for execution.

public override Task<TResult> CallSubOrchestratorAsync<TResult>(string functionName, string instanceId, object input)

Parameters

functionName string

The name of the orchestrator function to call.

instanceId string

A unique ID to use for the sub-orchestration instance.

input object

The JSON-serializeable input to pass to the orchestrator function.

Returns

Task<TResult>

A durable task that completes when the called orchestrator function completes or fails.

Type Parameters

TResult

The return type of the scheduled orchestrator function.

Exceptions

ArgumentException

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

InvalidOperationException

The current thread is different than the thread which started the orchestrator execution.

FunctionFailedException

The activity function failed with an unhandled exception.

CallSubOrchestratorWithRetryAsync<TResult>(string, RetryOptions, string, object)

Schedules an orchestrator function named functionName for execution with retry options.

public override Task<TResult> CallSubOrchestratorWithRetryAsync<TResult>(string functionName, RetryOptions retryOptions, string instanceId, object input)

Parameters

functionName string

The name of the orchestrator function to call.

retryOptions RetryOptions

The retry option for the orchestrator function.

instanceId string

A unique ID to use for the sub-orchestration instance.

input object

The JSON-serializeable input to pass to the orchestrator function.

Returns

Task<TResult>

A durable task that completes when the called orchestrator function completes or fails.

Type Parameters

TResult

The return type of the scheduled orchestrator function.

Exceptions

ArgumentNullException

The retry option object is null.

ArgumentException

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

InvalidOperationException

The current thread is different than the thread which started the orchestrator execution.

FunctionFailedException

The activity function failed with an unhandled exception.

ContinueAsNew(object)

Restarts the orchestration by clearing its history.

public override void ContinueAsNew(object input)

Parameters

input object

The JSON-serializeable data to re-initialize the instance with.

Remarks

Large orchestration histories can consume a lot of memory and cause delays in instance load times. This method can be used to periodically truncate the stored history of an orchestration instance.

Note that any unprocessed external events will be discarded when an orchestration instance restarts itself using this method.

CreateTimer<T>(DateTime, T, CancellationToken)

Creates a durable timer that expires at a specified time.

public override Task<T> CreateTimer<T>(DateTime fireAt, T state, CancellationToken cancelToken)

Parameters

fireAt DateTime

The time at which the timer should expire.

state T

Any state to be preserved by the timer.

cancelToken CancellationToken

The CancellationToken to use for cancelling the timer.

Returns

Task<T>

A durable task that completes when the durable timer expires.

Type Parameters

T

The type of state.

Remarks

All durable timers created using this method must either expire or be cancelled using the cancelToken before the orchestrator function completes. Otherwise the underlying framework will keep the instance alive until the timer expires.

GetInput<T>()

Gets the input of the current orchestrator function as a deserialized value.

public override T GetInput<T>()

Returns

T

The deserialized input value.

Type Parameters

T

Any data contract type that matches the JSON input.

NewGuid()

Creates a new GUID that is safe for replay within an orchestrator function.

public override Guid NewGuid()

Returns

Guid

The new Guid value.

Remarks

The default implementation of this method creates a name-based UUID using the algorithm from RFC 4122 §4.3. The name input used to generate this value is a combination of the orchestration instance ID and an internally managed sequence number.

SetCustomStatus(object)

Sets the JSON-serializeable status of the current orchestrator function.

public override void SetCustomStatus(object customStatusObject)

Parameters

customStatusObject object

The JSON-serializeable value to use as the orchestrator function's custom status.

Remarks

The customStatusObject value is serialized to JSON and will be made available to the orchestration status query APIs. The serialized JSON value must not exceed 16 KB of UTF-16 encoded text.

WaitForExternalEvent<T>(string)

Waits asynchronously for an event to be raised with name name and returns the event data.

public override Task<T> WaitForExternalEvent<T>(string name)

Parameters

name string

The name of the event to wait for.

Returns

Task<T>

A durable task that completes when the external event is received.

Type Parameters

T

Any serializeable type that represents the JSON event payload.

Remarks

External clients can raise events to a waiting orchestration instance using RaiseEventAsync(string, string, object).

WaitForExternalEvent<T>(string, TimeSpan)

Waits asynchronously for an event to be raised with name name and returns the event data.

public override Task<T> WaitForExternalEvent<T>(string name, TimeSpan timeout)

Parameters

name string

The name of the event to wait for.

timeout TimeSpan

The duration after which to throw a TimeoutException.

Returns

Task<T>

A durable task that completes when the external event is received.

Type Parameters

T

Any serializeable type that represents the JSON event payload.

Remarks

External clients can raise events to a waiting orchestration instance using RaiseEventAsync(string, string, object).

Exceptions

TimeoutException

The external event was not received before the timeout expired.

WaitForExternalEvent<T>(string, TimeSpan, T)

Waits asynchronously for an event to be raised with name name and returns the event data.

public override Task<T> WaitForExternalEvent<T>(string name, TimeSpan timeout, T defaultValue)

Parameters

name string

The name of the event to wait for.

timeout TimeSpan

The duration after which to return the value in the defaultValue parameter.

defaultValue T

The default value to return if the timeout expires before the external event is received.

Returns

Task<T>

A durable task that completes when the external event is received, or returns the value of defaultValue if the timeout expires.

Type Parameters

T

Any serializeable type that represents the JSON event payload.

Remarks

External clients can raise events to a waiting orchestration instance using RaiseEventAsync(string, string, object).