ORLEANS0202: Await external operations in steps or after the last durable operation
| Property | Value |
|---|---|
| Severity | Warning |
| Category | Usage |
| Code fix | None |
A durable task body awaits an operation which isn’t durable, such as an HttpClient call, a database query, an ordinary grain call, or a Task-returning service method, at a point from which it still reaches a durable operation. Awaits of durable tasks, their configurations and handles, durable task APIs, Task.Yield, and helpers in the same compilation which perform durable operations aren’t external. The following invoice fetches an exchange rate before its first step:
public async DurableTask<decimal> InvoiceAsync(string customer, decimal amount, string currency){ // A replay calls the service again: it can return another rate, or fail where the first run succeeded. var rate = await rates.GetRateAsync(currency, DurableTask.Current.CancellationToken); var total = await Bill(amount * rate).WithId("bill"); await DurableTask.Delay(TimeSpan.FromDays(30)).WithId("due"); return total;}Rule description
Section titled “Rule description”A replay runs the code before the body’s last durable operation again, including each await in it. An external await then:
- Repeats its effects. A call which changes another system, such as sending a message or creating a record, runs once per replay.
- Observes another result. The replay receives another exchange rate and passes another amount to the recorded
billstep, which diverges and stalls the execution when the step is a call to another grain, and otherwise returns the recorded total for a different amount. - Fails where the first run succeeded. A replay which runs while the service is unavailable fails the task, although every recorded operation succeeded.
A step records its result, so a replay returns the result without awaiting the operation again.
For the rules and the replay model, see Replay-safety rules.
How to fix violations
Section titled “How to fix violations”Await the operation in DurableTask.Run. The delegate runs as a child step, its result is recorded, and the step receives a cancellation token which durable cancellation signals:
public async DurableTask<decimal> InvoiceWithRecordedRateAsync(string customer, decimal amount, string currency){ // The step records the rate, so a replay returns it without calling the service. var rate = await DurableTask.Run(ct => rates.GetRateAsync(currency, ct)).WithId("rate"); var total = await Bill(amount * rate).WithId("bill"); await DurableTask.Delay(TimeSpan.FromDays(30)).WithId("due"); return total;}Await the operation in a local step. An async DurableTask method of the same grain records its completion. Name it when it does more than one thing, or when other workflows reuse it:
public async DurableTask<decimal> InvoiceAndNotifyAsync(string customer, decimal amount){ var total = await Bill(amount).WithId("bill"); await NotifyAsync(customer, total).WithId("notify"); return total;}
// A local step: a replay returns its recorded completion without sending the email again.private async DurableTask NotifyAsync(string customer, decimal total) => await email.SendAsync(customer, $"Your invoice for {total:C}", DurableTask.Current.CancellationToken);Await the operation after the body’s last durable operation. The synchronous tail runs only in a run which completes the body:
public async DurableTask<decimal> InvoiceThenNotifyAsync(string customer, decimal amount){ var total = await Bill(amount).WithId("bill");
// No durable operation follows, so only a run which completes the task sends the email. A run which ends // before the result commits sends it again. await email.SendAsync(customer, $"Your invoice for {total:C}", DurableTask.Current.CancellationToken); return total;}A step which ends before its result commits runs again, and so does the tail of a run which ends before the task’s result commits. An external operation in a step or the tail therefore runs at least once, so give it an idempotency key derived from the task, such as $"{grainId}/{DurableTask.Current.Id}/{DurableTask.Current.Incarnation:N}", when it changes another system; see Idempotency in durable tasks and Integrate durable tasks with other systems. The incarnation distinguishes a later run of the same task identifier, whose operations are new.
When to suppress
Section titled “When to suppress”Suppress the diagnostic for a read which is idempotent, returns the same value in every run, and can’t fail during a replay, such as a read of immutable configuration.
