Class DurableOrchestrationContextBase

Namespace

Microsoft.Azure.WebJobs

Assembly

Microsoft.Azure.WebJobs.Extensions.DurableTask.dll

Abstract base class for DurableOrchestrationContext.

public abstract class DurableOrchestrationContextBase

Inheritance

object

DurableOrchestrationContextBase

Derived

DurableOrchestrationContext

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Constructors

DurableOrchestrationContextBase()

protected DurableOrchestrationContextBase()

Properties

CurrentUtcDateTime

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

public abstract 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.

InstanceId

Gets the instance ID of the currently executing orchestration.

public virtual string InstanceId { get; }

Property Value

string

The ID of the current orchestration instance.

Remarks

The instance ID is generated and fixed when the orchestrator function is scheduled. It can be either auto-generated, in which case it is formatted as a GUID, or it can be user-specified with any format.

IsReplaying

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

public virtual 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.

ParentInstanceId

Gets the parent instance ID of the currently executing sub-orchestration.

public virtual string ParentInstanceId { get; }

Property Value

string

The ID of the parent orchestration of the current sub-orchestration instance. The value will be available only in sub-orchestrations.

Remarks

The parent instance ID is generated and fixed when the parent orchestrator function is scheduled. It can be either auto-generated, in which case it is formatted as a GUID, or it can be user-specified with any format.

Methods

CallActivityAsync(string, object)

Schedules an activity function named functionName for execution.

public virtual Task CallActivityAsync(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

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

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.

CallActivityAsync<TResult>(string, object)

Schedules an activity function named functionName for execution.

public abstract 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(string, RetryOptions, object)

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

public virtual Task CallActivityWithRetryAsync(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

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

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.

CallActivityWithRetryAsync<TResult>(string, RetryOptions, object)

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

public abstract 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(string, object)

Schedules an orchestrator function named functionName for execution.

public virtual Task CallSubOrchestratorAsync(string functionName, object input)

Parameters

functionName string

The name of the orchestrator function to call.

input object

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

Returns

Task

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

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 sub-orchestrator function failed with an unhandled exception.

CallSubOrchestratorAsync(string, string, object)

Schedules an orchestrator function named functionName for execution.

public virtual Task CallSubOrchestratorAsync(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

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

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.

CallSubOrchestratorAsync<TResult>(string, object)

Schedules an orchestration function named functionName for execution.

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

Parameters

functionName string

The name of the orchestrator function to call.

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.

CallSubOrchestratorAsync<TResult>(string, string, object)

Schedules an orchestration function named functionName for execution.

public abstract 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(string, RetryOptions, object)

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

public virtual Task CallSubOrchestratorWithRetryAsync(string functionName, RetryOptions retryOptions, object input)

Parameters

functionName string

The name of the orchestrator function to call.

retryOptions RetryOptions

The retry option for the orchestrator function.

input object

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

Returns

Task

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

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.

CallSubOrchestratorWithRetryAsync(string, RetryOptions, string, object)

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

public virtual Task CallSubOrchestratorWithRetryAsync(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

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

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.

CallSubOrchestratorWithRetryAsync<TResult>(string, RetryOptions, object)

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

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

Parameters

functionName string

The name of the orchestrator function to call.

retryOptions RetryOptions

The retry option for the orchestrator function.

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.

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

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

public abstract 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 abstract 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(DateTime, CancellationToken)

Creates a durable timer that expires at a specified time.

public virtual Task CreateTimer(DateTime fireAt, CancellationToken cancelToken)

Parameters

fireAt DateTime

The time at which the timer should expire.

cancelToken CancellationToken

The CancellationToken to use for cancelling the timer.

Returns

Task

A durable task that completes when the durable timer expires.

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.

CreateTimer<T>(DateTime, T, CancellationToken)

Creates a durable timer that expires at a specified time.

public abstract 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 abstract 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 abstract 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 abstract 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(string)

Waits asynchronously for an event to be raised with name name.

public virtual Task WaitForExternalEvent(string name)

Parameters

name string

The name of the event to wait for.

Returns

Task

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

Remarks

External clients can raise events to a waiting orchestration instance using RaiseEventAsync(string, string, object) with the object parameter set to null.

WaitForExternalEvent(string, TimeSpan)

Waits asynchronously for an event to be raised with name name.

public virtual Task WaitForExternalEvent(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

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

Remarks

External clients can raise events to a waiting orchestration instance using RaiseEventAsync(string, string, object) with the object parameter set to null.

Exceptions

TimeoutException

The external event was not received before the timeout expired.

WaitForExternalEvent<T>(string)

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

public abstract 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 abstract 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 abstract 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).