Messaging
Messaging, in the Microsoft.Orleans.Durable package, gives each grain a durable inbox and
outbox built on Orleans Journaling and Durable Jobs. A grain commits received
messages, business changes, and outgoing messages in its own journal, so handler
effects and pending sends survive activation loss.
Microsoft.Orleans.Durableis a pre-release alpha package which targets .NET 11 (net11.0). Evaluate it with an explicit upgrade, rollback, backup, and recovery plan because its APIs and journal formats can change before stabilization.
This page describes the message, commit, and execution model. Continue with:
- Idempotency and hierarchical operation keys for application command identities, retained completion facts, and external effects.
- Practical recipes for inventory reservation, payment-provider reconciliation, out-of-order projections, and notification fan-out.
- Operations and throughput for configuration, diagnostics, dead-letter replay, upgrades, and sequential messaging benchmarks.
- Durable tasks for multi-step workflows written as sequential code, which run over the same inbox and outbox.
Message and routing model
Section titled “Message and routing model”Each Envelope carries an application-supplied
MessageId, which wraps a
HierarchicalKey, a required byte[] payload,
an optional ordinal subject, optional named byte-array headers, and an optional
DeliverAt time. Empty payloads are valid.
An OutboxMessage pairs the envelope with its destination (GrainId). Delivery passes an InboxMessage carrying the same envelope to that grain’s inbox. The envelope’s ID identifies the logical command. Reply destinations, domain versions, and other business data travel in the application payload.
Sending and delivery validate each message before any durable change:
- The message ID is set and is at most 1,024 UTF-8 bytes in its canonical form.
- The payload is non-null.
- A supplied subject is nonempty and at most 256 UTF-8 bytes.
- Header keys are nonempty, well-formed UTF-16 strings, and header values are non-null.
- An outgoing message has a destination.
Retries and reconstructed submissions reuse the same ID, subject, destination, body,
and DeliverAt time.
Register handlers
Section titled “Register handlers”Inject IInbox into the grain and add handlers with
Register. An
IInboxHandler has two members:
CanHandle receives the
InboxMessage and selects the messages the handler
accepts, and HandleAsync processes one message.
The inbox dispatches each message to the first registered handler whose CanHandle
returns true, in registration order. The selected handler stages the message’s
terminal outcome from HandleAsync.
Typed handlers register through the Register extension methods. Each overload takes a MessageType<T> binding and a delegate, matches the binding’s subject ordinally, decodes the payload, and passes the decoded body and the handler context to the delegate:
| Delegate | Use |
|---|---|
Action<T, IInboxHandlerContext> | Synchronous handling. |
Func<T, IInboxHandlerContext, CancellationToken, ValueTask> | Asynchronous preparation before the final update. |
Action<T, TArg, IInboxHandlerContext> | Synchronous handling with an explicit argument, for static delegates. |
Func<T, TArg, IInboxHandlerContext, CancellationToken, ValueTask> | Asynchronous handling with an explicit argument, for static delegates. |
The overloads that take a TArg argument let a static lambda receive the grain or
other state without a closure allocation. Synchronous typed handlers observe the
processing cancellation token immediately before the delegate runs. Register
returns the inbox, so registrations chain.
Handlers can be registered at any time. Register them during grain construction or in OnActivateAsync, so they’re available when the inbox starts processing recovered messages. Messages already in the inbox wait until a handler is registered.
A receiver with no registered handlers answers delivery with
DeliveryResult.HandlerNotFound, and the sender retries the
message. When handlers are registered and none accepts the message, processing
reports a handler failure for that message, which follows the retry and dead-letter
policy.
Encode ordinary application values
Section titled “Encode ordinary application values”Message bodies are ordinary Orleans-serializable types:
[GenerateSerializer]public sealed record Notify( [property: Id(0)] string? Text, [property: Id(2)] GrainId? ResponseDestination = null);
[GenerateSerializer]public sealed record NotificationReceived( [property: Id(0)] string Text, [property: Id(1)] MessageId CommandId);A MessageType<T> binds a subject to the Serializer<T> for its body type. Decode verifies the envelope’s subject before reading its payload. Define an application’s bindings in one class which constructs them from the Serializer service, register that class as a singleton, and inject it into grains:
public sealed class Messages(Serializer serializer){ public MessageType<Notify> Notify { get; } = new("notifications.notify.v1", serializer); public MessageType<NotificationReceived> NotificationReceived { get; } = new("notifications.received.v1", serializer); public MessageType<ReserveStock> ReserveStock { get; } = new("inventory.reserve.v1", serializer); public MessageType<Restock> Restock { get; } = new("inventory.restock.v1", serializer); public MessageType<ReservationResult> ReservationResult { get; } = new("inventory.reservation-result.v1", serializer); public MessageType<ChargePayment> ChargePayment { get; } = new("payments.charge.v1", serializer); public MessageType<PaymentResult> PaymentResult { get; } = new("payments.result.v1", serializer); public MessageType<StockSnapshot> StockSnapshot { get; } = new("inventory.snapshot.v1", serializer); public MessageType<Shipment> Shipment { get; } = new("shipments.manifest.v1", serializer); public MessageType<SubmitCheckout> SubmitCheckout { get; } = new("checkout.submit.v1", serializer); public MessageType<GracePeriodElapsed> GracePeriodElapsed { get; } = new("checkout.grace-period-elapsed.v1", serializer);}AddMessageType registers a single
binding as a keyed singleton for FromKeyedServices injection.
Subjects use exact ordinal spelling, for example inventory.reserve.v1. Separate
subjects can bind the same CLR type. When a subject uses a base type, define the
supported polymorphism in the serialization contract.
Send takes a binding, a stable command ID, a destination, and a body. The destination is a GrainId or an IAddressable grain reference. The helper encodes the body and stages the outgoing message. Serialization completes before staging, so a serialization error leaves the outbox unchanged. A batch overload encodes every message before staging any, so an encoding failure stages nothing, then stages the messages in order.
SendReply takes a binding, the handler
context, a destination, and a result body. It derives the reply ID by appending the
literal result segment to the received command ID. The application supplies the
reply destination, typically from a field of the request body such as
ResponseDestination.
Create builds an outgoing message from a command ID, a destination, and a body. Use it to deliver a message explicitly through its ToInboxMessage view.
Use payload and header arrays
Section titled “Use payload and header arrays”An envelope is a readonly value holding its payload array, subject, and optional header dictionary. Struct assignment shares those objects; RPC copying and deserialization produce independent copies. Prepare the payload and headers before sending and keep their contents unchanged afterward: outbox state, delivery retries, handler contexts, and diagnostics read the same arrays.
For a raw protocol, assign the encoded payload and the headers the protocol uses. Receivers look up headers by ordinal key and decode them with the agreed encoding. This example encodes a shipment payload and two application headers with ordinary serializers:
internal static class ShipmentEnvelope{ internal static OutboxMessage Create( Serializer serializer, MessageId commandId, GrainId sender, GrainId receiver, Shipment shipment, Guid traceId) { var envelope = new Envelope { MessageId = commandId, Subject = "shipments.manifest.v1", Payload = serializer.SerializeToArray(shipment), Headers = new() { ["sender"] = serializer.SerializeToArray(sender), ["trace-id"] = serializer.SerializeToArray(traceId) } }; return new OutboxMessage { Envelope = envelope, ReceiverId = receiver }; }
internal static Guid ReadTrace(InboxMessage message, Serializer<Guid> serializer) { if (message.Envelope.Headers is not { } headers || !headers.TryGetValue("trace-id", out var bytes)) { throw new InvalidOperationException("The shipment requires its trace-id header."); } return serializer.Deserialize(bytes); }}Headers travel with the payload through persistence, retries, recovery, and dead-letter inspection. A repeated submission of a pending or staged command keeps the first submission’s headers. Place command-defining parameters in the payload and subject, and use headers for accompanying context such as trace identifiers.
Carry related values in one message
Section titled “Carry related values in one message”Use a serializable record for a composite message. Fields can contain other
application records, collections, and binary data. This shipment carries a
reservation request and a byte[] manifest in one body:
[GenerateSerializer]public sealed record Shipment( [property: Id(0)] ReserveStock Reservation, [property: Id(1)] byte[] Manifest);
public interface IShipmentSenderGrain : IGrainWithStringKey{ Task SendAsync(MessageId commandId, GrainId receiver, Shipment shipment);}
public sealed class ShipmentSenderGrain( IOutbox outbox, IDurableStateManager state, Messages messages) : Grain, IShipmentSenderGrain{ public async Task SendAsync(MessageId commandId, GrainId receiver, Shipment shipment) { outbox.Send(messages.Shipment, commandId, receiver, shipment); await state.WriteStateAsync(); }}The typed Send helper serializes the entire Shipment, and a typed handler
receives the decoded record. For serialization outside messaging, use
SerializeToArray and
Deserialize.
Schedule processing
Section titled “Schedule processing”Set DeliverAt to hold a message in the receiving
inbox until a time on the Durable Jobs clock. The single-message typed
Send helpers and
Create accept an optional deliverAt
argument. Compute deliverAt from the Durable Jobs clock, which a grain injects as
the keyed TimeProvider service named
DurableJobTimeProviderNames.DurableJobs. The outbox delivers the message
immediately; the receiver accepts, deduplicates, and journals it, and its handler
runs once the message is due. A grain that schedules a message for itself commits
its acceptance in the sending journal write. Scheduled messages stay in the
receiver’s journal and snapshots until they are processed, and count toward
MaxCapacity from their acceptance until they complete.
Keep payloads in application state
Section titled “Keep payloads in application state”By default, a sent payload is journaled by the outbox and a received payload by the inbox. When the application’s own journaled state already holds a payload, an outbox source or an inbox sink keeps that state as the only journaled copy:
-
An IOutboxMessageSource, registered with Register, provides messages sent by ID with Send. The outbox journals the message ID and delivery state and applies every delivery guarantee of an ordinary message. It materializes the message with TryGetMessage to validate the send and before each delivery attempt; the source returns the same message while it provides it, and returns
falsefor a message that isn’t its own. The first source that returns the message owns it.- Withdraw. Withdraw removes a pending message,
for example one the application timed out. Stage it in the same journal write in
which the source releases its payload. The outbox makes no further attempt and
doesn’t call
OnRetired; an attempt already in flight can still deliver the message. - Retire. When the message retires, the outbox calls
OnRetired while it stages the
removal, so the source’s release, application terminal outcome, and follow-up
work commit in the same journal write. The
OutboxMessageRetirement is one of three cases:
OutboxMessageRetirement.Deliveredwhen the receiver accepted the message or reported it as a duplicate;OutboxMessageRetirement.Rejectedwhen an inbox sink at the receiver rejected it durably, with the sink’sReasonand application-definedCode; andOutboxMessageRetirement.DeadLetteredwhen the outbox dead-lettered it after its retry timeout, a source failure, or anExpiredanswer, with itsReason.DeadLetteredleaves earlier receiver acceptance unknown.OutboxMessageRetirementandDeliveryResultare C# unions whose cases are classes, so match them with type and property patterns, such asretirement is OutboxMessageRetirement.Rejected { Code: var code }. An outbox dead letter receives its own copy of the materialized message first, so the source can release its payload inOnRetired. Stage a self-addressed follow-up message there to run application recovery work through the inbox’s durable wake-up and handler path. A failure before commit recovers the pending outbox entry and invokes the callback again; a committed retirement recovers the outcome and follow-up together. A callback exception fails the activation so its uncommitted changes are discarded. Perform external I/O in the follow-up handler’s preparation phase. - Fail. After the send, when the owning source throws, returns an invalid
message, or returns
falsefor its message, the outbox dead-letters only that entry and retires it asDeadLetteredin the same journal write; the grain keeps processing its other messages. That dead letter carries only the message ID, with an empty payload and a default receiver, and its reason records the failure. A recovered entry which no registered source provides is dead-lettered the same way, without an owner to notify.
During
Send, a source exception or an invalid message propagates to the caller and nothing is staged. Sending a pending ID again coalesces; an ID pending as an ordinary message throws InvalidOperationException. A source-provided message can’t be addressed to the sending grain. - Withdraw. Withdraw removes a pending message,
for example one the application timed out. Stage it in the same journal write in
which the source releases its payload. The outbox makes no further attempt and
doesn’t call
-
An IInboxMessageSink, registered with Register, receives each deduplicated message before the inbox accepts it, including scheduled messages and messages a grain sends to itself. A sink that takes the message returns
truefrom TryAccept and sets itsoutDeliveryResult to one of these cases; a sink that declines returnsfalseand sets it todefault:DeliveryResult.Accepted.Instance: the sink staged the message’s effects. The inbox journals only the processed record in the same write and returns the result once the write completes.DeliveryResult.Duplicate.Instance: the sink already holds the message.DeliveryResult.Backpressured.Instance: the sink is at capacity, so the sender retries later.DeadLettered: created withnew DeliveryResult.DeadLettered(reason, code), the only permanent rejection. The inbox records the message as processed with the reason and the optional application-defined code, such asorders/duplicate-order, and returns them to the sender, whose source receives them in anOutboxMessageRetirement.Rejectedretirement. A duplicate of the message receives the same rejection.
A sink exception, or any other result, leaves the outcome unknown: the inbox stages nothing and fails the delivery, so the sender’s outbox retries it until
OutboxRetryTimeout. A message a grain sends to itself fails itsSendwhen a sink throws or reportsBackpressured. A sink-owned message occupies no inbox capacity, and the sink honors itsDeliverAttime. Messages that every sink declines follow the ordinary inbox path. -
A wake-up callback, registered with RegisterWakeup, reports durable work that a component such as a sink holds in the grain’s journal. The callback returns how soon a deactivated grain must wake to resume the work, or
nullwhen none is pending. The messaging wake-up then reactivates the grain until the work clears, and the component resumes its work on activation.
Register sources, sinks, and wake-up callbacks during construction or activation setup, before journal recovery. A recovered source-provided message fails the activation when no source is registered. The inbox deduplicates a tracked identity before offering it to a sink, and expires an untracked message sent at or before its durable admission floor before any sink effects.
Commit and delivery guarantees
Section titled “Commit and delivery guarantees”- Send stages an outgoing message in the grain’s journaled state. The next journal write persists it together with the grain’s other staged changes. The outbox delivers a message only after that write completes.
- A message addressed to the sending grain never enters the outbox.
Sendstages its acceptance in the grain’s own inbox, so the same journal write persists the acceptance with the grain’s other staged changes, and the inbox processes the message only after that write completes. When the write fails before it captures the staged changes, such as when scheduling its wake-up fails, the acceptance stays staged with them and a retried write persists it. A failed storage write discards it with the rest of the staged changes, and the next activation recovers the committed state. - Repeating a send with the same ID and an equivalent message (same destination,
subject, payload, and
DeliverAttime) keeps the original message. Reusing the ID with different content throws InvalidOperationException. - The receiving inbox journals an accepted message, or the processed record of a
message an inbox sink accepts, before returning
DeliveryResult.Accepted, and processes it only after that acceptance is durable. - A handler’s business changes, outgoing messages, and inbox completion are staged together and persist in one journal write.
- Transport is at-least-once. If the sender loses its activation after the
receiver accepts a message and before the outbox records the delivery, the outbox
sends the message again using its original
SentAt. Effects apply once per logical send through retained completion records and a durable admission floor; a handler can execute more than once for the same message, so its preparation must tolerate repetition. - The receiver deduplicates by exact
MessageId. A repeat of a pending message returnsDeliveryResult.Duplicatewhen its subject, payload, andDeliverAttime match, and fails when they differ. A repeat of a completed message returnsDuplicatewhile the completion record is retained, or the originalDeadLetteredreason and code when an inbox sink rejected it. Both records keep theSentAtthe inbox accepted, whatever a repeat carries. Once the record is compacted, an untracked message sent at or before the durable floor receivesExpired, whose earlier acceptance outcome is unknown. - A message with DeliverAt is delivered and
accepted immediately, then processed once its acceptance is durable and the
Durable Jobs clock reaches
DeliverAt. A message the grain sends to itself is accepted in the sending write, so a grain can schedule durable work for itself together with its other journaled changes in one write. - Delivery is unordered. Applications that need ordering carry sequence numbers and apply messages in application-defined order.
Execution model
Section titled “Execution model”Each activation runs one messaging pump, which starts when activation completes. The pump processes ready inbox messages, then delivers ready outbox messages, and repeats while work remains. All pump work, including handler code, runs on the activation’s single-threaded scheduler. A live activation processes due work as soon as it is durable: journal write completions and finished deliveries signal the pump directly.
The inbox processes up to InboxBatchSize durable, due messages per pass, one at a time, then writes the journal once for the batch. The outbox keeps up to OutboxBatchSize delivery attempts in flight for the grain. Each attempt completes on its own and frees its slot for the next due message, so a slow or unresponsive receiver holds one slot and messages to other receivers continue. The outbox never holds messages addressed to the grain itself; a handler that sends one stages its acceptance with the batch’s write, and a later pass processes it.
Deliveries to the grain, through
DeliverAsync, interleave with the
grain’s other requests. A delivery validates the envelope, recognizes recorded
outcomes, and validates any newly stored send time before staging the message’s
acceptance synchronously, then waits for that journal write; concurrent deliveries
share journal writes. Inbox message sinks run synchronously within the delivery, so a
sink can run while a request is suspended at an await, as handlers can.
One durable job per grain, named orleans.messaging.pump, is crash insurance for
work the live pump performs. It wakes the grain while either queue or a registered
wake-up callback holds work which the activation can perform, at the earliest retry time,
DeliverAt time, or callback delay. Work which is already due resumes within about
a second of recovery. A journal write schedules a job only when no tracked job is due
within that slack, so a busy grain performs no Durable Jobs operation per write. When
activation fails, Durable Jobs retries the pump job indefinitely with capped backoff
on its clock; AddMessaging configures this retry policy for the pump job only.
Every activation re-arms the wake-up at the real due time from recovered state, so
committed work always keeps a wake-up.
Grain state is authoritative. Each pass derives its work from the journaled
messages, their retry times, and their DeliverAt times, so early, late, and
duplicate wake-ups are harmless.
The pump keeps the activation alive while a pass processes queued messages and while
outbox deliveries are in flight. Messages that become due later, at their DeliverAt
or retry time, leave the activation collectable; the durable job reactivates the grain
when they are due.
Interleaving
Section titled “Interleaving”Handlers run as activation work outside grain requests, so handler code interleaves
with grain calls at each await, on reentrant and non-reentrant grains alike.
Deliveries and inbox message sinks interleave the same way. Design handlers, sinks,
and grain methods to stay correct under that interleaving. Stateless worker grains
are rejected at activation.
To apply a handler’s commit phase exclusively on a non-reentrant grain, run it as a grain request with RunRequestAsync. The request waits for the current grain call to finish and excludes other calls while it runs:
public interface IStockLevelGrain : IGrainWithStringKey{ ValueTask<int> GetStock();}
public sealed class StockLevelGrain( IInbox inbox, Messages messages, [FromKeyedServices("stock-level")] IDurableValue<int> stock) : Grain, IStockLevelGrain{ public override Task OnActivateAsync(CancellationToken cancellationToken) { inbox.Register(messages.Restock, HandleRestockAsync); return base.OnActivateAsync(cancellationToken); }
public ValueTask<int> GetStock() => new(stock.Value);
private async ValueTask HandleRestockAsync(Restock message, IInboxHandlerContext context, CancellationToken cancellationToken) { // The commit runs as a grain request, so it waits for the current grain call and excludes others. await this.RunRequestAsync(_ => { stock.Value = checked(stock.Value + message.Quantity); context.Complete(); return Task.CompletedTask; }, cancellationToken); }}Handler outcomes
Section titled “Handler outcomes”The handler context, IInboxHandlerContext, exposes the received Message and two terminal operations:
- Complete stages the message’s removal and its completion record.
- Fail moves the message to the inbox dead letters with a nonblank reason and records its ID as processed.
Each successful handler calls exactly one of them. Repeated Complete() calls, or
repeated Fail calls with the same reason, coalesce. The context belongs to one
processing attempt and rejects use after the handler returns.
The terminal operation stages its changes immediately, and any journal write on the activation can capture them. Structure each handler in two phases:
- Prepare. Perform asynchronous I/O, validation, decoding, and fallible computation using local values. Observe cancellation before the final phase.
- Commit. In one synchronous block, with no
awaitafter the first change, send typed outgoing messages, apply the business update, callComplete()orFail(reason), and return.
This ordering keeps business changes, outgoing messages, and completion in the same journal write. The inbox persists the batch after its handlers return.
Route each failure by whether it can ever succeed:
- Business rejection. Send a typed rejection reply and call
Complete(). - Permanently invalid input, such as a command which can never become valid.
Call
Fail(reason), or send a typed rejection reply and callComplete()when the protocol has a reply. The message leaves the inbox at once and frees its capacity slot. - Transient fault, such as an unavailable dependency. Throw. The grain deactivates,
and after recovery the message retries with backoff until
InboxRetryTimeout, keeping its capacity slot meanwhile.
The following outcomes cover the remaining cases:
| Handler outcome | Result |
|---|---|
| Exception, or return without a terminal operation | The outcome is unknown. The grain deactivates, recovery from the journal discards the attempt’s staged changes and charges the attempt, and the message retries with backoff until InboxRetryTimeout, then moves to the dead letters. |
| Exception after a terminal operation | The exception is logged and the staged outcome persists. |
| Conflicting terminal operations | Contract error: messaging stops and the grain deactivates. |
An attempt’s staged changes share the grain’s pending journal write, so every unknown outcome fails the activation rather than committing a retry alongside them.
Backpressure, retries, and dead letters
Section titled “Backpressure, retries, and dead letters”For deliveries, a tracked message receives its recorded answer whatever its SentAt,
including after a receiver clock rollback. An untracked message at or below the
admission floor receives Expired. Above the floor, the inbox bounds an untracked
message’s SentAt by its Durable Jobs time plus DeduplicationWindow; equality is
admitted, and a later time throws ArgumentOutOfRangeException,
with no staged change or sink offer. The outbox treats the
exception as a failed attempt, preserving the original SentAt and retrying until
SentAt + OutboxRetryTimeout; retry exhaustion retires the send as DeadLettered
with an unknown earlier outcome. Messages staged directly in the sending grain’s
own inbox use the local staging time, or the first time above the admission floor
after a backward clock jump, and follow the local-send path.
When the inbox holds
MaxCapacity pending
messages, it answers new messages with Backpressured, and the sender retries them
later. Every pending message, including a scheduled message waiting for its
DeliverAt time, counts toward this limit from its acceptance until it completes.
Messages a grain sends to itself are admitted regardless of the limit, because Send
is synchronous, and count toward it until they complete. Likewise, the grain’s inbox
accepts them before a handler is registered and processes them once one is.
Once recovery charges a failed handler attempt, the inbox schedules a retry after
RetryInitialInterval multiplied
by an exponential factor that caps at 64. Retries continue until
InboxRetryTimeout (6 hours by
default) after the first failure, so they span transient faults such as outages and
deployments that fix a bug. The last attempt runs when the timeout elapses; if it fails,
the message moves to the inbox dead letters and its ID is recorded as processed. Call
Fail(reason) to dead-letter a message at once.
The outbox removes a message when the receiver reports Accepted, Duplicate, or
DeadLettered. Any other outcome, including a status the sender can’t interpret, such
as one from a newer receiver, leaves the outcome unknown and schedules a durable retry
with the same backoff while other messages continue:
Backpressuredretries within the original absolute delivery budget.HandlerNotFoundlogs an error, and retries give a deployment time to register the handler.- Other failures, such as calls which fail without an answer during an infrastructure outage,
retry like
HandlerNotFound.
OutboxRetryTimeout starts
at the staging time recorded in
SentAt. Each attempt and recovery preserves
that time; retry expiration is SentAt + OutboxRetryTimeout.
No attempt starts after the timeout elapses; the outbox then moves the message to its
dead letters with a reason stating that the retry timeout elapsed. Each attempt
carries the original SentAt.
The receiver checks pending and completed identities first. For an untracked
identity, a send time at or below its non-decreasing admission floor returns
DeliveryResult.Expired before any sink or handler runs.
The outbox retains that message as a dead letter and retires it as DeadLettered:
earlier acceptance may have succeeded with a lost acknowledgement. Stage durable
application reconciliation through the source callback before authorizing another
send. The Durable Jobs clock governs retry scheduling and candidate floor
advancement; the journaled send time and floor preserve admission decisions across
clock changes. OutboxRetryTimeout must be shorter than DeduplicationWindow.
Inspect dead letters through IMessagingDiagnostics and remove handled records with RemoveInboxDeadLetter or RemoveOutboxDeadLetter. Removal becomes durable with the next journal write. Retention settings bound both collections; see Capacity, retries, and retention.
Snapshots advance the admission floor to the later of its current value and
observed Durable Jobs time minus DeduplicationWindow, and compact completed
records whose accepted SentAt is at or below that floor. The floor and
compacted history persist atomically, and in-memory records remain until
acknowledgement.
State, recovery, and deletion
Section titled “State, recovery, and deletion”The inbox and the outbox are each one event-sourced journaling state machine,
registered as orleans.messaging.inbox and orleans.messaging.outbox. They use the
grain’s configured journal format; both the JSON and the Orleans binary formats are
supported.
A fresh activation replays the journal and resumes pending work from the recorded attempt counts and retry times. When messaging fails, for example because staging or persistence fails, it vetoes every later journal write of that activation and the grain deactivates; the next activation recovers the committed outcome from the journal.
After the grain deletes its journal with DeleteStateAsync, the inbox and outbox
start empty and continue to accept and send messages.
Deployment requirements
Section titled “Deployment requirements”Configure Durable Jobs storage and Journaling storage, then enable messaging with AddMessaging on the silo builder or service collection. The optional callback configures DurableMessagingOptions, which are validated at startup. Registration adds Durable Jobs and uses an application-supplied TimeProvider when one is registered.
For development, configure in-memory storage and enable messaging:
siloBuilder.UseInMemoryDurableJobs();siloBuilder.AddVolatileJournalStorage();siloBuilder.AddMessaging();siloBuilder.Services.AddSingleton<Messages>();A grain uses messaging by resolving IInbox or IOutbox during construction or activation setup, typically through constructor injection. Deliveries reach the grain’s inbox through its messaging extension, and journal recovery restores messaging state with the grain’s other journaled state.
The following grain registers a typed handler during activation. The handler
dead-letters a notification without text with Fail(reason), because that input can
never become valid. For a valid notification, it computes an optional reply, sends
it, updates its count, and completes the message before returning:
public interface INotificationGrain : IGrainWithStringKey{ ValueTask<int> GetCount();}
public sealed class NotificationGrain( IInbox inbox, IOutbox outbox, Messages messages, [FromKeyedServices("notification-count")] IDurableValue<int> count) : Grain, INotificationGrain{ public override Task OnActivateAsync(CancellationToken cancellationToken) { inbox.Register(messages.Notify, HandleNotification); return base.OnActivateAsync(cancellationToken); }
public ValueTask<int> GetCount() => new(count.Value);
private void HandleNotification(Notify message, IInboxHandlerContext context) { if (string.IsNullOrWhiteSpace(message.Text)) { context.Fail("A notification requires text."); return; }
var nextCount = checked(count.Value + 1); if (message.ResponseDestination is { } recipient) { outbox.SendReply(messages.NotificationReceived, context, recipient, new NotificationReceived(message.Text, context.Message.Envelope.MessageId)); } count.Value = nextCount; context.Complete(); }}An ordinary grain method stages a typed send with a stable command ID and persists it with one journal write. A client retry with the same command ID stages the same message: the outbox keeps one entry while the message is pending, and the receiver recognizes it as a duplicate after delivery:
public interface INotificationSenderGrain : IGrainWithStringKey{ Task SendAsync(MessageId commandId, GrainId receiver, string message);}
public sealed class NotificationSenderGrain( IOutbox outbox, IDurableStateManager stateManager, Messages messages) : Grain, INotificationSenderGrain{ public async Task SendAsync(MessageId commandId, GrainId receiver, string message) { ArgumentException.ThrowIfNullOrWhiteSpace(message); outbox.Send(messages.Notify, commandId, receiver, new Notify(message)); await stateManager.WriteStateAsync(); }}Use shared, production-grade storage for multi-silo deployments. In-memory Durable Jobs and journal storage support development and tests.
Monitor inbox and outbox depth, retry and dead-letter outcomes, and the age of pending messages. Size admission-floor lag and retry budgets for the workload’s availability and retained-history costs. For metric names and diagnostics, see Operate messaging.
