Class WorkflowHandle

Namespace

Temporalio.Client

Assembly

Temporalio.dll

Workflow handle to perform actions on an individual workflow.

public record WorkflowHandle : IEquatable<WorkflowHandle>

Inheritance

object

WorkflowHandle

Implements

IEquatable<WorkflowHandle>

Derived

WorkflowHandle<TWorkflow>

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

WorkflowHandle(ITemporalClient, string, string?, string?, string?)

Workflow handle to perform actions on an individual workflow.

public WorkflowHandle(ITemporalClient Client, string Id, string? RunId = null, string? ResultRunId = null, string? FirstExecutionRunId = null)

Parameters

Client ITemporalClient

Client used for workflow handle calls.

Id string

Workflow ID.

RunId string

Run ID used for signals, queries, and updates if present to ensure a very specific run to call. This is only set when getting a workflow handle, not when starting a workflow.

ResultRunId string

Run ID used for get result calls to ensure getting a result starting from this run. This is set the same as a run ID when getting a workflow handle. When starting a workflow, this is set as the resulting run ID.

FirstExecutionRunId string

Run ID used for cancellation and termination to ensure they happen on a workflow starting with this run ID. This can be set when getting a workflow handle. When starting a workflow, this is set as the resulting run ID if no start signal was provided.

Properties

Client

Client used for workflow handle calls.

public ITemporalClient Client { get; init; }

Property Value

ITemporalClient

FirstExecutionRunId

Run ID used for cancellation and termination to ensure they happen on a workflow starting with this run ID. This can be set when getting a workflow handle. When starting a workflow, this is set as the resulting run ID if no start signal was provided.

public string? FirstExecutionRunId { get; init; }

Property Value

string

Id

Workflow ID.

public string Id { get; init; }

Property Value

string

ResultRunId

Run ID used for get result calls to ensure getting a result starting from this run. This is set the same as a run ID when getting a workflow handle. When starting a workflow, this is set as the resulting run ID.

public string? ResultRunId { get; init; }

Property Value

string

RunId

Run ID used for signals, queries, and updates if present to ensure a very specific run to call. This is only set when getting a workflow handle, not when starting a workflow.

public string? RunId { get; init; }

Property Value

string

Methods

CancelAsync(WorkflowCancelOptions?)

Request cancellation of this workflow.

public Task CancelAsync(WorkflowCancelOptions? options = null)

Parameters

options WorkflowCancelOptions

Cancellation options.

Returns

Task

Cancel accepted task.

Exceptions

RpcException

Server-side error.

DescribeAsync(WorkflowDescribeOptions?)

Get the current description of this workflow.

public Task<WorkflowExecutionDescription> DescribeAsync(WorkflowDescribeOptions? options = null)

Parameters

options WorkflowDescribeOptions

Extra options.

Returns

Task<WorkflowExecutionDescription>

Description for the workflow.

ExecuteUpdateAsync(string, IReadOnlyCollection<object?>, WorkflowUpdateOptions?)

Start an update and wait for it to complete. This is a shortcut for StartUpdateAsync(string, IReadOnlyCollection<object?>, WorkflowUpdateStartOptions) + GetResultAsync(RpcOptions?).

public Task ExecuteUpdateAsync(string update, IReadOnlyCollection<object?> args, WorkflowUpdateOptions? options = null)

Parameters

update string

Update name.

args IReadOnlyCollection<object>

Update args.

options WorkflowUpdateOptions

Extra options.

Returns

Task

Completed update task.

Remarks

WARNING: Workflow update is experimental and APIs may change. Currently this API will timeout on long update requests instead of properly polling for their completion.

ExecuteUpdateAsync<TWorkflow>(Expression<Func<TWorkflow, Task>>, WorkflowUpdateOptions?)

Start an update and wait for it to complete. This is a shortcut for StartUpdateAsync<TWorkflow>(Expression<Func<TWorkflow, Task>>, WorkflowUpdateStartOptions) + GetResultAsync(RpcOptions?).

public Task ExecuteUpdateAsync<TWorkflow>(Expression<Func<TWorkflow, Task>> updateCall, WorkflowUpdateOptions? options = null)

Parameters

updateCall Expression<Func<TWorkflow, Task>>

Invocation of workflow update method.

options WorkflowUpdateOptions

Extra options.

Returns

Task

Completed update task.

Type Parameters

TWorkflow

Workflow class type.

Remarks

WARNING: Workflow update is experimental and APIs may change. Currently this API will timeout on long update requests instead of properly polling for their completion.

ExecuteUpdateAsync<TUpdateResult>(string, IReadOnlyCollection<object?>, WorkflowUpdateOptions?)

Start an update and wait for it to complete. This is a shortcut for StartUpdateAsync<TUpdateResult>(string, IReadOnlyCollection<object?>, WorkflowUpdateStartOptions) + GetResultAsync(RpcOptions?).

public Task<TUpdateResult> ExecuteUpdateAsync<TUpdateResult>(string update, IReadOnlyCollection<object?> args, WorkflowUpdateOptions? options = null)

Parameters

update string

Update name.

args IReadOnlyCollection<object>

Update args.

options WorkflowUpdateOptions

Extra options.

Returns

Task<TUpdateResult>

Completed update task.

Type Parameters

TUpdateResult

Update result type.

Remarks

WARNING: Workflow update is experimental and APIs may change. Currently this API will timeout on long update requests instead of properly polling for their completion.

ExecuteUpdateAsync<TWorkflow, TUpdateResult>(Expression<Func<TWorkflow, Task<TUpdateResult>>>, WorkflowUpdateOptions?)

Start an update and wait for it to complete. This is a shortcut for StartUpdateAsync<TWorkflow, TUpdateResult>(Expression<Func<TWorkflow, Task<TUpdateResult>>>, WorkflowUpdateStartOptions) + GetResultAsync(RpcOptions?).

public Task<TUpdateResult> ExecuteUpdateAsync<TWorkflow, TUpdateResult>(Expression<Func<TWorkflow, Task<TUpdateResult>>> updateCall, WorkflowUpdateOptions? options = null)

Parameters

updateCall Expression<Func<TWorkflow, Task<TUpdateResult>>>

Invocation of workflow update method.

options WorkflowUpdateOptions

Extra options.

Returns

Task<TUpdateResult>

Completed update task.

Type Parameters

TWorkflow

Workflow class type.

TUpdateResult

Update result type.

Remarks

WARNING: Workflow update is experimental and APIs may change. Currently this API will timeout on long update requests instead of properly polling for their completion.

FetchHistoryAsync(WorkflowHistoryEventFetchOptions?)

Fetcgh history for the workflow.

public Task<WorkflowHistory> FetchHistoryAsync(WorkflowHistoryEventFetchOptions? options = null)

Parameters

options WorkflowHistoryEventFetchOptions

Options for history fetching.

Returns

Task<WorkflowHistory>

Fetched history.

FetchHistoryEventsAsync(WorkflowHistoryEventFetchOptions?)

Asynchronously iterate over history events.

public IAsyncEnumerable<HistoryEvent> FetchHistoryEventsAsync(WorkflowHistoryEventFetchOptions? options = null)

Parameters

options WorkflowHistoryEventFetchOptions

History event fetch options.

Returns

IAsyncEnumerable<HistoryEvent>

Async enumerable to iterate events for.

GetResultAsync(bool, RpcOptions?)

Get the result of a workflow disregarding its return (or not having a return type).

public Task GetResultAsync(bool followRuns = true, RpcOptions? rpcOptions = null)

Parameters

followRuns bool

Whether to follow runs until the latest workflow is reached.

rpcOptions RpcOptions

RPC options.

Returns

Task

Untyped task for waiting on result.

Exceptions

WorkflowFailedException

Exception thrown for unsuccessful workflow result. The cause can be CanceledFailureException, TerminatedFailureException, TimeoutFailureException, or any exception deserialized that was thrown in the workflow (usually an ApplicationFailureException).

RpcException

Server-side error.

GetResultAsync<TResult>(bool, RpcOptions?)

Get the result of a workflow, deserializing into the given return type.

public virtual Task<TResult> GetResultAsync<TResult>(bool followRuns = true, RpcOptions? rpcOptions = null)

Parameters

followRuns bool

Whether to follow runs until the latest workflow is reached.

rpcOptions RpcOptions

RPC options.

Returns

Task<TResult>

Result of the workflow.

Type Parameters

TResult

Return type to deserialize result into.

Exceptions

WorkflowFailedException

Exception thrown for unsuccessful workflow result. The cause can be CanceledFailureException, TerminatedFailureException, TimeoutFailureException, or any exception deserialized that was thrown in the workflow (usually an ApplicationFailureException).

RpcException

Server-side error.

GetUpdateHandle(string)

Get a workflow update handle for the given update ID on this workflow.

public WorkflowUpdateHandle GetUpdateHandle(string id)

Parameters

id string

ID of the update.

Returns

WorkflowUpdateHandle

Workflow update handle.

Remarks

WARNING: Workflow update is experimental and APIs may change.

GetUpdateHandle<TUpdateResult>(string)

Get a workflow update handle for the given update ID on this workflow.

public WorkflowUpdateHandle<TUpdateResult> GetUpdateHandle<TUpdateResult>(string id)

Parameters

id string

ID of the update.

Returns

WorkflowUpdateHandle<TUpdateResult>

Workflow update handle.

Type Parameters

TUpdateResult

Update result type.

Remarks

WARNING: Workflow update is experimental and APIs may change.

QueryAsync<TQueryResult>(string, IReadOnlyCollection<object?>, WorkflowQueryOptions?)

Query a workflow with the given WorkflowQuery attributed method.

public Task<TQueryResult> QueryAsync<TQueryResult>(string query, IReadOnlyCollection<object?> args, WorkflowQueryOptions? options = null)

Parameters

query string

Workflow query method.

args IReadOnlyCollection<object>

Query arguments.

options WorkflowQueryOptions

Extra options.

Returns

Task<TQueryResult>

Query result.

Type Parameters

TQueryResult

Query result type.

Exceptions

WorkflowQueryFailedException

Query failed on worker.

WorkflowQueryRejectedException

Query rejected by server based on rejection condition.

RpcException

Server-side error.

QueryAsync<TWorkflow, TQueryResult>(Expression<Func<TWorkflow, TQueryResult>>, WorkflowQueryOptions?)

Query a workflow via a lambda that calls a WorkflowQuery attributed method or accesses a WorkflowQuery attributed property.

public Task<TQueryResult> QueryAsync<TWorkflow, TQueryResult>(Expression<Func<TWorkflow, TQueryResult>> queryCall, WorkflowQueryOptions? options = null)

Parameters

queryCall Expression<Func<TWorkflow, TQueryResult>>

Invocation of a workflow query method or access of workflow query property.

options WorkflowQueryOptions

Extra options.

Returns

Task<TQueryResult>

Query result.

Type Parameters

TWorkflow

Workflow class type.

TQueryResult

Query result type.

Exceptions

WorkflowQueryFailedException

Query failed on worker.

WorkflowQueryRejectedException

Query rejected by server based on rejection condition.

RpcException

Server-side error.

SignalAsync(string, IReadOnlyCollection<object?>, WorkflowSignalOptions?)

Signal a workflow with the given signal name and args.

public Task SignalAsync(string signal, IReadOnlyCollection<object?> args, WorkflowSignalOptions? options = null)

Parameters

signal string

Signal name.

args IReadOnlyCollection<object>

Signal args.

options WorkflowSignalOptions

Extra options.

Returns

Task

Signal completion task. Means signal was accepted, but may not have been processed by the workflow yet.

Exceptions

RpcException

Server-side error.

SignalAsync<TWorkflow>(Expression<Func<TWorkflow, Task>>, WorkflowSignalOptions?)

Signal a workflow via a lambda call to a WorkflowSignal attributed method.

public Task SignalAsync<TWorkflow>(Expression<Func<TWorkflow, Task>> signalCall, WorkflowSignalOptions? options = null)

Parameters

signalCall Expression<Func<TWorkflow, Task>>

Invocation of a workflow signal method.

options WorkflowSignalOptions

Extra options.

Returns

Task

Signal completion task. Means signal was accepted, but may not have been processed by the workflow yet.

Type Parameters

TWorkflow

Workflow class type.

Exceptions

RpcException

Server-side error.

StartUpdateAsync(string, IReadOnlyCollection<object?>, WorkflowUpdateStartOptions)

Start a workflow update using its name.

public Task<WorkflowUpdateHandle> StartUpdateAsync(string update, IReadOnlyCollection<object?> args, WorkflowUpdateStartOptions options)

Parameters

update string

Name of the update.

args IReadOnlyCollection<object>

Arguments for the update.

options WorkflowUpdateStartOptions

Update options. Currently WaitForStage is required.

Returns

Task<WorkflowUpdateHandle>

Workflow update handle.

Remarks

WARNING: Workflow update is experimental and APIs may change.

StartUpdateAsync<TWorkflow>(Expression<Func<TWorkflow, Task>>, WorkflowUpdateStartOptions)

Start a workflow update via a call to a WorkflowUpdate attributed method.

public Task<WorkflowUpdateHandle> StartUpdateAsync<TWorkflow>(Expression<Func<TWorkflow, Task>> updateCall, WorkflowUpdateStartOptions options)

Parameters

updateCall Expression<Func<TWorkflow, Task>>

Invocation of workflow update method.

options WorkflowUpdateStartOptions

Update options. Currently WaitForStage is required.

Returns

Task<WorkflowUpdateHandle>

Workflow update handle.

Type Parameters

TWorkflow

Workflow class type.

Remarks

WARNING: Workflow update is experimental and APIs may change.

StartUpdateAsync<TUpdateResult>(string, IReadOnlyCollection<object?>, WorkflowUpdateStartOptions)

Start a workflow update using its name.

public Task<WorkflowUpdateHandle<TUpdateResult>> StartUpdateAsync<TUpdateResult>(string update, IReadOnlyCollection<object?> args, WorkflowUpdateStartOptions options)

Parameters

update string

Name of the update.

args IReadOnlyCollection<object>

Arguments for the update.

options WorkflowUpdateStartOptions

Update options. Currently WaitForStage is required.

Returns

Task<WorkflowUpdateHandle<TUpdateResult>>

Workflow update handle.

Type Parameters

TUpdateResult

Update result type.

Remarks

WARNING: Workflow update is experimental and APIs may change.

StartUpdateAsync<TWorkflow, TUpdateResult>(Expression<Func<TWorkflow, Task<TUpdateResult>>>, WorkflowUpdateStartOptions)

Start a workflow update via a call to a WorkflowUpdate attributed method.

public Task<WorkflowUpdateHandle<TUpdateResult>> StartUpdateAsync<TWorkflow, TUpdateResult>(Expression<Func<TWorkflow, Task<TUpdateResult>>> updateCall, WorkflowUpdateStartOptions options)

Parameters

updateCall Expression<Func<TWorkflow, Task<TUpdateResult>>>

Invocation of workflow update method.

options WorkflowUpdateStartOptions

Update options. Currently WaitForStage is required.

Returns

Task<WorkflowUpdateHandle<TUpdateResult>>

Workflow update handle.

Type Parameters

TWorkflow

Workflow class type.

TUpdateResult

Update result type.

Remarks

WARNING: Workflow update is experimental and APIs may change.

TerminateAsync(string?, WorkflowTerminateOptions?)

Terminate this workflow.

public Task TerminateAsync(string? reason = null, WorkflowTerminateOptions? options = null)

Parameters

reason string

Termination reason.

options WorkflowTerminateOptions

Termination options.

Returns

Task

Terminate completed task.

Exceptions

RpcException

Server-side error.