Class TemporalClient

Namespace

Temporalio.Client

Assembly

Temporalio.dll

Client for a Temporal namespace.

public class TemporalClient : ITemporalClient, IWorkerClient

Inheritance

object

TemporalClient

Implements

ITemporalClient

IWorkerClient

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

ITemporalClientExtensions.ExecuteUpdateWithStartWorkflowAsync(ITemporalClient, string, IReadOnlyCollection<object?>, WorkflowUpdateWithStartOptions)

ITemporalClientExtensions.ExecuteUpdateWithStartWorkflowAsync<TWorkflow>(ITemporalClient, Expression<Func<TWorkflow, Task>>, WorkflowUpdateWithStartOptions)

ITemporalClientExtensions.ExecuteUpdateWithStartWorkflowAsync<TUpdateResult>(ITemporalClient, string, IReadOnlyCollection<object?>, WorkflowUpdateWithStartOptions)

ITemporalClientExtensions.ExecuteUpdateWithStartWorkflowAsync<TWorkflow, TUpdateResult>(ITemporalClient, Expression<Func<TWorkflow, Task<TUpdateResult>>>, WorkflowUpdateWithStartOptions)

ITemporalClientExtensions.ExecuteWorkflowAsync(ITemporalClient, string, IReadOnlyCollection<object?>, WorkflowOptions)

ITemporalClientExtensions.ExecuteWorkflowAsync<TWorkflow>(ITemporalClient, Expression<Func<TWorkflow, Task>>, WorkflowOptions)

ITemporalClientExtensions.ExecuteWorkflowAsync<TResult>(ITemporalClient, string, IReadOnlyCollection<object?>, WorkflowOptions)

ITemporalClientExtensions.ExecuteWorkflowAsync<TWorkflow, TResult>(ITemporalClient, Expression<Func<TWorkflow, Task<TResult>>>, WorkflowOptions)

ITemporalClientExtensions.ListWorkflowHistoriesAsync(ITemporalClient, string, WorkflowListOptions?, WorkflowHistoryEventFetchOptions?)

Remarks

Clients are thread-safe and are encouraged to be reused to properly reuse the underlying connection.

Constructors

TemporalClient(ITemporalConnection, TemporalClientOptions)

Initializes a new instance of the TemporalClient class from an existing connection.

public TemporalClient(ITemporalConnection connection, TemporalClientOptions options)

Parameters

connection ITemporalConnection

Connection for this client.

options TemporalClientOptions

Options for this client.

Properties

BridgeClientProvider

Gets the bridge client provider for this client.

public IBridgeClientProvider BridgeClientProvider { get; }

Property Value

IBridgeClientProvider

Connection

Gets the connection associated with this client.

public ITemporalConnection Connection { get; }

Property Value

ITemporalConnection

OperatorService

Gets the raw gRPC operator service for self-hosted servers. Most users do not need this.

public OperatorService OperatorService { get; }

Property Value

OperatorService

Options

Gets the options used to create this client.

public TemporalClientOptions Options { get; }

Property Value

TemporalClientOptions

OutboundInterceptor

Gets the outbound interceptor in use.

public ClientOutboundInterceptor OutboundInterceptor { get; }

Property Value

ClientOutboundInterceptor

RetryRpcOptions

Gets a fixed set of retry-only RPC options.

protected static RpcOptions RetryRpcOptions { get; }

Property Value

RpcOptions

WorkflowService

Gets the raw gRPC workflow service. Most users do not need this.

public WorkflowService WorkflowService { get; }

Property Value

WorkflowService

Methods

ConnectAsync(TemporalClientConnectOptions)

Connect to a Temporal namespace.

public static Task<TemporalClient> ConnectAsync(TemporalClientConnectOptions options)

Parameters

options TemporalClientConnectOptions

Options for connecting.

Returns

Task<TemporalClient>

The connected client.

CountWorkflowsAsync(string, WorkflowCountOptions?)

Count workflows with the given query.

public Task<WorkflowExecutionCount> CountWorkflowsAsync(string query, WorkflowCountOptions? options = null)

Parameters

query string

Query to use for counting.

options WorkflowCountOptions

Options for the count call.

Returns

Task<WorkflowExecutionCount>

Count information for the workflows.

See Also

Visibility docs.

CreateLazy(TemporalClientConnectOptions)

Create a client to a Temporal namespace that does not connect until first call. Unconnected lazy clients cannot be used by workers. If an initial client connection fails, it will be retried next time it is needed.

public static TemporalClient CreateLazy(TemporalClientConnectOptions options)

Parameters

options TemporalClientConnectOptions

Options for connecting.

Returns

TemporalClient

The not-yet-connected client.

CreateScheduleAsync(string, Schedule, ScheduleOptions?)

Create a schedule and return its handle.

public Task<ScheduleHandle> CreateScheduleAsync(string scheduleId, Schedule schedule, ScheduleOptions? options = null)

Parameters

scheduleId string

Unique ID for the schedule.

schedule Schedule

Schedule to create.

options ScheduleOptions

Options for creating the schedule.

Returns

Task<ScheduleHandle>

Handle to the created schedule.

Remarks

This can throw ScheduleAlreadyRunningException if the ID already exists.

DefaultRetryOptions(RpcOptions?)

Get a default set of retry options given the optional options. This will not mutate the given options. This only sets retry if original options are not present or they have not already set a retry.

protected static RpcOptions DefaultRetryOptions(RpcOptions? origOptions)

Parameters

origOptions RpcOptions

Original options to use as a base for the return.

Returns

RpcOptions

Options with default retry set.

GetAsyncActivityHandle(byte[])

Get a handle to complete an activity asynchronously using its task token.

public AsyncActivityHandle GetAsyncActivityHandle(byte[] taskToken)

Parameters

taskToken byte[]

Task token for the activity.

Returns

AsyncActivityHandle

Async activity handle.

GetAsyncActivityHandle(string, string, string)

Get a handle to complete an activity asynchronously using its qualified identifiers.

public AsyncActivityHandle GetAsyncActivityHandle(string workflowId, string runId, string activityId)

Parameters

workflowId string

ID for the activity's workflow.

runId string

Run ID for the activity's workflow.

activityId string

ID for the activity.

Returns

AsyncActivityHandle

Async activity handle.

GetScheduleHandle(string)

Gets the schedule handle for the given ID.

public ScheduleHandle GetScheduleHandle(string scheduleId)

Parameters

scheduleId string

Schedule ID to get the handle for.

Returns

ScheduleHandle

Schedule handle.

GetWorkerBuildIdCompatibilityAsync(string, int, RpcOptions?)

Use to retrieve the sets of compatible Build IDs for the targeted Task Queue. For more on this feature, see https://docs.temporal.io/workers#worker-versioning .

public Task<WorkerBuildIdVersionSets?> GetWorkerBuildIdCompatibilityAsync(string taskQueue, int maxSets, RpcOptions? rpcOptions = null)

Parameters

taskQueue string

The Task Queue to target.

maxSets int

The maximum number of sets to return. If not specified, all sets will be returned.

rpcOptions RpcOptions

RPC options.

Returns

Task<WorkerBuildIdVersionSets>

The sets, if the Task Queue is versioned, otherwise null.

GetWorkerTaskReachabilityAsync(IReadOnlyCollection<string>, IReadOnlyCollection<string>, TaskReachability?, RpcOptions?)

Determine if some Build IDs for certain Task Queues could have tasks dispatched to them. For more on this feature, see https://docs.temporal.io/workers#worker-versioning .

public Task<WorkerTaskReachability> GetWorkerTaskReachabilityAsync(IReadOnlyCollection<string> buildIds, IReadOnlyCollection<string> taskQueues, TaskReachability? reachability = null, RpcOptions? rpcOptions = null)

Parameters

buildIds IReadOnlyCollection<string>

The Build IDs to query the reachability of. At least one must be specified.

taskQueues IReadOnlyCollection<string>

Task Queues to restrict the query to. If not specified, all Task Queues will be searched. When requesting a large number of task queues or all task queues associated with the given Build IDs in a namespace, all Task Queues will be listed in the response but some of them may not contain reachability information due to a server enforced limit. When reaching the limit, task queues that reachability information could not be retrieved for will be marked with a NotFetched entry in TaskQueueReachability. The caller may issue another call to get the reachability for those task queues.

reachability TaskReachability?

The kind of reachability this request is concerned with.

rpcOptions RpcOptions

RPC options.

Returns

Task<WorkerTaskReachability>

The reachability information.

GetWorkflowHandle(string, string?, string?)

Get a workflow handle for an existing workflow with unknown return type.

public WorkflowHandle GetWorkflowHandle(string id, string? runId = null, string? firstExecutionRunId = null)

Parameters

id string

ID of the workflow.

runId string

Run ID of the workflow or null for latest.

firstExecutionRunId string

Optional first execution ID used for cancellation and termination.

Returns

WorkflowHandle

Created workflow handle.

GetWorkflowHandle<TWorkflow>(string, string?, string?)

Get a workflow handle for an existing workflow with known type.

public WorkflowHandle<TWorkflow> GetWorkflowHandle<TWorkflow>(string id, string? runId = null, string? firstExecutionRunId = null)

Parameters

id string

ID of the workflow.

runId string

Run ID of the workflow or null for latest.

firstExecutionRunId string

Optional first execution ID used for cancellation and termination.

Returns

WorkflowHandle<TWorkflow>

Created workflow handle.

Type Parameters

TWorkflow

Workflow class type.

GetWorkflowHandle<TWorkflow, TResult>(string, string?, string?)

Get a workflow handle for an existing workflow with known type and return type.

public WorkflowHandle<TWorkflow, TResult> GetWorkflowHandle<TWorkflow, TResult>(string id, string? runId = null, string? firstExecutionRunId = null)

Parameters

id string

ID of the workflow.

runId string

Run ID of the workflow or null for latest.

firstExecutionRunId string

Optional first execution ID used for cancellation and termination.

Returns

WorkflowHandle<TWorkflow, TResult>

Created workflow handle.

Type Parameters

TWorkflow

Workflow class type.

TResult

Result type of the workflow.

ListSchedulesAsync(ScheduleListOptions?)

List schedules.

public IAsyncEnumerable<ScheduleListDescription> ListSchedulesAsync(ScheduleListOptions? options = null)

Parameters

options ScheduleListOptions

Options for the list call.

Returns

IAsyncEnumerable<ScheduleListDescription>

Async enumerator for the schedules.

ListWorkflowsAsync(string, WorkflowListOptions?)

List workflows with the given query.

public IAsyncEnumerable<WorkflowExecution> ListWorkflowsAsync(string query, WorkflowListOptions? options = null)

Parameters

query string

Query to use for filtering.

options WorkflowListOptions

Options for the list call.

Returns

IAsyncEnumerable<WorkflowExecution>

Async enumerator for the workflows.

See Also

Visibility docs.

StartUpdateWithStartWorkflowAsync(string, IReadOnlyCollection<object?>, WorkflowStartUpdateWithStartOptions)

Start an update using its name, possibly starting the workflow at the same time. Note that in some cases this call may fail but the workflow will still be started.

public Task<WorkflowUpdateHandle> StartUpdateWithStartWorkflowAsync(string update, IReadOnlyCollection<object?> args, WorkflowStartUpdateWithStartOptions options)

Parameters

update string

Name of the update.

args IReadOnlyCollection<object>

Arguments for the update.

options WorkflowStartUpdateWithStartOptions

Update options. Currently WaitForStage is required.

Returns

Task<WorkflowUpdateHandle>

Workflow update handle.

Remarks

WARNING: Workflow update with start is experimental and APIs may change.

Exceptions

ArgumentException

Invalid run call or options.

WorkflowAlreadyStartedException

Workflow was already started according to ID reuse and conflict policy.

RpcException

Server-side error.

StartUpdateWithStartWorkflowAsync<TWorkflow>(Expression<Func<TWorkflow, Task>>, WorkflowStartUpdateWithStartOptions)

Start an update via a call to a WorkflowUpdate attributed method, possibly starting the workflow at the same time. Note that in some cases this call may fail but the workflow will still be started.

public Task<WorkflowUpdateHandle> StartUpdateWithStartWorkflowAsync<TWorkflow>(Expression<Func<TWorkflow, Task>> updateCall, WorkflowStartUpdateWithStartOptions options)

Parameters

updateCall Expression<Func<TWorkflow, Task>>

Invocation of workflow update method.

options WorkflowStartUpdateWithStartOptions

Update options. Currently WaitForStage is required.

Returns

Task<WorkflowUpdateHandle>

Workflow update handle.

Type Parameters

TWorkflow

Workflow class type.

Remarks

WARNING: Workflow update with start is experimental and APIs may change.

Exceptions

ArgumentException

Invalid run call or options.

WorkflowAlreadyStartedException

Workflow was already started according to ID reuse and conflict policy.

RpcException

Server-side error.

StartUpdateWithStartWorkflowAsync<TUpdateResult>(string, IReadOnlyCollection<object?>, WorkflowStartUpdateWithStartOptions)

Start an update using its name, possibly starting the workflow at the same time. Note that in some cases this call may fail but the workflow will still be started.

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

Parameters

update string

Name of the update.

args IReadOnlyCollection<object>

Arguments for the update.

options WorkflowStartUpdateWithStartOptions

Update options. Currently WaitForStage is required.

Returns

Task<WorkflowUpdateHandle<TUpdateResult>>

Workflow update handle.

Type Parameters

TUpdateResult

Update result type.

Remarks

WARNING: Workflow update with start is experimental and APIs may change.

Exceptions

ArgumentException

Invalid run call or options.

WorkflowAlreadyStartedException

Workflow was already started according to ID reuse and conflict policy.

RpcException

Server-side error.

StartUpdateWithStartWorkflowAsync<TWorkflow, TUpdateResult>(Expression<Func<TWorkflow, Task<TUpdateResult>>>, WorkflowStartUpdateWithStartOptions)

Start an update via a call to a WorkflowUpdate attributed method, possibly starting the workflow at the same time. Note that in some cases this call may fail but the workflow will still be started.

public Task<WorkflowUpdateHandle<TUpdateResult>> StartUpdateWithStartWorkflowAsync<TWorkflow, TUpdateResult>(Expression<Func<TWorkflow, Task<TUpdateResult>>> updateCall, WorkflowStartUpdateWithStartOptions options)

Parameters

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

Invocation of workflow update method.

options WorkflowStartUpdateWithStartOptions

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 with start is experimental and APIs may change.

Exceptions

ArgumentException

Invalid run call or options.

WorkflowAlreadyStartedException

Workflow was already started according to ID reuse and conflict policy.

RpcException

Server-side error.

StartWorkflowAsync(string, IReadOnlyCollection<object?>, WorkflowOptions)

Start a workflow by name.

public Task<WorkflowHandle> StartWorkflowAsync(string workflow, IReadOnlyCollection<object?> args, WorkflowOptions options)

Parameters

workflow string

Workflow type name.

args IReadOnlyCollection<object>

Arguments for the workflow.

options WorkflowOptions

Start workflow options. ID and TaskQueue are required.

Returns

Task<WorkflowHandle>

Workflow handle for the started workflow.

Exceptions

ArgumentException

Invalid options.

WorkflowAlreadyStartedException

Workflow was already started according to ID reuse policy.

RpcException

Server-side error.

StartWorkflowAsync<TWorkflow>(Expression<Func<TWorkflow, Task>>, WorkflowOptions)

Start a workflow via lambda invoking the run method.

public Task<WorkflowHandle<TWorkflow>> StartWorkflowAsync<TWorkflow>(Expression<Func<TWorkflow, Task>> workflowRunCall, WorkflowOptions options)

Parameters

workflowRunCall Expression<Func<TWorkflow, Task>>

Invocation of workflow run method with no result.

options WorkflowOptions

Start workflow options. ID and TaskQueue are required.

Returns

Task<WorkflowHandle<TWorkflow>>

Workflow handle for the started workflow.

Type Parameters

TWorkflow

Workflow class type.

Exceptions

ArgumentException

Invalid run call or options.

WorkflowAlreadyStartedException

Workflow was already started according to ID reuse policy.

RpcException

Server-side error.

StartWorkflowAsync<TWorkflow, TResult>(Expression<Func<TWorkflow, Task<TResult>>>, WorkflowOptions)

Start a workflow via lambda invoking the run method.

public Task<WorkflowHandle<TWorkflow, TResult>> StartWorkflowAsync<TWorkflow, TResult>(Expression<Func<TWorkflow, Task<TResult>>> workflowRunCall, WorkflowOptions options)

Parameters

workflowRunCall Expression<Func<TWorkflow, Task<TResult>>>

Invocation of workflow run method with a result.

options WorkflowOptions

Start workflow options. ID and TaskQueue are required.

Returns

Task<WorkflowHandle<TWorkflow, TResult>>

Workflow handle for the started workflow.

Type Parameters

TWorkflow

Workflow class type.

TResult

Workflow result type.

Exceptions

ArgumentException

Invalid run call or options.

WorkflowAlreadyStartedException

Workflow was already started according to ID reuse policy.

RpcException

Server-side error.

UpdateWorkerBuildIdCompatibilityAsync(string, BuildIdOp, RpcOptions?)

Use to add new Build IDs or otherwise update the relative compatibility of Build IDs as defined on a specific task queue for the Worker Versioning feature. For more on this feature, see https://docs.temporal.io/workers#worker-versioning .

public Task UpdateWorkerBuildIdCompatibilityAsync(string taskQueue, BuildIdOp buildIdOp, RpcOptions? rpcOptions = null)

Parameters

taskQueue string

The Task Queue to target.

buildIdOp BuildIdOp

The operation to perform.

rpcOptions RpcOptions

RPC options.

Returns

Task

Completion task.