DurableOrchestrationContext class

Package:

durable-functions

Provides functionality for application code implementing an orchestration operation.

Properties

currentUtcDateTime	Gets the current date/time in a way that is safe for use by orchestrator functions. 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.
customStatus	Custom status for the orchestration
instanceId	The ID of the current orchestration instance. 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. 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	The ID of the parent orchestration of the current sub-orchestration instance. The value will be available only in sub-orchestrations. 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.
Task	Entry point for methods to handle collections of pending actions represented by Task instances. For use in parallelization operations.

Methods

callActivity(string, unknown)	Schedules an activity function named name for execution.
callActivityWithRetry(string, RetryOptions, unknown)	Schedules an activity function named name for execution with retry options.
callEntity(EntityId, string, unknown)	Calls an operation on an entity, passing an argument, and waits for it to complete.
callHttp(CallHttpOptions)	Schedules a durable HTTP call to the specified endpoint.
callSubOrchestrator(string, unknown, string)	Schedules an orchestration function named name for execution.
callSubOrchestratorWithRetry(string, RetryOptions, unknown, string)	Schedules an orchestrator function named name for execution with retry options.
continueAsNew(unknown)	Restarts the orchestration by clearing its history.
createTimer(Date)	Creates a durable timer that expires at a specified time. All durable timers created using this method must either expire or be cancelled using TimerTask.cancel() 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.
newGuid(string)	Creates a new GUID that is safe for replay within an orchestration or operation. 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(unknown)	Sets the JSON-serializable status of the current orchestrator function. 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. The serialized customStatusObject value will be made available to the aforementioned APIs after the next yield or return statement.
signalEntity(EntityId, string, unknown)	Send a signal operation to a Durable Entity, passing an argument, without waiting for a response. A fire-and-forget operation.
waitForExternalEvent(string)	Waits asynchronously for an event to be raised with the name name and returns the event data. External clients can raise events to a waiting orchestration instance using raiseEvent().

Property Details

currentUtcDateTime

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

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.

currentUtcDateTime: Date

Property Value

Date

customStatus

Custom status for the orchestration

customStatus: unknown

Property Value

unknown

instanceId

The ID of the current orchestration instance.

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.

instanceId: string

Property Value

string

isReplaying

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

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.

isReplaying: boolean

Property Value

boolean

parentInstanceId

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

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.

parentInstanceId: undefined | string

Property Value

undefined | string

Task

Entry point for methods to handle collections of pending actions represented by Task instances. For use in parallelization operations.

Task: { all: (tasks: Task[]) => Task, any: (tasks: Task[]) => Task }

Property Value

{ all: (tasks: Task[]) => Task, any: (tasks: Task[]) => Task }

Method Details

callActivity(string, unknown)

Schedules an activity function named name for execution.

function callActivity(name: string, input?: unknown): Task

Parameters

name

string

The name of the activity function to call.

input

unknown

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

Returns

Task

A Durable Task that completes when the called activity function completes or fails.

callActivityWithRetry(string, RetryOptions, unknown)

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

function callActivityWithRetry(name: string, retryOptions: RetryOptions, input?: unknown): Task

Parameters

name

string

The name of the activity function to call.

retryOptions

RetryOptions

The retry options for the activity function.

input

unknown

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

Returns

Task

callEntity(EntityId, string, unknown)

Calls an operation on an entity, passing an argument, and waits for it to complete.

function callEntity(entityId: EntityId, operationName: string, operationInput?: unknown): Task

Parameters

entityId

EntityId

The target entity.

operationName

string

The name of the operation.

operationInput

unknown

The input for the operation.

Returns

Task

callHttp(CallHttpOptions)

Schedules a durable HTTP call to the specified endpoint.

function callHttp(options: CallHttpOptions): Task

Parameters

options

CallHttpOptions

The HTTP options object

Returns

Task

callSubOrchestrator(string, unknown, string)

Schedules an orchestration function named name for execution.

function callSubOrchestrator(name: string, input?: unknown, instanceId?: string): Task

Parameters

name

string

The name of the orchestrator function to call.

input

unknown

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

instanceId

string

A unique ID to use for the sub-orchestration instance. If instanceId is not specified, the extension will generate an id in the format <calling orchestrator instance ID>:<#>

Returns

Task

callSubOrchestratorWithRetry(string, RetryOptions, unknown, string)

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

function callSubOrchestratorWithRetry(name: string, retryOptions: RetryOptions, input?: unknown, instanceId?: string): Task

Parameters

name

string

The name of the orchestrator function to call.

retryOptions

RetryOptions

The retry options for the orchestrator function.

input

unknown

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

instanceId

string

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

Returns

Task

continueAsNew(unknown)

Restarts the orchestration by clearing its history.

function continueAsNew(input: unknown)

Parameters

input

unknown

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

createTimer(Date)

Creates a durable timer that expires at a specified time.

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

function createTimer(fireAt: Date): TimerTask

Parameters

fireAt

Date

The time at which the timer should expire.

Returns

TimerTask

A TimerTask that completes when the durable timer expires.

getInput<T>()

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

function getInput<T>(): T

Returns

T

newGuid(string)

Creates a new GUID that is safe for replay within an orchestration or operation.

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.

function newGuid(input: string): string

Parameters

input

string

used to generate the unique GUID

Returns

string

setCustomStatus(unknown)

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

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.

The serialized customStatusObject value will be made available to the aforementioned APIs after the next yield or return statement.

function setCustomStatus(customStatusObject: unknown)

Parameters

customStatusObject

unknown

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

signalEntity(EntityId, string, unknown)

Send a signal operation to a Durable Entity, passing an argument, without waiting for a response. A fire-and-forget operation.

function signalEntity(entityId: EntityId, operationName: string, operationInput?: unknown)

Parameters

entityId

EntityId

ID of the target entity.

operationName

string

The name of the operation.

operationInput

unknown

(optional) input for the operation.

waitForExternalEvent(string)

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

External clients can raise events to a waiting orchestration instance using raiseEvent().

function waitForExternalEvent(name: string): Task

Parameters

name

string

The name of the external event to wait for.

Returns

Task

a Task that completes when an external event of the specified name is received