DurableClient class

Package:

durable-functions

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

Properties

taskHubName

The name of the task hub configured on this orchestration client instance.

Methods

createCheckStatusResponse(undefined | HttpRequest, string)	Creates an HTTP response that is useful for checking the status of the specified instance.
createHttpManagementPayload(string)	Creates an HttpManagementPayload object that contains instance management HTTP endpoints.
getStatus(string, GetStatusOptions)	Gets the status of the specified orchestration instance.
getStatusAll()	Gets the status of all orchestration instances.
getStatusBy(OrchestrationFilter)	Gets the status of all orchestration instances that match the specified conditions.
purgeInstanceHistory(string)	Purge the history for a specific orchestration instance.
purgeInstanceHistoryBy(OrchestrationFilter)	Purge the orchestration history for instances that match the conditions.
raiseEvent(string, string, unknown, TaskHubOptions)	Sends an event notification message to a waiting orchestration instance.
readEntityState<T>(EntityId, TaskHubOptions)	Tries to read the current state of an entity. Returns undefined if the entity does not exist, or if the JSON-serialized state of the entity is larger than 16KB.
rewind(string, string, TaskHubOptions)	Rewinds the specified failed orchestration instance with a reason.
signalEntity(EntityId, string, unknown, TaskHubOptions)	Signals an entity to perform an operation.
startNew(string, StartNewOptions)	Starts a new instance of the specified orchestrator function. If an orchestration instance with the specified ID already exists, the existing instance will be silently replaced by this new instance.
terminate(string, string)	Terminates a running orchestration instance.
waitForCompletionOrCreateCheckStatusResponse(HttpRequest, string, WaitForCompletionOptions)	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. If the orchestration does not complete within the specified timeout, then the HTTP response will be identical to that of createCheckStatusResponse().

Property Details

taskHubName

The name of the task hub configured on this orchestration client instance.

taskHubName: string

Property Value

string

Method Details

createCheckStatusResponse(undefined | HttpRequest, string)

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

function createCheckStatusResponse(request: undefined | HttpRequest, instanceId: string): HttpResponse

Parameters

request

undefined | HttpRequest

The HTTP request that triggered the current orchestration instance.

instanceId

string

The ID of the orchestration instance to check.

Returns

HttpResponse

An HTTP 202 response with a Location header and a payload containing instance management URLs.

createHttpManagementPayload(string)

Creates an HttpManagementPayload object that contains instance management HTTP endpoints.

function createHttpManagementPayload(instanceId: string): HttpManagementPayload

Parameters

instanceId

string

The ID of the orchestration instance to check.

Returns

HttpManagementPayload

getStatus(string, GetStatusOptions)

Gets the status of the specified orchestration instance.

function getStatus(instanceId: string, options?: GetStatusOptions): Promise<DurableOrchestrationStatus>

Parameters

instanceId

string

The ID of the orchestration instance to query.

options

GetStatusOptions

options object specifying extra configuration

Returns

Promise<DurableOrchestrationStatus>

getStatusAll()

Gets the status of all orchestration instances.

function getStatusAll(): Promise<DurableOrchestrationStatus[]>

Returns

Promise<DurableOrchestrationStatus[]>

getStatusBy(OrchestrationFilter)

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

function getStatusBy(filter: OrchestrationFilter): Promise<DurableOrchestrationStatus[]>

Parameters

filter

OrchestrationFilter

the OrchestrationFilter object specifying which orchestrations to retrieve.

Returns

Promise<DurableOrchestrationStatus[]>

purgeInstanceHistory(string)

Purge the history for a specific orchestration instance.

function purgeInstanceHistory(instanceId: string): Promise<PurgeHistoryResult>

Parameters

instanceId

string

The ID of the orchestration instance to purge.

Returns

Promise<PurgeHistoryResult>

purgeInstanceHistoryBy(OrchestrationFilter)

Purge the orchestration history for instances that match the conditions.

function purgeInstanceHistoryBy(filter: OrchestrationFilter): Promise<PurgeHistoryResult>

Parameters

filter

OrchestrationFilter

the OrchestrationFilter object specifying which orchestrations to purge.

Returns

Promise<PurgeHistoryResult>

raiseEvent(string, string, unknown, TaskHubOptions)

Sends an event notification message to a waiting orchestration instance.

function raiseEvent(instanceId: string, eventName: string, eventData: unknown, options?: TaskHubOptions): Promise<void>

Parameters

instanceId

string

The ID of the orchestration instance that will handle the event.

eventName

string

The name of the event.

eventData

unknown

The JSON-serializable data associated with the event.

options

TaskHubOptions

object providing TaskHubName of the orchestration instance and the name of its associated connection string

Returns

Promise<void>

A promise that resolves when the event notification message has been enqueued.

In order to handle the event, the target orchestration instance must be waiting for an event named eventName using waitForExternalEvent(string).

If the specified instance is not found or not running, this operation will have no effect.

readEntityState<T>(EntityId, TaskHubOptions)

Tries to read the current state of an entity. Returns undefined if the entity does not exist, or if the JSON-serialized state of the entity is larger than 16KB.

function readEntityState<T>(entityId: EntityId, options?: TaskHubOptions): Promise<EntityStateResponse<T>>

Parameters

entityId

EntityId

The target entity.

options

TaskHubOptions

optional object providing the TaskHubName of the target entity and the name of its associated connection string

Returns

Promise<EntityStateResponse<T>>

A response containing the current state of the entity.

rewind(string, string, TaskHubOptions)

Rewinds the specified failed orchestration instance with a reason.

function rewind(instanceId: string, reason: string, options?: TaskHubOptions): Promise<void>

Parameters

instanceId

string

The ID of the orchestration instance to rewind.

reason

string

The reason for rewinding the orchestration instance.

options

TaskHubOptions

object providing TaskHubName of the orchestration instance and the name of its associated connection string

Returns

Promise<void>

A promise that resolves when the rewind message is enqueued.

This feature is currently in preview.

signalEntity(EntityId, string, unknown, TaskHubOptions)

Signals an entity to perform an operation.

function signalEntity(entityId: EntityId, operationName?: string, operationContent?: unknown, options?: TaskHubOptions): Promise<void>

Parameters

entityId

EntityId

The target entity.

operationName

string

The name of the operation.

operationContent

unknown

The content for the operation.

options

TaskHubOptions

object providing TaskHubName of the entity instance and the name of its associated connection string

Returns

Promise<void>

startNew(string, StartNewOptions)

Starts a new instance of the specified orchestrator function.

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

function startNew(orchestratorFunctionName: string, options?: StartNewOptions): Promise<string>

Parameters

orchestratorFunctionName

string

The name of the orchestrator function to start.

options

StartNewOptions

optional object to control the scheduled orchestrator (e.g provide input, instanceID)

Returns

Promise<string>

The ID of the new orchestration instance.

terminate(string, string)

Terminates a running orchestration instance.

function terminate(instanceId: string, reason: string): Promise<void>

Parameters

instanceId

string

The ID of the orchestration instance to terminate.

reason

string

The reason for terminating the orchestration instance.

Returns

Promise<void>

A promise that resolves when the terminate message is enqueued.

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.

waitForCompletionOrCreateCheckStatusResponse(HttpRequest, string, WaitForCompletionOptions)

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.

If the orchestration does not complete within the specified timeout, then the HTTP response will be identical to that of createCheckStatusResponse().

function waitForCompletionOrCreateCheckStatusResponse(request: HttpRequest, instanceId: string, waitOptions?: WaitForCompletionOptions): Promise<HttpResponse>

Parameters

request

HttpRequest

The HTTP request that triggered the current function.

instanceId

string

The unique ID of the instance to check.

waitOptions

WaitForCompletionOptions

options object specifying the timeouts for how long to wait for output from the durable function and how often to check for output.

Returns

Promise<HttpResponse>