Skip to main content

Temporal Client - .NET SDK feature guide

This page shows how to do the following:

Create a Temporal Client​

How to create a Temporal Client using the Temporal .NET SDK

A Temporal Client enables you to communicate with the Temporal Service. Communication with a Temporal Service includes, but isn't limited to, the following:

  • Starting Workflow Executions.
  • Sending Signals to Workflow Executions.
  • Sending Queries to Workflow Executions.
  • Getting the results of a Workflow Execution.
  • Providing an Activity Task Token.
caution

A Temporal Client cannot be initialized and used inside a Workflow. However, it is acceptable and common to use a Temporal Client inside an Activity to communicate with a Temporal Service.

When you are running a Temporal Service locally (such as the Temporal CLI), the number of connection options you must provide is minimal. Many SDKs default to the local host or IP address and port that Temporalite and Docker Compose serve (127.0.0.1:7233).

Use the ConnectAsync() static method on the Temporalio.Client.TemporalClient class to create and connect to a Temporal Client to the Temporal Service.

var client = await TemporalClient.ConnectAsync(new("localhost:7233"));

Connect to Temporal Cloud​

How to connect to Temporal Cloud using the Temporal .NET SDK

When you connect to Temporal Cloud, you need to provide additional connection and client options that include the following:

For more information about managing and generating client certificates for Temporal Cloud, see How to manage certificates in Temporal Cloud.

For more information about configuring TLS to secure inter- and intra-network communication for a Temporal Service, see Temporal Customization Samples.

Use the ConnectAsync() static method on the Temporalio.Client.TemporalClient class to create and connect to a Temporal Client to the Temporal Service. Specify the Tls property of the connection options to connect to a Temporal Service with TLS enabled.

var client = await TemporalClient.ConnectAsync(new("my-namespace.a1b2c.tmprl.cloud:7233")
{
    Namespace = "my-namespace.a1b2c",
    Tls = new()
    {
        ClientCert = await File.ReadAllBytesAsync("my-cert.pem"),
        ClientPrivateKey = await File.ReadAllBytesAsync("my-key.pem"),
    },
});

Start a Workflow​

How to start a Workflow using the Temporal .NET SDK

Workflow Execution semantics rely on several parameters—that is, to start a Workflow Execution you must supply a Task Queue that will be used for the Tasks (one that a Worker is polling), the Workflow Type, language-specific contextual data, and Workflow Function parameters.

A request to spawn a Workflow Execution causes the Temporal Service to create the first Event (WorkflowExecutionStarted) in the Workflow Execution Event History. The Temporal Service then creates the first Workflow Task, resulting in the first WorkflowTaskScheduled Event.

To start a Workflow Execution in .NET, use either the StartWorkflowAsync() or ExecuteWorkflowAsync() methods in the Client. You must set a Workflow Id and Task Queue in the WorkflowOptions given to the method.

var result = await client.ExecuteWorkflowAsync(
    (MyWorkflow wf) => wf.RunAsync(),
    new(id: "my-workflow-id", taskQueue: "my-task-queue");
Console.WriteLine("Result: {0}", result);

Get Workflow results​

How to get the results of a Workflow Execution using the Temporal .NET SDK

If the call to start a Workflow Execution is successful, you will gain access to the Workflow Execution's Run Id.

The Workflow Id, Run Id, and Namespace may be used to uniquely identify a Workflow Execution in the system and get its result.

It's possible to both block progress on the result (synchronous execution) or get the result at some other point in time (asynchronous execution).

In the Temporal Platform, it's also acceptable to use Queries as the preferred method for accessing the state and results of Workflow Executions.

Use StartWorkflowAsync() or GetWorkflowHandle() to return a Workflow handle. Then use the GetResultAsync() method to await on the result of the Workflow.

To get a handle for an existing Workflow by its Id, you can use GetWorkflowHandle().

Then use DescribeAsync() to get the current status of the Workflow. If the Workflow does not exist, this call fails.

var handle = client.GetWorkflowHandle("my-workflow-id");
var result = await client.GetResultAsync<string>();
Console.WriteLine("Result: {0}", result);