Skip to main content

Standalone Nexus Operations - .NET SDK

SUPPORT, STABILITY, and DEPENDENCY INFO

Temporal .NET SDK support for Standalone Nexus Operations is at Pre-release.

All APIs are experimental and may be subject to backwards-incompatible changes.

Standalone Nexus Operations let you run Nexus Operation Executions independently, without being orchestrated by a Workflow. Instead of calling a Nexus Operation from within a Workflow Definition using Workflow.CreateNexusWorkflowClient<TService>(), you execute a Standalone Nexus Operation directly from a Nexus Client created using ITemporalClient.CreateNexusClient<TService>().

Standalone Nexus Operations use the same Nexus Service contract, Operation handlers, and Worker setup as Workflow-driven Operations — only the execution path differs. See the Nexus feature guide for details on defining a Service contract, developing Operation handlers, and registering a Service in a Worker.

This page focuses on the client-side APIs that are unique to Standalone Nexus Operations:

Execute a Standalone Nexus Operation​

To execute a Standalone Nexus Operation, first create a NexusClient using ITemporalClient.CreateNexusClient<TService>(), bound to a specific Nexus Endpoint and Service. The endpoint must be pre-created on the server. Then call ExecuteNexusOperationAsync() from application code (for example, a starter program), not from inside a Workflow Definition.

ExecuteNexusOperationAsync is a shortcut that starts the Operation and waits for the result. If you need a handle to the Operation while it runs, call StartNexusOperationAsync instead — it returns a NexusOperationHandle that you can use to get the result, describe, cancel, or terminate the Operation. Id is required on NexusOperationOptions; ScheduleToCloseTimeout is optional and defaults to the maximum allowed by the Temporal server.

var nexusClient = client.CreateNexusClient<IHelloService>("my-nexus-endpoint");

var result = await nexusClient.ExecuteNexusOperationAsync(
    svc => svc.Echo(new("Nexus Echo 👋")),
    new("unique-operation-id")
    {
        ScheduleToCloseTimeout = TimeSpan.FromSeconds(10),
    });

You can also use the untyped overload that takes the Operation name as a string:

var nexusClient = client.CreateNexusClient("my-nexus-endpoint", "my-service-name");

var handle = await nexusClient.StartNexusOperationAsync<IHelloService.EchoOutput>(
    "Echo",
    new IHelloService.EchoInput("Nexus Echo 👋"),
    new("unique-operation-id")
    {
        ScheduleToCloseTimeout = TimeSpan.FromSeconds(10),
    });

Get the result of a Standalone Nexus Operation​

Use NexusOperationHandle<TResult>.GetResultAsync() to await the Operation's completion and retrieve its result. This works for both synchronous and asynchronous (Workflow-backed) Operations.

var output = await handle.GetResultAsync();
logger.LogInformation("Operation result: {Message}", output.Message);

If the Operation completed successfully, the result is deserialized into the handle's result type. If the Operation failed, a NexusOperationFailedException is thrown.

You can also recover a handle for an already-started Operation using GetNexusOperationHandle<TResult>() on the Temporal Client:

var handle = client.GetNexusOperationHandle<IHelloService.EchoOutput>("unique-operation-id");
var output = await handle.GetResultAsync();

List Standalone Nexus Operations​

Use ITemporalClient.ListNexusOperationsAsync() to list Standalone Nexus Operation Executions that match a List Filter query. The call returns an IAsyncEnumerable<NexusOperationExecution> that you can iterate with await foreach.

Note that ListNexusOperationsAsync is called on the base ITemporalClient, not on the NexusClient.

await foreach (var execution in client.ListNexusOperationsAsync(
    "Endpoint = 'my-nexus-endpoint'"))
{
    logger.LogInformation(
        "OperationID: {Id}, Operation: {Operation}, Status: {Status}",
        execution.OperationId, execution.Operation, execution.Status);
}

The query string accepts List Filter syntax. For example, "Endpoint = 'my-endpoint' AND Status = 'Running'".

Count Standalone Nexus Operations​

Use ITemporalClient.CountNexusOperationsAsync() to count Standalone Nexus Operation Executions that match a List Filter query.

Note that CountNexusOperationsAsync is called on the base ITemporalClient, not on the NexusClient.

var count = await client.CountNexusOperationsAsync(
    "Endpoint = 'my-nexus-endpoint'");
logger.LogInformation("Total Nexus operations: {Count}", count.Count);

Run Standalone Nexus Operations with Temporal Cloud​

Standalone Nexus Operations work against Temporal Cloud with the same code — only the client connection options change. For full details on connecting to Temporal Cloud, including Namespace creation, Nexus Endpoint setup, certificate generation, and authentication options, see Make Nexus calls across Namespaces in Temporal Cloud and Connect to Temporal Cloud.