Skip to main content

Messages - Temporal .NET SDK feature guide

A Workflow can act like a stateful web service that receives messages: Queries, Signals, and Updates. The Workflow implementation defines these endpoints via handler methods that can react to incoming messages and return values. Temporal Clients use messages to read Workflow state and control execution. See Workflow message passing for a general overview of this topic. This page introduces these features for the Temporal .NET SDK.

Write message handlers​

info

The code that follows is part of a working solution.

Follow these guidelines when writing your message handlers:

  • Message handlers are defined as methods on the Workflow class, using one of the three attributes: WorkflowQueryAttribute, WorkflowSignalAttribute, and WorkflowUpdateAttribute.
  • The parameters and return values of handlers and the main Workflow function must be serializable.
  • Prefer data classes to multiple input parameters. Data class parameters allow you to add fields without changing the calling signature.

Query handlers​

A Query is a synchronous operation that retrieves state from a Workflow Execution. Define as a method:

[Workflow]
public class GreetingWorkflow
{
    public enum Language
    {
        Chinese,
        English,
        French,
        Spanish,
        Portuguese,
    }

    public record GetLanguagesInput(bool IncludeUnsupported);

    // ...

    [WorkflowQuery]
    public IList<Language> GetLanguages(GetLanguagesInput input) =>
        Enum.GetValues<Language>().
            Where(language => input.IncludeUnsupported || Greetings.ContainsKey(language)).
            ToList();

    // ...

Or as a property getter:

[Workflow]
public class GreetingWorkflow
{
    public enum Language
    {
        Chinese,
        English,
        French,
        Spanish,
        Portuguese,
    }

    // ...

    [WorkflowQuery]
    public Language CurrentLanguage { get; private set; } = Language.English;

    // ...
  • The Query attribute can accept arguments. See the API reference docs: WorkflowQueryAttribute.
  • A Query handler must not modify Workflow state.
  • You can't perform async blocking operations such as executing an Activity in a Query handler.

Signal handlers​

A Signal is an asynchronous message sent to a running Workflow Execution to change its state and control its flow:

[Workflow]
public class GreetingWorkflow
{
    public record ApproveInput(string Name);

    // ...

    [WorkflowSignal]
    public async Task ApproveAsync(ApproveInput input)
    {
        approvedForRelease = true;
        approverName = input.Name;
    }

    // ...

  • The Signal attribute can accept arguments. Refer to the API docs: WorkflowSignalAttribute.

  • The handler should not return a value. The response is sent immediately from the server, without waiting for the Workflow to process the Signal.

  • Signal (and Update) handlers can be asynchronous and blocking. This allows you to use Activities, Child Workflows, durable Workflow.DelayAsync Timers, Workflow.WaitConditionAsync conditions, and more. See Async handlers and Workflow message passing for guidelines on safely using async Signal and Update handlers.

Update handlers and validators​

An Update is a trackable synchronous request sent to a running Workflow Execution. It can change the Workflow state, control its flow, and return a result. The sender must wait until the Worker accepts or rejects the Update. The sender may wait further to receive a returned value or an exception if something goes wrong:

[Workflow]
public class GreetingWorkflow
{
    public enum Language
    {
        Chinese,
        English,
        French,
        Spanish,
        Portuguese,
    }

    // ...

    [WorkflowUpdateValidator(nameof(SetCurrentLanguageAsync))]
    public void ValidateLanguage(Language language)
    {
        if (!Greetings.ContainsKey(language))
        {
            throw new ApplicationFailureException($"{language} is not supported");
        }
    }

    [WorkflowUpdate]
    public async Task<Language> SetCurrentLanguageAsync(Language language)
    {
        var previousLanguage = CurrentLanguage;
        CurrentLanguage = language;
        return previousLanguage;
    }

    // ...

  • The Update attribute can take arguments (like, Name, Dynamic and UnfinishedPolicy) as described in the API reference docs for WorkflowUpdateAttribute.

  • About validators:

    • Use validators to reject an Update before it is written to History. Validators are always optional. If you don't need to reject Updates, you can skip them.
    • Define an Update validator with the WorkflowUpdateValidatorAttribute attribute. Use the Name argument when declaring the validator to connect it to its Update. The validator must be a void type and accept the same argument types as the handler.

  • Accepting and rejecting Updates with validators:

    • To reject an Update, raise an exception of any type in the validator.
    • Without a validator, Updates are always accepted.

  • Validators and Event History:

    • The WorkflowExecutionUpdateAccepted event is written into the History whether the acceptance was automatic or programmatic.
    • When a Validator raises an error, the Update is rejected, the Update is not run, and WorkflowExecutionUpdateAccepted won't be added to the Event History. The caller receives an "Update failed" error.

  • Use Workflow.CurrentUpdateInfo to obtain information about the current Update. This includes the Update ID, which can be useful for deduplication when using Continue-As-New: see Ensuring your messages are processed exactly once.

  • Update (and Signal) handlers can be asynchronous and blocking. This allows you to use Activities, Child Workflows, durable Workflow.DelayAsync Timers, Workflow.WaitConditionAsync conditions, and more. See Async handlers and Workflow message passing for guidelines on safely using async Update and Signal handlers.

Send messages​

To send Queries, Signals, or Updates you call methods on a WorkflowHandle object. To obtain the WorkflowStub, you can:

For example:

var client = await TemporalClient.ConnectAsync(new("localhost:7233"));
var workflowHandle = await client.StartWorkflowAsync(
    (GreetingWorkflow wf) => wf.RunAsync(),
    new(id: "message-passing-workflow-id", taskQueue: "message-passing-sample"));

To check the argument types required when sending messages -- and the return type for Queries and Updates -- refer to the corresponding handler method in the Workflow Definition.

Send a Query​

Call a Query method with WorkflowHandle.QueryAsync:

var supportedLanguages = await workflowHandle.QueryAsync(wf => wf.GetLanguages(new(false)));

  • Sending a Query doesn’t add events to a Workflow's Event History.

  • You can send Queries to closed Workflow Executions within a Namespace's Workflow retention period. This includes Workflows that have completed, failed, or timed out. Querying terminated Workflows is not safe and, therefore, not supported.

  • A Worker must be online and polling the Task Queue to process a Query.

Send a Signal​

You can send a Signal to a Workflow Execution from a Temporal Client or from another Workflow Execution. However, you can only send Signals to Workflow Executions that haven’t closed.

Send a Signal from a Client​

Use WorkflowHandle.SignalAsync from Client code to send a Signal:

await workflowHandle.SignalAsync(wf => wf.ApproveAsync(new("MyUser")));

  • The call returns when the server accepts the Signal; it does not wait for the Signal to be delivered to the Workflow Execution.

  • The WorkflowExecutionSignaled Event appears in the Workflow's Event History.

Send a Signal from a Workflow​

A Workflow can send a Signal to another Workflow, known as an External Signal. In this case you need to obtain a Workflow handle for the external Workflow. Use Workflow.GetExternalWorkflowHandle, passing a running Workflow Id, to retrieve a typed Workflow handle:

// ...

[Workflow]
public class WorkflowB
{
    [WorkflowRun]
    public async Task RunAsync()
    {
        var handle = Workflow.GetExternalWorkflowHandle<WorkflowA>("workflow-a");
        await handle.SignalAsync(wf => wf.YourSignalAsync("signal argument"));
    }

    // ...

When an External Signal is sent:

Signal-With-Start​

Signal-With-Start allows a Client to send a Signal to a Workflow Execution, starting the Execution if it is not already running. If there's a Workflow running with the given Workflow Id, it will be signaled. If there isn't, a new Workflow will be started and immediately signaled. To use Signal-With-Start, call SignalWithStart with a lambda expression invoking it:

var client = await TemporalClient.ConnectAsync(new("localhost:7233"));
var options = new WorkflowOptions(id: "your-signal-with-start-workflow", taskQueue: "signal-tq");
options.SignalWithStart((GreetingWorkflow wf) => wf.SubmitGreetingAsync("User Signal with Start"));
await client.StartWorkflowAsync((GreetingWorkflow wf) => wf.RunAsync(), options);

Send an Update​

An Update is a synchronous, blocking call that can change Workflow state, control its flow, and return a result.

A Client sending an Update must wait until the Server delivers the Update to a Worker. Workers must be available and responsive. If you need a response as soon as the Server receives the request, use a Signal instead. Also note that you can't send Updates to other Workflow Executions or perform an Update equivalent of Signal-With-Start.

  • WorkflowExecutionUpdateAccepted is added to the Event History when the Worker confirms that the Update passed validation.
  • WorkflowExecutionUpdateCompleted is added to the Event History when the Worker confirms that the Update has finished.

To send an Update to a Workflow Execution, you can:

  • Call the Update method with ExecuteUpdateAsync from the Client and wait for the Update to complete. This code fetches an Update result:

var previousLanguage = await workflowHandle.ExecuteUpdateAsync( wf => wf.SetCurrentLanguageAsync(GreetingWorkflow.Language.Chinese));


- 2. Use `StartUpdateAsync` to receive a handle as soon as the Update is accepted or rejected
  It returns an `UpdateHandle`

- Use this `UpdateHandle` later to fetch your results.
- Asynchronous Update handlers normally perform long-running async Activities.
- `StartUpdateAsync` only waits until the Worker has accepted or rejected the Update, not until all asynchronous operations are complete.

For example:

```csharp
// Wait until the update is accepted
var updateHandle = await workflowHandle.StartUpdateAsync(
    wf => wf.SetGreetingAsync(new HelloWorldInput("World")));
// Wait until the update is completed
var updateResult = await updateHandle.GetResultAsync();

For more details, see the "Async handlers" section.

NON-TYPE SAFE API CALLS

In real-world development, sometimes you may be unable to import Workflow Definition method signatures. When you don't have access to the Workflow Definition or it isn't written in .NET, you can still use non-type safe APIs and dynamic method invocation. Pass method names instead of method objects to:

Use non-type safe overloads of these APIs:

Message handler patterns​

This section covers common write operations, such as Signal and Update handlers. It doesn't apply to pure read operations, like Queries or Update Validators.

tip

For additional information, see Inject work into the main Workflow and Ensuring your messages are processed exactly once.

Add async handlers to use await​

Signal and Update handlers can be asynchronous as well as blocking. Using asynchronous calls allows you to await Activities, Child Workflows, Workflow.DelayAsync Timers, Workflow.WaitConditionAsync wait conditions, etc. This expands the possibilities for what can be done by a handler but it also means that handler executions and your main Workflow method are all running concurrently, with switching occurring between them at await calls.

It's essential to understand the things that could go wrong in order to use asynchronous handlers safely. See Workflow message passing for guidance on safe usage of async Signal and Update handlers, and the Controlling handler concurrency and Waiting for message handlers to finish sections below.

The following code executes an Activity that simulates a network call to a remote service:

public class MyActivities
{
    private static readonly Dictionary<Language, string> Greetings = new()
    {
        [Language.Arabic] = "مرحبا بالعالم",
        [Language.Chinese] = "你好，世界",
        [Language.English] = "Hello, world",
        [Language.French] = "Bonjour, monde",
        [Language.Hindi] = "नमस्ते दुनिया",
        [Language.Spanish] = "Hola mundo",
    };

    [Activity]
    public async Task<string?> CallGreetingServiceAsync(Language language)
    {
        // Pretend that we are calling a remove service
        await Task.Delay(200);
        return Greetings.TryGetValue(language, out var value) ? value : null;
    }
}

The following code modifies a WorkflowUpdate for asynchronous use of the preceding Activity:

[Workflow]
public class GreetingWorkflow
{
    private readonly Mutex mutex = new();

    // ...

    [WorkflowUpdate]
    public async Task<Language> SetLanguageAsync(Language language)
    {
        // 👉 Use a mutex here to ensure that multiple calls to SetLanguageAsync are processed in order.
        await mutex.WaitOneAsync();
        try
        {
            if (!greetings.ContainsKey(language))
            {
                var greeting = Workflow.ExecuteActivityAsync(
                    (MyActivities acts) => acts.CallGreetingServiceAsync(language),
                    new() { StartToCloseTimeout = TimeSpan.FromSeconds(10) });
                if (greeting == null)
                {
                    // 👉 An update validator cannot be async, so cannot be used to check that the remote
                    // CallGreetingServiceAsync supports the requested language. Throwing ApplicationFailureException
                    // will fail the Update, but the WorkflowExecutionUpdateAccepted event will still be
                    // added to history.
                    throw new ApplicationFailureException(
                        $"Greeting service does not support {language}");
                }
                greetings[language] = greeting;
            }
            var previousLanguage = CurrentLanguage;
            CurrentLanguage = language;
            return previousLanguage;
        }
        finally
        {
            mutex.ReleaseMutex();
        }
    }
}

After updating the code for asynchronous calls, your Update handler can schedule an Activity and await the result. Although an async Signal handler can initiate similar network tasks, using an Update handler allows the Client to receive a result or error once the Activity completes. This lets your Client track the progress of asynchronous work performed by the Update's Activities, Child Workflows, etc.

Add wait conditions to block​

Sometimes, async Signal or Update handlers need to meet certain conditions before they should continue. Using a wait condition with Workflow.WaitConditionAsync sets a function that prevents the code from proceeding until the condition returns true. This is an important feature that helps you control your handler logic.

Here are two important use cases for Workflow.await:

  • Waiting in a handler until it is appropriate to continue.
  • Waiting in the main Workflow until all active handlers have finished.

The condition state you're waiting for can be updated by and reflect any part of the Workflow code. This includes the main Workflow method, other handlers, or child coroutines spawned by the main Workflow method, and so forth.

Use wait conditions in handlers​

Sometimes, async Signal or Update handlers need to meet certain conditions before they should continue. Using a wait condition with Workflow.WaitConditionAsync sets a function that prevents the code from proceeding until the condition returns true. This is an important feature that helps you control your handler logic.

Consider a ReadyForUpdateToExecute method that runs before your Update handler executes. The Workflow.WaitConditionAsync call waits until your condition is met:

    [WorkflowUpdate]
    public async Task<string> MyUpdateAsync(UpdateInput updateInput)
    {
        await Workflow.WaitConditionAsync(() => ReadyForUpdateToExecute(updateInput));
        // ...
    }

Remember: Handlers can execute before the main Workflow method starts.

Ensure your handlers finish before the Workflow completes​

Workflow wait conditions can ensure your handler completes before a Workflow finishes. When your Workflow uses async Signal or Update handlers, your main Workflow method can return or continue-as-new while a handler is still waiting on an async task, such as an Activity result. The Workflow completing may interrupt the handler before it finishes crucial work and cause Client errors when trying retrieve Update results. Use Workflow.AllHandlersFinished to address this problem and allow your Workflow to end smoothly:

[Workflow]
public class MyWorkflow
{
    [WorkflowRun]
    public async Task<string> RunAsync()
    {
        // ...
        await Workflow.WaitConditionAsync(() => Workflow.AllHandlersFinished);
        return "workflow-result";
    }

    // ...

By default, your Worker will log a warning when you allow a Workflow Execution to finish with unfinished handler executions. You can silence these warnings on a per-handler basis by passing the UnfinishedPolicy argument to the WorkflowSignalAttribute / WorkflowUpdateAttribute decorator:

    [WorkflowUpdate(UnfinishedPolicy = HandlerUnfinishedPolicy.Abandon)]
    public async Task MyUpdateAsync()
    {
        // ...

See Finishing handlers before the Workflow completes for more information.

Use locks to prevent concurrent handler execution​

Concurrent processes can interact in unpredictable ways. Incorrectly written concurrent message-passing code may not work correctly when multiple handler instances run simultaneously. Here's an example of a pathological case:

[Workflow]
public class MyWorkflow
{
    // ...

    [WorkflowSignal]
    public async Task BadHandlerAsync()
    {
        var data = await Workflow.ExecuteActivityAsync(
            (MyActivities acts) => acts.FetchDataAsync(),
            new() { StartToCloseTimeout = TimeSpan.FromSeconds(10) });
        this.x = data.X;
        // 🐛🐛 Bug!! If multiple instances of this handler are executing concurrently, then
        // there may be times when the Workflow has this.x from one Activity execution and this.y from another.
        await Workflow.DelayAsync(1000);
        this.y = data.Y;
    }
}

Coordinating access with Workflows.Mutex, a mutual exclusion lock, corrects this code. Locking makes sure that only one handler instance can execute a specific section of code at any given time:

[Workflow]
public class MyWorkflow
{
    private readonly Mutex mutex = new();

    // ...

    [WorkflowSignal]
    public async Task SafeHandlerAsync()
    {
        await mutex.WaitOneAsync();
        try
        {
            var data = await Workflow.ExecuteActivityAsync(
                (MyActivities acts) => acts.FetchDataAsync(),
                new() { StartToCloseTimeout = TimeSpan.FromSeconds(10) });
            this.x = data.X;
            // ✅ OK: the scheduler may switch now to a different handler execution, or to the main workflow
            // method, but no other execution of this handler can run until this execution finishes.
            await Workflow.DelayAsync(1000);
            this.y = data.Y;
        }
        finally
        {
            mutex.ReleaseMutex();
        }
    }
}

For additional concurrency options, you can use Workflows.Semaphore. Semaphores manage access to shared resources and coordinate the order in which threads or processes execute.

Message handler troubleshooting​

When sending a Signal, Update, or Query to a Workflow, your Client might encounter the following errors:

See Exceptions in message handlers for a non–.NET-specific discussion of this topic.

Problems when sending a Signal​

When using Signal, the only exception that will result from your requests during its execution is RpcException. All handlers may experience additional exceptions during the initial (pre-Worker) part of a handler request lifecycle.

For Queries and Updates, the Client waits for a response from the Worker. If an issue occurs during the handler Execution by the Worker, the Client may receive an exception.

Problems when sending an Update​

When working with Updates, you may encounter these errors:

  • No Workflow Workers are polling the Task Queue: Your request will be retried by the SDK Client indefinitely. Use a CancellationToken in your RPC options to cancel the Update. This raises a Temporalio.Exceptions.WorkflowUpdateRpcTimeoutOrCanceledException exception .

  • Update failed: You'll receive a Temporalio.Exceptions.WorkflowUpdateFailedException exception. There are two ways this can happen:

    • The Update was rejected by an Update validator defined in the Workflow alongside the Update handler.

    • The Update failed after having been accepted.

    Update failures are like Workflow failures. Issues that cause a Workflow failure in the main method also cause Update failures in the Update handler. These might include:

  • The handler caused the Workflow Task to fail: A Workflow Task Failure causes the server to retry Workflow Tasks indefinitely. What happens to your Update request depends on its stage:

    • If the request hasn't been accepted by the server, you receive a FAILED_PRECONDITION Temporalio.Exceptions.RpcException exception.
    • If the request has been accepted, it is durable. Once the Workflow is healthy again after a code deploy, use an UpdateHandle to fetch the Update result.

  • The Workflow finished while the Update handler execution was in progress: You'll receive a Temporalio.Exceptions.RpcException "workflow execution already completed".

    This will happen if the Workflow finished while the Update handler execution was in progress, for example because

Problems when sending a Query​

When working with Queries, you may encounter these errors:

  • There is no Workflow Worker polling the Task Queue: You'll receive a Temporalio.Exceptions.RpcException on which the Code is a RpcException.StatusCode with a status of FailedPrecondition.

  • Query failed: You'll receive a Temporalio.Exceptions.WorkflowQueryFailedException exception if something goes wrong during a Query. Any exception in a Query handler will trigger this error. This differs from Signal and Update requests, where exceptions can lead to Workflow Task Failure instead.

  • The handler caused the Workflow Task to fail. This would happen, for example, if the Query handler blocks the thread for too long without yielding.

Dynamic Handler​

Temporal supports Dynamic Queries, Signals, Updates, Workflows, and Activities. These are unnamed handlers that are invoked if no other statically defined handler with the given name exists.

Dynamic Handlers provide flexibility to handle cases where the names of Queries, Signals, Updates, Workflows, or Activities, aren't known at run time.

caution

Dynamic Handlers should be used judiciously as a fallback mechanism rather than the primary approach. Overusing them can lead to maintainability and debugging issues down the line.

Instead, Signals, Queries, Workflows, or Activities should be defined statically whenever possible, with clear names that indicate their purpose. Use static definitions as the primary way of structuring your Workflows.

Reserve Dynamic Handlers for cases where the handler names are not known at compile time and need to be looked up dynamically at runtime. They are meant to handle edge cases and act as a catch-all, not as the main way of invoking logic.

Set a Dynamic Query​

A Dynamic Query in Temporal is a Query method that is invoked dynamically at runtime if no other Query with the same name is registered. A Query can be made dynamic by setting Dynamic to true on the [WorkflowQuery] attribute. Only one Dynamic Query can be present on a Workflow.

The Query Handler parameters must accept a string name and Temporalio.Converters.IRawValue[] for the arguments. The Workflow.PayloadConverter property is used to convert an IRawValue object to the desired type using extension methods in the Temporalio.Converters Namespace.

[WorkflowQuery(Dynamic = true)]
public string DynamicQueryAsync(string queryName, IRawValue[] args)
{
    var input = Workflow.PayloadConverter.ToValue<MyStatusParam>(args.Single());
    return statuses[input.Type];
}

Set a Dynamic Signal​

A Dynamic Signal in Temporal is a Signal that is invoked dynamically at runtime if no other Signal with the same input is registered. A Signal can be made dynamic by setting Dynamic to true on the [WorkflowSignal] attribute. Only one Dynamic Signal can be present on a Workflow.

The Signal Handler parameters must accept a string name and Temporalio.Converters.IRawValue[] for the arguments. The Workflow.PayloadConverter property is used to convert an IRawValue object to the desired type using extension methods in the Temporalio.Converters Namespace.

[WorkflowSignal(Dynamic = true)]
public async Task DynamicSignalAsync(string signalName, IRawValue[] args)
{
    var input = Workflow.PayloadConverter.ToValue<DoSomethingParam>(args.Single());
    pendingThings.Add(input);
}

Set a Dynamic Update​

A Dynamic Update in Temporal is an Update that is invoked dynamically at runtime if no other Update with the same input is registered. An Update can be made dynamic by setting Dynamic to true on the [WorkflowUpdate] attribute. Only one Dynamic Update can be present on a Workflow.

The Update Handler parameters must accept a string name and Temporalio.Converters.IRawValue[] for the arguments. The Workflow.PayloadConverter property is used to convert an IRawValue object to the desired type using extension methods in the Temporalio.Converters Namespace.

[WorkflowUpdate(Dynamic = true)]
public async Task<string> DynamicUpdateAsync(string updateName, IRawValue[] args)
{
    var input = Workflow.PayloadConverter.ToValue<DoSomethingParam>(args.Single());
    pendingThings.Add(input);
    return statuses[input.Type];
}