Skip to content

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.Durable is 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.

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.

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:

DelegateUse
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.

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.

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.

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.

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.

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 false for 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.Delivered when the receiver accepted the message or reported it as a duplicate; OutboxMessageRetirement.Rejected when an inbox sink at the receiver rejected it durably, with the sink’s Reason and application-defined Code; and OutboxMessageRetirement.DeadLettered when the outbox dead-lettered it after its retry timeout, a source failure, or an Expired answer, with its Reason. DeadLettered leaves earlier receiver acceptance unknown. OutboxMessageRetirement and DeliveryResult are C# unions whose cases are classes, so match them with type and property patterns, such as retirement 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 in OnRetired. 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 false for its message, the outbox dead-letters only that entry and retires it as DeadLettered in 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.

  • 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 true from TryAccept and sets its out DeliveryResult to one of these cases; a sink that declines returns false and sets it to default:

    • 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 with new 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 as orders/duplicate-order, and returns them to the sender, whose source receives them in an OutboxMessageRetirement.Rejected retirement. 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 its Send when a sink throws or reports Backpressured. A sink-owned message occupies no inbox capacity, and the sink honors its DeliverAt time. 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 null when 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.

  • 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. Send stages 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 DeliverAt time) 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 returns DeliveryResult.Duplicate when its subject, payload, and DeliverAt time match, and fails when they differ. A repeat of a completed message returns Duplicate while the completion record is retained, or the original DeadLettered reason and code when an inbox sink rejected it. Both records keep the SentAt the inbox accepted, whatever a repeat carries. Once the record is compacted, an untracked message sent at or before the durable floor receives Expired, 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.

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.

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);
}
}

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:

  1. Prepare. Perform asynchronous I/O, validation, decoding, and fallible computation using local values. Observe cancellation before the final phase.
  2. Commit. In one synchronous block, with no await after the first change, send typed outgoing messages, apply the business update, call Complete() or Fail(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 call Complete() 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 outcomeResult
Exception, or return without a terminal operationThe 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 operationThe exception is logged and the staged outcome persists.
Conflicting terminal operationsContract 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.

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:

  • Backpressured retries within the original absolute delivery budget.
  • HandlerNotFound logs 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.

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.

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.